# Defining an ApplicationObject

Once you have created an ArchestrA Object Toolkit project, you can start defining your object. This section explains how to configure object properties and add primitives using the Object Designer, and how to add custom code using the Object Design View. For information on configuring attributes, see Configuring Attributes.

Common steps when defining your object are:

- Configuring the object’s names and description. See Configuring the Object's Names and Description.
- Adding code to the object’s various event handlers. See Configuring Event Handlers.
- Working with primitives to structure your object. See Working with Primitives.
- Adding a custom object editor that allows end users to configure the object in the ArchestrA IDE. See Adding a Custom Object Editor.
- Configuring associated files in case your object uses any external files or assemblies. See Configuring Associated Files.
- Configuring other object properties, including “Advise Only Active” support, the object’s behavior in the ArchestrA IDE, and dump/load or failover support for dynamic attributes. See Configuring Additional Object Properties.
- Adding object help that end users can access from the ArchestrA IDE. See Adding Object Help.

If you have an existing ApplicationObject developed with a previous version of the ArchestrA Object Toolkit, you can easily import its shape by importing the object’s .aaDEF file. For more information, see Importing an .aaDEF File from a Previous Object Version.

You can also configure object properties directly in the code. For more information, see the *ArchestrA Object Toolkit* *Reference Guide*.

## Configuring the Object's Names and Description

You can configure an object’s internal and external names and give it a meaningful description. The *internal name* is the name by which you can refer to the object from within its code. The object’s *external name* and description are used in the ArchestrA IDE. It is also used to create default names for object instances.

You can also configure an object’s vendor name. This name shows the end user who created the object and is used to uniquely identify the object for upgrade purposes.

For more information on ArchestrA naming conventions and restrictions, see Naming Conventions.

> **Note** 
> For brevity, do not use the word “Object” or “Template” in an object’s name.

**To configure an object’s names and description**

1. Open the Object Designer.
2. In the **Shape** pane, click the topmost node. The object properties appear in the **Configuration** pane.
3. In the **External Name** box, enter the object’s external name. The name must be ArchestrA compliant. The maximum length is 31 characters.
4. In the **Internal Name** box, enter the object’s internal name. The name must be C# compliant. The maximum length is 329 characters.
5. In the **Vendor Name** box, enter the vendor name. This name must not contain double-byte characters or any characters that are invalid in Windows file names.
6. In the **Description** box, enter the object description. The maximum length is 1024 characters.
7. Click **OK**.

## Configuring Event Handlers

Event handlers are the main place where you will add the custom code for your ApplicationObject. The object and each of its local primitives have a variety of config time and run time events that you can link with custom handler code. The following sections describe which events exist, and how you can associate them with code.

You can also execute custom code when the value of an attribute is changed at config time or run time. For more information, see Configuring Config Time Set Handlers and Configuring Run Time Set Handlers.

### Configuring Config Time Event Handlers

ArchestrA ApplicationObjects support a number of “config time” events that are triggered when a user works with the object in the ArchestrA IDE. By implementing handlers for these events, you can link configuration actions with custom code. For example, you could execute certain code after an object instance is created.

> **Note** 
> Config time event handler code is executed only on the Galaxy Repository node. Therefore, it cannot directly interact with the user. For example, if you call a message box within an event handler, the message box appears on the Galaxy Repository node.

All ApplicationObjects have the following standard config time event handlers enabled:

| Event | Occurs |
| --- | --- |
| Intialize | When the object is initialized. Use this event handler for any custom initialization code. |
| Migrate | When derived templates or instances are migrated. See Migrating Objects. |
| PostCreate | After the object (instance or derived template) is created. |
| PreValidate | Before the object is validated (when the user has edited its configuration and saves it). |
| Validate | When the object is validated. Use this event handler for any custom validation code (for example, checking for invalid combinations of attribute values). |

**To add code to a config time event handler**

1. In the Object Design View, expand the **Configtime** folder.
2. Double-click the event name. The code section for the config time event handler appears.
3. Enter the code for the config time event handler. When you are done, save your changes.

### Configuring Run Time Event Handlers

ArchestrA ApplicationObjects support a number of run time events that are triggered as the object is executed at run time. By implementing handlers for these events, you can link custom code with these events. For example, you could execute certain code on every scan cycle.

All ApplicationObjects have the following run time event handlers:

| Event | Occurs |
| --- | --- |
| Execute | On every scan cycle of the hosting AppEngine while the object is OnScan. |
| GetStatusDesc | When the run time component requests a detailed message for an error, for example, after a set handler returns a failure. |
| Initialize | After the object is created in run time (usually after deployment, but also after a failover or after the bootstrap is restarted). Occurs before the Startup event. No attribute information is available at this time. |
| SetScanState | When the object’s scan state (OnScan/OffScan) is changed. |
| Shutdown | When the object is shutting down (usually after the object is set to OffScan, but during a failover OffScan may not be set). This event does not occur if the object goes off the network during a network failure. |
| Startup | When the object is being started (after the Initialize event and before it goes OnScan). You can use the event’s startup context to find out whether the object is starting up after a failover or other reasons. |

**To add code to a run time event handler**

