Joseph Doherty
32f26272ae
Five tools under one repo, all docs organized per DOCS-GUIDE.md: - aalogcli: .NET 4.8 / x86 CliFx CLI for reading System Platform binary logs (*.aaLGX) for LLM debugging, built on aaOpenSource/aaLog. Commands: last, tail, range, unread, fields. Stable JSON envelope under --llm-json. Build template under lib/build/ for rebuilding aaLogReader.dll. - aot: ArchestrA Object Toolkit 2014 v4.0 reference material. Dev guide (Markdown converted from CHM), API reference for the ArchestrA.Toolkit namespace, and the Monitor / Watchdog VS sample solutions. - graccesscli: .NET 4.8 / x86 CliFx CLI that automates Galaxy configuration via the ArchestrA GRAccess COM interop. Includes session daemon, IPC protocol, and llm-json envelope contract. - grdb: SQL/DDL exploration of the Galaxy Repository database. DDL captures, reusable queries, hierarchy / contained-name <-> tag-name translation notes. - histdb: LLM-oriented reference for AVEVA Historian retrieval. INSQL linked-server, extension tables, every wwXxx time-domain extension, every retrieval mode, alarm/event SQL recipes, REST API. Distilled from the 243-page Historian Retrieval Guide. Root contains: - CLAUDE.md: thin index pointing into each tool's README. - DOCS-GUIDE.md: doctrine for organizing docs for LLM consumption. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
12 KiB
Overview and Concepts
This section gives you a general overview of the Wonderware ArchestrA Object Toolkit and its features. We recommend that you read this section in its entirety to familiarize yourself with the key concepts, and then continue with the other sections for detailed information on specific tasks.
About the ArchestrA Object Toolkit
The ArchestrA Object Toolkit is an add-on to Microsoft Visual Studio that lets you create custom ArchestrA ApplicationObjects in C# code. It provides an easy-to-use graphical Object Designer while still giving you full control over the object’s source code.
Using the ArchestrA Object Toolkit, you can:
- Create custom ApplicationObjects for use in Wonderware Application Server without having to deal with its internals.
- Create a custom editor for your object that allows your users to easily configure the object’s attributes using the Application Server IDE.
- Create reusable primitives, code modules that you can reuse in multiple custom ApplicationObjects.
- Easily navigate to all sections of your object’s code using an Object Design View.
- Configure object attributes using an easy-to-use Object Designer.
- Build .aaPDF files and automatically import, instantiate and deploy them in your Galaxy for testing.
Note
You cannot create DeviceIntegration Objects with this release of the ArchestrA Object Toolkit. For information on creating DeviceIntegration Objects, contact your Wonderware distributor.
About ApplicationObjects and Primitives
ApplicationObjects are domain-specific objects that represent plant equipment and instrumentation such as pumps, valves, temperature transmitters, or conveyors. They usually get their source data from other objects, such as DeviceIntegration objects.
Wonderware Application Server already includes some basic ApplicationObject templates, such as the $AnalogDevice object for a simple analog device. Using the ArchestrA Object Toolkit, you can create complex custom ApplicationObjects that represent specific types of equipment, for example, a pump system. These ApplicationObjects support various events that allow you to execute custom config time and run time code. You can also create a custom object editor for easy configuration.
Attributes are the data items of an ApplicationObject or primitive. By reading from and writing to attributes, objects can exchange data with each other. (Unless specifically noted, when this manual talks about “attributes,” we mean these ArchestrA attributes, not C# attributes.)
Primitives are modules containing code and attributes. Like the main ApplicationObject, they have their own config time and run time event handlers as well. You can think of them as the “building blocks” for your object. By “modularizing” your object into primitives, you can create a clear, logical structure and dynamically enable or disable functionality as needed. There are two types of primitives:
- Local primitives are defined locally in an object and are only used in that single object.
- Reusable primitives are “stand-alone” primitives that can be reused in multiple ApplicationObjects. Organizing common functionality into reusable primitives makes it easier to maintain your code. The ArchestrA Object Toolkit includes predefined utility primitives for various tasks, such as historizing values to a database. You can also create custom reusable primitives for your objects.
Both local and reusable primitives can be made “virtual.” This allows you to dynamically add and delete instances of the primitive at config time. If you don’t add any instances of the primitive, it doesn’t become part of the object instance and is not deployed at run time. This reduces the run time processing load because only the functionality that is actually needed gets deployed.
All ApplicationObjects automatically contain the “Common” primitive, which provides common attributes and functionality that all objects need (for example, attributes for setting the object OnScan/OffScan, etc.) The Common primitive is hidden, and you can’t edit it in any way.
For example, a simple ApplicationObject might have the following structure:
The structure of an ApplicationObject or primitive, as composed of its attributes and child primitives, is also called its “shape.”
Workflow: Creating an ApplicationObject or Reusable Primitive
The basic steps to create an ApplicationObject or reusable primitive are as follows:
- Planning. When developing an ApplicationObject, you should consider certain requirements and best practices. For more information, see Object Design Considerations.
- Creating a project in Visual Studio. Working with an ArchestrA Object Toolkit project is similar to working with other projects in Visual Studio. For more information, see Working with Projects.
- Internationalizing the object (optional). If your object will be used in different localized environments, you can define multilingual strings for your object’s messages and other text. At run time, the object can then use the appropriate local language strings for the environment it’s used in. It is best to internationalize any required messages right from the start and then refer to them as required as you write your code. For more information, see Internationalizing Objects.
- Defining the object or primitive. In this step, you configure basic object properties and add the attributes (data items) that your object or primitive will use. You also add any code procedures that your object will need, such as run time set handlers or event handlers. Finally, you create a custom object editor that your users can use to configure the object’s properties in the Application Server IDE.
For more information on defining ApplicationObjects and reusable primitives, see Defining an ApplicationObject, and Defining a Reusable Primitive. For information on configuring attributes, see Configuring Attributes.
When coding your object, follow the “best practices” and guidelines outlined in Development Best Practices.
- Building the object. In this step, you create an .aaPDF object file that contains your custom ApplicationObject (or an .aaPRI file if you’re developing a reusable primitive). You can then import and use the object in Application Server. You can also import, instantiate and deploy the object automatically as part of the build process, and you can configure various build options. For more information, see Building and Versioning Objects.
- Testing and debugging the object. If you encounter problems while testing your object, see Debugging Objects, for troubleshooting hints.
The ArchestrA Object Toolkit includes some sample projects to help you get started. For more information, see Sample Projects.
Important
To build objects, you must run Visual Studio with administrative privileges.
Tour of the User Interface
The user interface of the ArchestrA Object Toolkit consists of:
- Additions to the regular Microsoft Visual Studio user interface: a toolbar, an Object Design View and a Logger view. By default, these are always visible when an ArchestrA Object Toolkit project is opened in Visual Studio.
- An Object Designer window that you can open and close as required while working with an ArchestrA Object Toolkit project.
The following sections describe each of these components.
Additions to the Visual Studio Interface
When you create or open an ArchestrA Object Toolkit project in Visual Studio, the Visual Studio environment shows extra items.
Note
When you create your first project after installing the ArchestrA Object Toolkit, the Object Design View and Logger View are not docked. We recommend that you dock the Object Design View to the left of the Visual Studio window, and the Logger view to the bottom (as shown above).
ArchestrA Object Toolkit Toolbar
The ArchestrA Object Toolkit toolbar lets you access all main features of the ArchestrA Object Toolkit. The individual features and icons are described throughout this documentation.
Object Design View
The Object Design View allows you to easily navigate your object’s code. Double-clicking on an item in the Object Design View automatically opens the code section that controls the respective aspect of your object. For example, the Object Design View might look like this:
- Attributes: Double-click an attribute name to see its definition in the code.
- Attribute set handlers and “Advise Only Active” code: Double-click Configtime Set Handler or Runtime Set Handler to open the code section that contains the config time or run time set handler for an attribute (if enabled). Double-click Advise only Active to open the “Advise only Active” code section for an attribute (if enabled)
- Config time/run time events: Double-click an event name to open the code section linked to the event. Once you have added custom code for an event, its name is shown in bold type.
- Custom editor: Double-click Editor to open the object’s custom editor in the Visual Studio design view.
- Object dictionary: Double-click Dictionary to edit the object dictionary. Expand this item to see the content of the dictionary.
To refresh the Object Design View after making changes to the code, click its Refresh icon. This automatically validates the code as well.
To hide or re-open the Object Design View, click the Object Design View icon in the ArchestrA Object Toolkit toolbar.
Logger View
The Logger view shows the same ArchestrA Logger messages that you would see in the ArchestrA Log Viewer. Check this view for any errors and warnings that may be reported by the ArchestrA Object Toolkit. The Logger view is intended for quick reference. It does not offer the full functionality of the ArchestrA Log Viewer.
To hide or re-open the Logger View, click the Logger View icon in the ArchestrA Object Toolkit toolbar.
Object Designer Window
The Object Designer lets you easily edit and configure your object’s general properties, attributes and primitives. We recommend that you edit your objects using this editor. However, you can always edit all aspects of your object directly in the underlying code.
The code and the data you see in the Object Designer are always synchronized. For example, when you change the properties of an attribute in the code, you see the updated property values the next time you open the Object Designer, and vice versa.
Opening the Object Designer
You can open and close the Object Designer as required while working with your project. You can also have the Object Designer open automatically when you open an ArchestrA Object Toolkit project in Visual Studio.
To open the Object Designer
- Click the Object Designer icon in the ArchestrA Object Toolkit toolbar.
To have the Object Designer open automatically when opening a project
- Open the Object Designer.
- In the bottom left corner of the Object Designer, select the Automatically launch editor check box.
- Click OK.
Object Designer Panes
The Object Designer contains the following panes:
- Shape pane: This pane shows the structure (“shape”) of your object. You can edit your object here by adding and deleting attributes and primitives.
- Configuration pane: Use this pane to configure the item that is currently selected in the Shape pane.
- Attributes pane: This pane shows a list of all custom attributes in your object, including their configuration. You can expand this pane to see more information at once. Also, you can choose to see config time or run time attributes only. The abbreviated column headings mean the following:
| Heading | Description |
|---|---|
| FA | “Frequently Accessed” option is enabled |
| CQ | “Calculated Quality” option is enabled |
| Cfg | Config time set handler is enabled |
| Run | Run time set handler is enabled |
| Al | Attribute is alarmed |
| His | Attribute is historized |