1. In the Object Design View, expand the **Runtime** folder.
2. Double-click the event name. The code section for the run time event handler appears.
3. Enter the code for the run time event handler. When you are done, save your changes.

## Working with Primitives

By using primitives, you can structure your object’s code and attributes logically and efficiently. If you define a primitive as virtual, you can also enable or disable instances of it as required at config time. For more information, see Working with Virtual Primitives.

> **Note** 
> When you arrange local primitives in a hierarchy (that is, embed primitives within other primitives, and so on), there is a limit to the number of levels the hierarchy can have. For more information, see Limitations to the Complexity of Primitive Hierarchies.

### Adding a Local Primitive

Local primitives are defined locally in an object and are only used in that single object.

**To add a local primitive**

1. Open the Object Designer.
2. In the **Shape** pane, select the location where you want to add the primitive. For example, if you want to add a primitive to another primitive, select that primitive or one of its attributes.
3. In the **Shape** pane, click the down arrow next to the **Add** icon.
4. Click **Local Primitive**. The properties of the new primitive are shown in the **Configuration** pane.
5. In the **External Name** box, enter a unique external name for the primitive. This is the name by which other objects can access the primitive’s attributes. The name must be ArchestrA compliant. For applicable restrictions, see Naming Conventions.

You can also leave it blank. For more information, see Naming Considerations for Primitives.

6. In the **Internal Name** box, enter a unique internal name for the primitive. This is the name by which you can refer to the primitive in the object’s code. The name must be C# compliant. The maximum length is 329 characters.
7. If required, select the **Dump/Load support for Dynamic** **Attributes & Reusable Primitives** and **Failover support for** **Runtime Dynamic Attributes** check boxes. For more information on these options, see Configuring Dump/Load Support for Dynamic Attributes and Virtual Primitives and Configuring Failover Support for Run Time Dynamic Attributes.
8. Select the **Virtual** check box if the primitive should be virtual. For more information, see Working with Virtual Primitives.
9. If required, select the **Advanced Configuration** check box to specify additional options:
a. In the **Execution Group** list, select the execution group for the primitive. This determines the execution order of the object’s primitives within each scan of the AppEngine. For more information, see Configuring the Object’s Primitive Execution Order.
b. If required, use the **Primitive GUID**, **Package CLSID** and **Runtime CLSID** boxes to specify that the primitive should use other assemblies than the ones automatically generated by the ArchestrA Object Toolkit. For more information, see Associating Different Assemblies with an Object.
1. If required, configure associated files for the primitive. This works the same as configuring associated files for the main ApplicationObject. For more information, see Configuring Associated Files Manually.
2. Click **OK**, or go back to Step 2 to add more primitives.

The Object Design View now shows the new primitive in the tree. It has its own sub-entries for attributes, config time and run time events. You can configure custom code for the primitive’s events and set handlers in the same way as you would configure it for the object itself.

### Adding a Reusable Primitive

A reusable primitive is a primitive that is intended to be included into multiple objects. By implementing common features as reusable primitives, you avoid code duplication. You can also add multiple instances of a reusable primitive to the same object.

Using the ArchestrA Object Toolkit, you can create your own custom reusable primitives. For more information, see Defining a Reusable Primitive.

Standard reusable primitives installed by Wonderware Application Server are available at C:\Program Files\Common Files\ArchestrA\ReusablePrimitives\ ArchestrA.

On a 64-bit operating system, standard reusable primitives will be installed at C:\Program Files (x86)\Common Files\ArchestrA\ReusablePrimitives\ArchestrA.

Technically, the Inputs and Outputs as well as the Alarm and History extensions that you can add in the Object Designer are reusable primitives as well. However, there are separate mechanisms in the Object Designer for adding and configuring these primitives. For more information, see:

- Adding Inputs and Outputs for information on Inputs and Outputs
- Historizing an Attribute for information on the History primitive
- Making an Attribute Alarmable for information on the Alarm primitive

**To add a reusable primitive to your object**

1. Open the Object Designer.
2. In the **Shape** pane, select the location where you want to add the primitive. For example, if you want to add a primitive to another primitive, select that primitive or one of its attributes.
3. In the **Shape** pane, click the down arrow next to the **Add** icon.
4. Click **Reusable Primitive**. The **Add Existing (Predefined)** **Primitive** dialog box appears.
5. Select the .aaPRI file of the reusable primitive you want to add. Click **Open**.
6. The reusable primitive and its attributes appear in the **Shape** pane. The primitive’s properties are shown in the **Configuration** pane.
7. In the **External Name** box, enter a unique external name for the primitive. This is the name by which other objects can access the primitive’s attributes. The name must be ArchestrA compliant. For applicable restrictions, see Naming Conventions.

You can also leave it blank. For more information, see Naming Considerations for Primitives.

8. In the **Internal Name** box, enter a unique internal name for the primitive. This is the name by which you can refer to the primitive in the object’s code. The name must be C# compliant. The maximum length is 329 characters.
9. Select the **Virtual** check box if the primitive should be virtual. For more information, see Working with Virtual Primitives.
10. Click **OK**, or go back to Step 2 to add more primitives.

The Object Design View now shows the new primitive in the tree. Unlike with a local primitive, you can’t configure custom code for the primitive’s events and set handlers because that code is already configured in the reusable primitive itself.

#### Overriding and Locking Attributes of Reusable Primitives

When you include a reusable primitive into another primitive or object, you may be able modify the default values and security classification of its attributes. This is called *overriding*.

When appropriate, you can also lock these overridden values, which prevents them from being changed after the object is imported into a Galaxy. A common example is an object that is designed to monitor only Boolean items from the field. To do so, include an Input Primitive, override its “data type” attribute to Boolean, and lock it.

### Deleting a Primitive

You can delete primitives from your object. In that case, you must check whether the object still contains any references to the deleted primitive or its attributes, and change those references accordingly.

**To delete a primitive**

1. Open the Object Designer.
2. In the **Shape** pane, select the primitive you want to delete.
3. Click the **Delete** icon. A confirmation message appears.
4. Click **Yes** to delete the primitive.

### Working with Virtual Primitives

You can use a *virtual primitive* to implement a block of optional functionality that can be enabled as required by an end user. This ensures that only required primitives are actually deployed at run time, reducing overhead and processing load.

You design and implement a virtual primitive in the same way as any other primitive. However, from the end user’s perspective, a virtual primitive does not appear to be part of the object by default. Instead, it is only made "real" at configuration time by programmatically adding instances of the virtual primitive to the object as needed. For more information, see the documentation on the AddPrimitive and DeletePrimitive methods in the *ArchestrA Object Toolkit* *Reference Guide*.

For example, you might want to provide an optional Hi alarm for an object’s PV (process value). To do this, you would add a virtual primitive that contains the alarming functionality, and an attribute that enables or disables the Hi alarm. When the user enables that attribute at config time, you create an instance of the virtual primitive via a call in the attribute’s config time set handler. If the attribute stays disabled, you never create an instance of the primitive, and the primitive never gets deployed.

You can create multiple instances of a virtual primitive in the same object. Each instance behaves like a separate primitive. For example, you could re-use the same Hi alarm primitive for multiple attributes by simply creating multiple instances of it. However, when you add the instances, you must provide a unique external and internal name for each instance to avoid naming conflicts.

For an example of using virtual primitives, see the WatchDog sample object. It uses a virtual primitive for providing optional statistics calculations. See Sample Projects.

You can also use virtual primitives to define “optional” attributes and “arrays” of related primitives. For more information, see the following sections.

#### Defining "Optional" Attributes Using Virtual Primitives

Using virtual primitives, you can include primitives (and their attributes) in an object only when they are really necessary. For example, if the monitoring of a particular input is optional, you can mark the input primitive as virtual and include it in the object only when a certain attribute (for example, “EnableInputMonitoring”) is set to true. To do this, you would include logic for creating or removing an instance of the virtual primitive in that attribute’s config time set handler.

#### "Arrays" of Related Primitives

Using the same technique as described above, you can easily monitor a variable number of inputs (for example, 0 to 4). The only difference is that you create more than one instance of the virtual primitive. Each primitive instance must have unique internal and external names so its attribute names do not collide with those of the other primitive instances.

### Naming Considerations for Primitives

This section explains how to use a primitive’s names and what happens if you change them.

A primitive has two names: its *internal name* and its *external* *name*. In many cases, these two names will be identical.

- The **internal name** is used to refer to the primitive from config time and run time code. Avoid changing this name after you’ve used it in code. If you do change it, you must manually update any references where the primitive name is passed as a string.

Keep this name as short as possible. Long names can make source file and folder names excessively long, and may increase memory usage at run time.

- The **external name** determines the names of the primitive’s attributes. For example, if you have an attribute named “Condition” in a primitive named “AlarmHi,” you can access the attribute as “AlarmHi.Condition” in the object’s namespace. If you change this name, references in the config time or run time code are not affected. However, you must update any references where it is passed as a string, for example, in the object’s custom editor.

A primitive’s external name can be empty. In this case, the external name does not become part of the namespace that is visible to the end user. In the example above, if you have an attribute named “Condition” in a primitive with an empty external name, you can simply access that attribute as “Condition” in the object’s namespace. However, in that case, you must pay extra attention that no naming conflicts occur between the primitive’s attributes and any attributes of the containing object or primitive.

## Adding a Custom Object Editor

> **Note** 
> This section is about creating the custom object editor for end users to configure your object in the ArchestrA IDE. For information on the ArchestrA Object Toolkit Object Designer that you use to define your object in Visual Studio, see Object Designer Window.

By creating a custom object editor, you provide a graphical interface for configuring your object’s attributes. The custom object editor appears when the user opens the object for configuration in the ArchestrA IDE. It should allow the user to configure all configurable attributes of the object and its primitives.

You can create multiple custom tab pages for your object editor. In the ArchestrA IDE, these custom tab pages appear alongside the standard tab pages that are shown for every object (**Object Information**, **Scripts**, **UDAs**, etc.). You can disable these standard tabs if you don’t need them. See Configuring the Object’s IDE Behavior.

Your custom object editor can use standard controls from the Visual Studio toolbox or special ArchestrA controls. For information on adding the ArchestrA controls to Visual Studio, see Adding ArchestrA Controls to the Visual Studio Toolbox.

Your editor can also include controls for configuring attributes of virtual primitives. In the ArchestrA IDE, these controls are automatically enabled or disabled depending on whether the virtual primitive instance exists or not.

**To create the custom object editor**

1. In the Object Design View, double-click the **Editor** folder. The custom object editor appears in the Visual Studio Design view. It already contains a tab page. This is the first custom tab page that appears when you edit your object in the ArchestrA IDE.
2. Add controls to the tab page. You can use Visual Studio’s standard UI design features for this. You can also:
    - Drag attributes from the Object Design View onto the tab page. The ArchestrA Object Toolkit then automatically adds a standard label as well as ArchestrA controls for editing the value, security classification and lock status of that attribute.
    - Drag object dictionary items from the Object Design View onto the tab page. The ArchestrA Object Toolkit then automatically adds a label that will show the correct localized value at run time.
1. If required, add more tab pages.
2. When you are done, save your work.

### Adding ArchestrA Controls to the Visual Studio Toolbox

You can add special ArchestrA controls to the Visual Studio toolbox so you can use them in your custom object editor.

**To add ArchestrA controls to the Visual Studio toolbox**

1. Right-click the Visual Studio toolbox and then click **Add** **Tab**. A new tab appears in the toolbox. Give it a descriptive name, such as “ArchestrA.”
2. Right-click the new tab and then click **Choose Items**. The **Choose Toolbox Items** window appears with the **.NET** **Components** tab selected.
3. Click **Browse**. Browse to the C:\Program Files\Wonderware\Toolkits\ArchestrA Object\Bin folder and select the ArchestraEditorFramework.dll file.

On a 64-bit operating system, browse to the C:\Program Files (x86)\Wonderware\Toolkits\ArchestrA Object\Bin folder to select the file.

4. Click **Open**. The ArchestrA controls are added to the list of controls.
5. In the **Name** column, check those ArchestrA controls that you want to see on your new tab. Click **OK**.

The ArchestrA controls now appear on your new tab in the Visual Studio toolbox.

### Changing the Attribute Reference of ArchestrA Controls

You can change the attribute references of ArchestrA controls after you have added them to your object editor. To do this, set the control’s “Attribute” property to the external name of the attribute. You can also do this programmatically from config time code. This allows you, among other things, to configure multiple primitive instances using the same editor page.

For example, to set the attribute reference of the control instance “aaTextBox1” to “Prim1.Attr1”, use this statement:

```csharp
aaTextBox1.Attribute = "Prim1.Attr1";
```

## Configuring Associated Files

If your project contains references to custom files or libraries/assemblies, you must associate these “dependent files” with the object definition. This ensures that they are included when you build the object. The associated files become part of the .aaPDF object package file. When you later import the object on the target system, each associated file is automatically registered on that system based on its type.

If you know that the required files will already be present on the target system, you can also tell the ArchestrA Object Toolkit to specifically ignore these files. In that case, the files are not included in the object package. This is handy for references to standard Windows or ArchestrA assemblies.

There are two ways to configure associated files:

- For files that *are* set up as references in Visual Studio (for example, custom or third-party assemblies), you set up rules using the Dependent File Manager. Rules are regular expressions that can cover multiple references. All files covered by a rule are then automatically added to the object’s **Associated Files** list. You must set up rules for all project references that you have set up in Visual Studio before you can build your object.
- For files that *are not* set up as project references in Visual Studio (for example, custom data files), you set up the association manually in the Object Designer’s **Associated** **Files** list.

The following sections explain both options.

### Setting up Rules for Dependent Files

To associate files with your object that are set up as project references in Visual Studio (for example, custom or third-party assemblies), you set up rules using the Dependent File Manager. Rules are regular expressions that can cover multiple references. All files that are linked to the references covered by a rule are automatically added to the object’s **Associated Files** list.

> **Note** 
> The file and folder names of associated files must not contain any multi-byte characters.

You can configure a default set of rules for all projects, and you can configure specific rules for a single project.

- When you open the Dependent File Manager while no ArchestrA Object Toolkit project is opened, you can configure only the default rules for all projects.
- When you open the Dependent File Manager while an ArchestrA Object Toolkit project is opened, you can configure both the default rules for all projects as well as specific rules for the current project.

You can set up rules before or after you have added the relevant references to your project in Visual Studio. In the latter case, the references automatically appear in the Dependent File Manager, and you can create rules for them very easily without having to type the reference again. See the following two sections for each method.

Rules are checked in the order that they appear in the Dependent File Manager. After the ArchestrA Object Toolkit finds a rule that matches a particular reference, it ignores any subsequent rules that might also match that reference.

You can also configure additional search paths for dependent files. See Configuring Additional Search Paths.

> **Note** 
> The **System** folder of the Dependent File Manager always contains a set of default rules for references to core system libraries. You can’t edit the rules in this folder.

#### Setting up Rules for References that Don't Currently Exist in Visual Studio

To set up rules for dependent files that you haven’t yet added as references in Visual Studio, use the following procedure.

**To set up rules for dependent files manually**

1. Click the **Dependent File Manager** icon in the ArchestrA Object Toolkit toolbar. The **Dependent File Manager** dialog box appears.
2. Create a rule.
a. In the **Rules** list, click either **This Object** or **All Objects**, depending on where you want the rule to apply.
b. Click the **Add** icon. A new rule appears in the list.
c. In the **Reference** box on the right, enter the reference expression to which this rule should apply. This can be a .NET regular expression. For example, if you are using references to “MyMathLib.Core.dll” and “MyMathLib.Data.dll,” you can enter “MyMathLib*” to cover both.
d. Select the **Ignore** check box if the dependent file(s) covered by this rule should be ignored. In that case, the files are not added to the object package file generated by the build process. Use this option if you know that the files will already be present on the target system.
e. In the **Vendor** box, enter the vendor name for the file(s).
f. In the **Type** list, select the file type. This determines if and how files covered by this rule are registered on the target system. The types work as follows:

| Type | Description |
| --- | --- |
| Dictionary | An ArchestrA Dictionary (.aaDCT) file. |
| NETFrameworkAssembly | Strongly named .NET Framework Assembly. The file is installed into the Global Assembly Cache. |
| ComDLL | COM in-proc server DLL. The file is registered on the target system using regsvr32. |
| Normal | A normal file. Nothing is done on the target system except install the file. |
| ComEXE | COM local server EXE. The file is executed on the target system with the "/RegServer" parameter. |
| NTService | A file that runs as a Windows service. |
| MergeRegistryScript | A .reg file with registry information. The file is imported into the registry. |
| MsiMergeModule | A bundled subcomponent of an installer. |
| NETFrameworkAssemblyNIG | .NET Framework Assembly. The file is *not* installed into the Global Assembly Cache. |
| Unknown | Only applicable if you selected the **Ignore** check box. |

a. Leave the **Browser** check box unchanged. This feature is reserved for future use.
b. Select the **Contains Embedded DEF** check box if the file contains the object’s aaDEF file as an embedded resource. Typically, you don’t need to use this setting because the aaDEF file is managed by the ArchestrA Object Toolkit automatically.
1. If the dependent files covered by the rule require dependent files themselves, add each of those files to the rule. For example, if you are using a COM DLL, the reference in the project is actually to the auto-generated interop assembly, but not the COM DLL itself. In that case, you would add the actual COM DLL file as a dependent file to the rule. Do the following for each file:
a. In the **Rules** list, select the rule.
b. Click the **Add** icon. A new file item appears in the list.
c. In the **Reference** box on the right, enter the complete path to the file, or click the browse button to select the file.
d. Configure the remaining options as described in the previous step.
1. Click **OK**, or go back to step 2 to create more rules.

#### Setting up Rules for References that Currently Exist in Visual Studio

To set up rules for dependent files that you have already configured as references in Visual Studio, use the following procedure.

**To set up a rule for a reference already set up in Visual Studio**

1. Click the **Dependent File Manager** icon in the ArchestrA Object Toolkit toolbar. The **Dependent File Manager** dialog box appears.
2. In the **Dependent Files** list, select the reference for which you want to set up a rule. References not currently covered by a rule are highlighted in black type.
3. Click either the **All Objects** or **This Object** button, depending on where you want the rule to apply. A new rule for this reference appears in the corresponding section of the **Rules** list.
4. Configure the remaining options as described in the previous procedure.

#### Deleting and Re-Ordering Rules

You can edit the rules list by deleting rules or changing their order.

**To delete or re-order rules**

1. Open the **Dependent File Manager**.
2. In the **Rules** list, select the desired rule.
3. Do one of the following:
    - To delete the rule, click the **Delete** icon.
    - To move the rule up or down in the list, click the arrow icons.
1. Click **OK**.

#### Managing the Rules File for All Projects

The default dependent files rules for all projects are stored in an XML file. You can specify which file to use. This allows you to save and use different sets of default rules.

**To manage the rules file for all projects**

1. Open the Dependent File Manager.
2. In the **All Objects Rules** area, manage the rules file as follows:
    - To open a different rules file, click the browse button next to the **All Objects Rules File** box.
    - To save the current rules configuration under the file name that is shown, click **Save**.
    - To save the current rules configuration under a different file name, click the down arrow on the **Save** button and then select **Save As.**
    - To set the currently shown file as the default file, click **Set Default**.
    - To use the file that is set as the default file, click **Default**.

### Configuring Associated Files Manually

To associate files with your object that are not set up as project references in Visual Studio (for example, custom data files), you set up the association manually in the Object Designer’s **Associated Files** list. Files listed here are included in the object package file when you build the object, and optionally registered on the target system when you import the object.

**To manually add associated files**

1. Open the Object Designer.
2. In the **Shape** pane, click the topmost node. The object properties appear in the **Configuration** pane.
3. Click the downward arrow to the right of the **Associated** **Files** heading. The section expands.
4. Click the **Add** icon. The **Associated File** dialog box appears.
5. In the **Filename** box, enter the complete path to the file, or click the browse button to select the file.
6. In the **Type** list, select the file type. This determines if and how files covered by this rule are registered on the target system. The types work as follows:

| Type | Description |
| --- | --- |
| Dictionary | An ArchestrA Dictionary (.aaDCT) file. |
| NETFrameworkAssembly | Strongly named .NET Framework Assembly. The file is installed into the Global Assembly Cache. |
| ComDLL | COM in-proc server DLL. The file is registered on the target system using regsvr32. |
| Normal | A normal file. Nothing is done on the target system except install the file. |
| ComEXE | COM local server EXE. The file is executed on the target system with the "/RegServer" parameter. |
| NTService | A file that runs as a Windows service. |
| MergeRegistryScript | A .reg file with registry information. The file is imported into the registry. |
| MsiMergeModule | A bundled subcomponent of an installer. |
| NETFrameworkAssemblyNIG | .NET Framework Assembly. The file is *not* installed into the Global Assembly Cache. |

1. In the **Vendor** box, enter the vendor name for the file(s).
2. Select the **Needed at Config time**, **Needed at Run time** and **Needed by the Editor** check boxes depending on which components of your object use the file.
3. Leave the **Needed by the Browser** check box unchanged. This feature is reserved for future use.
4. Select the **Contains Embedded DEF** check box if the file contains the object’s aaDEF file as an embedded resource. Typically, you don’t need to use this setting because the aaDEF file is managed by the ArchestrA Object Toolkit automatically.
5. Click **OK**.

**To edit or delete an associated file**

> **Note** 
> You can only edit or delete files that you manually added to the Associated Files list. To edit or delete a file that was added through a rule, use the Dependent File Manager.

1. Open the **Associated Files** list.
2. Select the file you want to edit or delete.
3. Do one of the following:
    - To edit the file, click the **Edit** icon. The **Associated File** dialog box appears. Edit the properties as described in the previous procedure.
    - To delete the file, click the **Delete** icon and confirm the deletion.

## Configuring Additional Object Properties

You can configure various additional properties for your ApplicationObject:

- You can enable dump/load support for dynamic attributes and virtual primitives as well as failover support for dynamic attributes. See Configuring Dump/Load Support for Dynamic Attributes and Virtual Primitives and Configuring Failover Support for Run Time Dynamic Attributes.
- You can enable “Advise Only Active” support for the object to reduce processing and network load when its attributes aren’t subscribed to. See Enabling “Advise Only Active” Support for the Object.
- You can set a minimum Application Server version to prevent users from importing your object into earlier versions. See Configuring the Object’s Minimum Application Server Version.
- You can set IDE Behavior options to control various aspects of the object’s behavior in the ArchestrA IDE. See Configuring the Object’s IDE Behavior.
- You can set the toolset that the object should be placed in when it is imported into the ArchestrA IDE. See Setting the Object’s Toolset.
- You can specify the execution order for the object’s primitives. See Configuring the Object’s Primitive Execution Order.

The following sections explain each of these additional properties.

### Configuring Dump/Load Support for Dynamic Attributes and Virtual Primitives

You can enable dump/load support for config time dynamic attributes and virtual primitives in instances or derived templates of your ApplicationObject. These attributes and primitive instances are only added and configured at config time, so their status and configuration may be different in each object instance or derived template. Enabling dump/load support allows you to preserve this configuration when using the Galaxy Dump/Load and Export/Import features on those instances or derived templates.

The dump/load support setting always applies to a specific hierarchy level. For example, when you enable it on the top hierarchy level of your ApplicationObject, it applies to dynamic attributes and virtual primitive instances created on that level. If your object uses child primitives, you must configure the setting separately for each of those primitives.

Using the detailed AddAttribute and AddPrimitive methods, you can exclude specific dynamic attributes or virtual primitives from the dump/load support. For more information, see the *ArchestrA Object Toolkit* *Reference* *Guide*.

> **Important** 
> When you enable dump/load support, the ArchestrA Object Toolkit automatically adds an attribute named “InternalDumpLoadData1” to the object. Do not edit or remove this attribute. Otherwise, the dump/load support doesn’t work.

**To enable dump/load support**

1. Open the Object Designer.
2. In the **Shape** pane, click the object name.
3. In the **Configuration** pane, select the **Dump/Load support** **for Dynamic Attributes & Virtual Primitives** check box.
4. Click **OK**.

### Configuring Failover Support for Run Time Dynamic Attributes

You can enable failover support for run time dynamic attributes. This is relevant when using your ApplicationObject in a redundant environment with dual ApplicationEngines configured for failover. In such an environment, when the primary AppEngine fails, all of its hosted objects become available on the backup AppEngine.

When failover support is enabled, any dynamic attributes created on your object during run time are preserved in case of such a failover. Otherwise, run time dynamic attributes are lost when the failover occurs and have to be recreated.

The failover support setting always applies to a specific hierarchy level. For example, when you enable it on the top hierarchy level of your ApplicationObject, it applies to dynamic attributes created on that level. If your object uses child primitives, you must configure the setting separately for each of those primitives.

Using the detailed AddAttribute method, you can exclude specific dynamic attributes from the failover support. For more information, see the *ArchestrA Object Toolkit* *Reference* *Guide*.

You can also use failover support to restore dynamic attributes after a normal object startup, not just after a failover. For additional information and guidelines, see Ensuring Failover Support for Run Time Dynamic Attributes.

> **Important** 
> When you enable failover support, the ArchestrA Object Toolkit automatically adds an attribute named “_InternalFailoverData1” to the object. Do not edit or remove this attribute. Otherwise, the failover support doesn’t work.

**To enable failover support**

1. Open the Object Designer.
2. In the **Shape** pane, click the object name.
3. In the **Configuration** pane, select the **Failover support for** **Runtime Dynamic Attributes** check box.
4. Click **OK**.

### Enabling "Advise Only Active" Support for the Object

You can enable “Advise Only Active” support for your ApplicationObject. When “Advise Only Active” support is enabled, you can configure individual attributes to stop updating if noone is subscribing to them. This reduces the processing and network load.

After enabling “Advise Only Active” support for the object, you still need to configure each individual attribute for “Advise Only Active” support as required. For more information, see Configuring “Advise Only Active” Support for an Attribute.

**To enable “Advise Only Active” support for the object**

1. Open the Object Designer.
2. In the **Shape** pane, click the object name.
3. In the **Configuration** pane, select the **Advise only Active** **supported** check box.
4. Click **OK**.

### Configuring the Object's Minimum Application Server Version

You can configure a minimum Application Server version for your ApplicationObject. This prevents users from importing the object into earlier versions of Application Server.

> **Note** 
> This version check is only performed in Application Server 3.1 and higher.

**To configure the minimum Application Server version**

1. Open the Object Designer.
2. In the **Shape** pane, click the object name.
3. In the **Configuration** pane, enter the minimum version in the **Min IAS Version** and **Patch** boxes.
4. Click **OK**.

### Configuring the Object's IDE Behavior

You can customize the object’s behavior in the ArchestrA IDE. For example, you can hide the object from certain views and disable some commands.

**To configure the object’s IDE behavior**

1. Open the Object Designer.
2. In the **Shape** pane, click the object name.
3. In the **Configuration** pane, select the **IDE Behavior** check box. A list of options appears.
4. In the **General** area, select the check boxes for the general options you want to enable:
    - **Hide Tagname:** Hides the object’s tagname in the ArchestrA IDE views (Model, Deployment, Derivation). This option is only applicable if the object is contained. Otherwise, the tagname is shown even if this option is enabled. When the object’s tagname is hidden, users can only change its contained name in the ArchestrA IDE.
    - **Hide Contained Name:** Hides the object’s contained name in the ArchestrA IDE views.
    - **Disable ObjectViewer Menu:** Disables the **View in** **Object Viewer** menu option in the ArchestrA IDE.
    - **Disable Template Derivation:** Makes it impossible to derive templates from the object.
    - **Disable Instance Creation:** Makes it impossible to derive instances from the object.
    - **Hide Standard Editor Tabs:** Hides the standard tabs (**Object Information**, **Scripts**, **UDAs**, etc.) in the custom object editor. Only your custom tabs are shown.
1. In the **Appearance** area, select the check boxes for the appearance options you want to enable:
    - **Hide in Browser:** Hides the object in the Galaxy Browser.
    - **Hide Template in Template Toolbox:** Hides the object template in the **Template Toolbox**.
    - **Hide Instance in Model View:** Hides the object’s instances in the **Model** view.
    - **Hide Instance in Deployment View:** Hides the object’s instances in the **Deployment** view.
    - **Hide in Security Editor Object List:** Hides the object from the security group configuration (**Security Groups** tab in the **Configure Security** dialog box).
1. Click **OK**.

### Setting the Object's Toolset

You can specify which toolset the object is placed in when you import the object into the ArchestrA IDE.

> **Note** 
> You can configure the list of toolsets available for selection. See Configuring Toolset Names.

**To set the object’s toolset**

1. Open the Object Designer.
2. In the **Shape** pane, click the object name. The object properties appear in the **Configuration** pane.
3. In the **Toolset** list, click the toolset that the object should be placed in after importing. Alternatively, type a custom toolset name.
4. Click **OK**.

#### Configuring Toolset Names

You can configure the toolsets that you can select for your objects in the Object Designer. Toolset names are saved in an XML file and apply to all ArchestrA Object Toolkit projects on your system. You can also save this file in a central network location and share it across multiple systems.

**To configure toolset names**

1. In the ArchestrA Object Toolkit toolbar, click the **Options** icon. The **Options** dialog box appears.
2. In the left pane, click **Toolset Names**. The toolset list appears in the right pane. Default toolsets appear with a blue icon. You can’t edit these toolsets.
3. Configure the toolset names as follows:
    - To add a toolset, click the **Add** icon and then click Toolset. In the **Name** box, enter a name for the toolset. The name must be ArchestrA compliant.
    - To delete a toolset, select it, click the **Delete** icon, and confirm the deletion.
    - To save the toolset names file or to open a different one, use the **Save** and browse buttons.
    - To save the current rules configuration under a different file name, click the down arrow on the **Save** button and then select **Save As.**
    - To set the currently shown file as the default file, click **Set Default**.
    - To use the default file, click **Default**.
1. Click **OK**.

### Configuring the Object's Primitive Execution Order

You can configure an execution order for the primitives in an ApplicationObject by specifying one of ten execution groups for each primitive. The execution group specifies the order in which the primitive should be executed relative to other primitives in the object. For example, if primitive B depends on data calculated by primitive A, you would want to make sure that primitive A is executed before primitive B so that primitive B gets the latest data in each scan cycle of the AppEngine. To do this, you would place primitive A in an “earlier” execution group than primitive B.

Available execution groups are “Custom 1” to “Custom 10.” Primitives in the “Custom 1” group are executed first, then primitives in the “Custom 2” group, and so on.

Technically, all code that you implement at the ApplicationObject level, such as the object’s own Startup or Execute event handlers, is contained in a special primitive as well. Therefore, you can also set an execution group at the object level to specify when that code should be executed relative to the code of other primitives in the object.

> **Note** 
> You can configure the execution group of a reusable primitive when you develop the primitive, but you can’t change it after you have embedded the primitive in an ApplicationObject.

**To configure the object’s primitive execution order**

1. Open the Object Designer.
2. In the **Shape** pane, click the object name or a primitive. The object or primitive properties appear in the **Configuration** pane.
3. Select the **Advanced Configuration** check box. The **Advanced Configuration** section expands.
4. In the **Execution Group** list, select the execution group for the primitive.
5. Click **OK**.

## Associating Different Assemblies with an Object

An ApplicationObject consists of a number of different assemblies. For example, there is one assembly for config time code and another for run time code. These assemblies are tied to the main ApplicationObject by means of their CLSIDs.

By default, when you create a new ArchestrA Object Toolkit project, the ArchestrA Object Toolkit automatically generates a project folder with subfolders and code files for each of these assemblies (see Creating a Project). These are the files that you open and edit as you work with the Object Designer and Object Design View.

Initially, the ArchestrA Object Toolkit automatically configures the CLSIDs so that your object uses these new default assemblies. However, you can change these auto-configured CLSIDs to specify that your object should *not* use these default assemblies, but different ones.

In most circumstances, if you’re creating an object completely from scratch in the current version of the ArchestrA Object Toolkit, you would not change the CLSID configuration, but simply keep the default values. But, for example, there might be situations where you would want to use an existing run time assembly that you created by some other means, such as a previous version of the ArchestrA Object Toolkit. By specifying that assembly’s CLSID, you can tell your ApplicationObject to use that assembly instead of the default assembly that’s part of the ArchestrA Object Toolkit project.

If you change the CLSID configuration to use custom assemblies, you must manually include these assemblies as associated files so that they are installed and registered on the target system. For more information, see Configuring Associated Files.

> **Note** 
> Every time you increment your object’s major version, the CLSID configuration for the object and all child primitives is automatically reset to new, auto-generated values. Therefore, if you are using custom CLSIDs, you must restore them after each major version update.

**To change an object’s CLSID configuration**

1. Open the Object Designer.
2. In the **Shape** pane, click the object name. The object properties appear in the **Configuration** pane.
3. Select the **Advanced Configuration** check box. The **Advanced Configuration** section expands.
4. Enter the assembly CLSIDs as follows:
a. **Primitive GUID**: GUID of the main object assembly. Usually you won’t have to change this GUID.
b. **Package CLSID**: CLSID of the assembly that contains the config time code
c. **Runtime CLSID**: CLSID of the assembly that contains the run time code
d. **BRO CLSID**: Reserved for future use. Do not change this setting.
1. Click **OK**.

## Adding Object Help

The ArchestrA Object Toolkit does not provide a means to add object help to your object. However, you can use the standard means of the ArchestrA IDE to do this, and then export the object including the object help as an .aaPKG file.

Your object help file must be a standard HTML file.

**To add object help**

1. Develop and test your object as usual.
2. Open the ArchestrA IDE and import your object’s .aaPDF file. The object template is now shown in the **Template** **Toolbox**.
3. Right-click the object template and select **Object Help**. The help window appears with a message that no object help file could be found.
4. Save your object help file under the name shown in the error message. For example, if the message says that no help file was found at “C:\Program Files\ArchestrA\Framework\FileRepository\MyGalaxy\Objects\551\Help\1033\help.htm,” save the help file in that folder and under that name.
5. Close the help window. Repeat step 3 to verify that your help file now appears.
6. Export your object as an .aaPKG file.

The exported .aaPKG file now contains your original object as well as the help file that you manually copied into the help folder. When you import the .aaPKG file into a different galaxy, the help file is automatically imported and saved at the correct location.

## Importing an .aaDEF File from a Previous Object Version

If you have an existing ApplicationObject developed with a previous version of the ArchestrA Object Toolkit, you can easily re-create its shape by importing the object’s .aaDEF file. This saves time because you can reuse the existing object shape.

To use this feature, you must use a newly created ArchestrA Object Toolkit project for which you haven’t defined any attributes or primitives yet. Otherwise, the .aaDEF import is disabled.

**To import an existing .aaDEF file**

1. Open the Object Designer.
2. Click the **Import aaDEF** button in the bottom. The **Browse** **for AADef Files** dialog box appears.
3. Select the .aaDEF file you want to import and click **Open**.

The ArchestrA Object Toolkit imports the .aaDEF file. When the import is finished, the Object Designer shows the object shape as defined in the .aaDEF file.
