wwtools/aot/dev-guide/08-building-and-versioning.md

Building and Versioning Objects

By building your object, you create an .aaPDF object file that you can import and use in Wonderware Application Server. You can:

• Configure build options. You can configure various options concerning the build process.
• Validate your object. This allows you to find errors that would cause problems when building or using the object but that can’t be discovered by Visual Studio’s standard checking process.
• Manage object versions. You can specify whether to increment the object’s major or minor version with a build. You can also override the auto-generated version number in the object properties.
• Start the build process. The ArchestrA Object Toolkit can automatically import, instantiate and deploy the object as part of the build process.
• Analysing migration requirements. If you are developing a new version of an existing object, the ArchestrA Object Toolkit can help you to structure the code for migrating the existing object.

Validating an Object

Validating an object allows you to find errors that would cause problems when building or using the object but that can’t be discovered by Visual Studio’s standard checking process. This is particularly important if you have edited the object’s code directly. For example, you might try to assign a value of an invalid type to an attribute. This type of error is invisible to Visual Studio, but can be discovered by validating the object.

Your object is validated automatically when:

• You open the Object Designer.
• You build the object.
• You refresh the Object Design View.

You can also start validation manually.

The validation process reports any warnings and errors in the Logger view and, where appropriate, tries to fix the underlying issues. The warning and error messages are self-explanatory, so they are not duplicated here.

If the validation process detects any errors, you must fix them before you can build or debug the object, use the Migrate analysis, open the Object Designer, or update the Object Design View. These features are disabled until you fix the errors and revalidate the object.

To start validation manually

1. In the ArchestrA Object Toolkit toolbar, click the Validate icon.

Configuring Build Options

You can configure build options for all ArchestrA Object Toolkit projects or just the current project.

• When you configure build options while no ArchestrA Object Toolkit project is opened, they apply as defaults for all ArchestrA Object Toolkit projects on that computer. When you move a project to a different computer, it uses the defaults configured on that computer.
• When you configure build options while an ArchestrA Object Toolkit project is opened, they apply to the current project and override the defaults. In this case, you can work with the defaults as follows:
  • To restore a certain category of build options to its default values, click the Default button on its property page.
  • To set the current values as the new default values for a certain category of build options, click the Set Default button on its property page.

You can configure the following build options:

• Output preferences to copy the build output to additional locations
• Galaxy preferences to specify the working Galaxy for the various build modes
• Additional seach paths for reusable primitives and dependent files

Configuring Output Preferences

By default, the build output (.aaPDF or .aaPRI file) is saved in the \Output subfolder of your project folder. Optionally, the ArchestrA Object Toolkit can copy the build output to a custom location. When building a reusable primitive, the .aaPRI file can be copied to the common ArchestrA folder for reusable primitives.

To configure output preferences

1. In the ArchestrA Object Toolkit toolbar, click the Options icon. The Options dialog box appears with the Build category selected.
2. To copy the build output to a custom folder, select the Copy output package to specified folder check box and use the browse button to select the folder.
3. To copy reusable primitives to the common ArchestrA folder for reusable primitives after they have been built, select the Copy reusable primitives to ArchestrA Common check box. The base folder is always C:\Program Files\Common Files\ArchestrA\ReusablePrimitives. In that folder, the ArchestrA Object Toolkit creates a vendor subfolder based on the vendor name that you configured for the primitive.

On a 64-bit operating system, the base folder is C:\Program Files (x86)\Common Files\ArchestrA\ReusablePrimitives.

4. Click OK.

Configuring Galaxy Preferences

When you build an object, the ArchestrA Object Toolkit can optionally import, instantiate and deploy the new object version in a Galaxy so that you can test it. For more information, see Building an Object. You can specify which Galaxy to use for this.

To configure Galaxy preferences

1. In the ArchestrA Object Toolkit toolbar, click the Options icon. The Options dialog box appears.
2. In the left pane, click Galaxy. The Galaxy options appear in the right pane.
3. In the GR Node Name box, enter the name of the Galaxy Repository node. In most cases, it will be best to use a Galaxy Repository on the local machine. Otherwise, the build process can’t automatically restart the Application Server processes to make sure that the latest object version gets used.
4. In the Galaxy list, enter or select the name of the Galaxy to use.
5. If security is enabled for the Galaxy, enter the credentials in the User Name and Password boxes.
6. In the Assign to Area box, enter the name of the Area object that instances of your object should be assigned to.
7. To test the Galaxy connection, click Test.
8. Click OK.

Configuring Additional Search Paths

You can configure additional seach paths for dependent files. This gives you more flexibility because you can store your development files in multiple locations.

To configure additional search paths

1. In the ArchestrA Object Toolkit toolbar, click the Options icon. The Options dialog box appears.
2. In the left pane, click Search Paths. The Locations list appears in the right pane.
3. Edit the Locations list as follows:
   • To add the first entry, enter the search path in the text box, or click the browse button and select a path. Press Enter to confirm.
   • To add another entry, click the blank entry at the end of the list twice. The entry changes into editing mode. Enter the path as described above.
   • To edit an existing entry, click it twice to change into editing mode, then make your changes as described above.
4. Click OK.

Managing an Object's Versions

An ApplicationObject has a version number that consists of a major version and a minor version. For example, “1.3” where 1 is the major version and 3 is the minor version. This version number helps Wonderware Application Server distinguish object versions and detect any migration requirements.

When you build your object, you can keep the current version number, or you can automatically increment the minor or major version. You can also specify the version numbers manually in the object properties.

While developing an object, it is safest to have the major version number increment automatically on new builds. This helps avoid problems if you change the object shape but forget to increment the major version accordingly.

Building a New Minor Version of an Object

You usually increment an object’s minor version after making small changes to the object code. For example, you should increment the minor version after fixing bugs or making optimizations. If you change the object shape in any way, you must increment the major version instead.

When you build a new minor version of an object, you can choose to automatically restart Application Server processes. This is necessary if you have already imported a previous version of the object with the same major version into your Application Server working Galaxy. If you don’t restart the processes, Application Server continues to use the previous version even after you import the new minor version.

Depending on which components of your object have changed, you must restart different processes:

• After making changes to config time code, you must restart the aaGR and IDE processes.
• After making changes to run time code, you must restart the Bootstrap process.
• After making changes to custom object editor code, you must restart the IDE process.

When you build a new minor version and restart the processes, the ArchestrA Object Toolkit performs the following steps in the order listed:

1. Undeploys existing instances of the object
2. Deletes existing instances of the object
3. Deletes the existing object template(s)
4. Stops the processes
5. Builds the object
6. Restarts the processes
7. Performs any other steps as defined by the build mode (import. instantiate, deploy)

The ArchestrA Object Toolkit can only restart processes running on the local machine. For example, if you are using a remote Galaxy Repository (GR) machine or if you have deployed your object to a remote machine, you must restart the relevant processes manually. To specify the GR node, see Configuring Galaxy Preferences.

To build a new minor version of an object

1. In the ArchestrA Object Toolkit toolbar, click the Options icon. The Options dialog box appears.
2. In the left pane, click Version.
3. Select the Increment Minor Version option.
4. Select the Restart Bootstrap, Restart aaGR and Restart IDE check boxes as required (see above). If you select Restart aaGR, Restart IDE is always selected as well.
5. Click OK.
6. Build your object.

Building a New Major Version of an Object

You increment an object’s major version after making extensive changes to the object code, behavior and/or shape. For example, you should increment the major version after adding or renaming attributes. This alerts the user that the new version may not behave the same as previous versions, which might impact the user’s application.

While you develop an object, we recommend that you use this setting to have the major version number increment automatically on new builds. This helps avoid problems if you change the object shape but forget to increment the major version accordingly.

When you build an object with a new major version, you can choose to automatically delete the old version’s templates and instances from your working Galaxy. Alternatively, you can have the new version imported with the version number appended to the template name. This allows you to keep multiple versions of the same template in the Galaxy without having to manually rename existing templates.

To build a new major version of an object

1. In the ArchestrA Object Toolkit toolbar, click the Options icon. The Options dialog box appears.
2. In the left pane, click Version.
3. Select the Increment Major Version option.
4. Specify what to do with existing templates and instances if the ArchestrA Object Toolkit automatically imports the new object version into the Galaxy.
   • To keep the old template version and import the new version with the version number appended to its name, select the Append version number to template name check box.
   • To delete all previous versions of the object template (as determined by its vendor and object name), select the Delete all templates with the same vendor and object name check box. Any instances of these templates are deleted too.
   • To delete all previous versions of the object template and import the new version with the version number appended to its name, select the Delete all templates and append version number check box.
5. Click OK.
6. Build your object.

Creating a New Build without Incrementing the Version Number

You can create a new build without incrementing the object’s current version number. For example, you would do this if:

• You are using an automated build system that only recompiles the project.
• You set the final version number manually before release and don’t want the final build to increment that number.

When you build an object using this option, the only available build modes are Build and Build & Swap.

To build an object without incrementing the version number

1. In the ArchestrA Object Toolkit toolbar, click the Options icon. The Options dialog box appears.
2. In the left pane, click Version.
3. Select the Retain current version number option.
4. Click OK.
5. Build your object.

Manually Specifying the Version Number

If you want to reset the auto-generated version number, you can manually specify the object’s version number.

To manually specify the version number

1. Open the Object Designer.
2. In the Shape pane, click the object name. The object properties appear in the Configuration pane on the right.
3. In the Major Version and Minor Version boxes, enter the object’s major and minor version. If you increment the major version, you should reset the minor version to 1.
4. Click OK.

Building an Object

After you have set all build and versioning options and validated your object, you can build it. This creates an .aaPDF object file that you can import and use in Wonderware Application Server.

The ArchestrA Object Toolkit can automatically import, instantiate and deploy the object as part of the build process. To specify this, use the Mode list in the ArchestrA Object Toolkit toolbar.

The following build modes are available:

Build Mode	Description
Build	Creates an .aaPDF file of the object in the \Output subfolder of the Visual Studio solution folder.
Build & Import	Creates an .aaPDF file as outlined above, and then imports the template into the working Galaxy.
Build & Inst	Creates an .aaPDF file as outlined above, imports the template into the working Galaxy, derives a new template from it, and creates an instance from that template. The instance is assigned to the area configured in the Galaxy preferences (if any).
Build & Deploy	Creates an .aaPDF file as outlined above, imports the template into the working Galaxy, derives a new template from it, creates an instance from that template, and deploys it. The instance is assigned to the area configured in the Galaxy preferences (if any).
Build & Swap	Allows you to quickly swap the existing object assemblies in the Windows Global Assembly Cache (GAC). This is handy for debugging as it saves you the time for undeploying and redeploying an existing object instance. Don’t use this option if you have changed the object shape. Otherwise, unexpected results may occur. When you use this option, you must specify which processes to restart: • IDE if you have made changes to the custom object editor • IDE and aaGR if you have made changes to the config time code • Bootstrap if you have made changes to the run time code
•	IDE if you have made changes to the custom object editor
•	IDE and aaGR if you have made changes to the config time code
•	Bootstrap if you have made changes to the run time code

To specify the working Galaxy and Area object for importing, instantiating and deploying the object, see Configuring Galaxy Preferences.

To build an object

1. In the ArchestrA Object Toolkit toolbar, click the desired build mode in the Mode list. See above for available options.
2. Click the Build icon.

The ArchestrA Object Toolkit now starts the build and performs any other actions specified by the build mode. Any errors or warnings are reported in the Logger pane. The build output (.aaPDF or .aaPRI file, aaDEF file) is stored in the Output subfolder of your project folder.

Migrating Objects

When you import a new major version of an object template into Wonderware Application Server, existing instances of that object can be automatically migrated. This allows you to preserve their configuration in the new object version.

This is very easy if the new object version uses the same attributes as the previous version. In this case, all attribute values are automatically copied over from the old version’s instances to the new version’s instances.

However, you must create custom migration code if:

• The new version has attributes that the old version doesn’t have, and vice versa; and/or
• The security classification of an attribute has changed in the new version.

In this scenario, the custom migration code handles the mapping of attribute values between the old and new version. For example, if you have changed an attribute’s name from “Attribute1” to “AttributeA,” but the attribute still has the same purpose, the migration code could copy the value of Attribute1 (in the old version) to AttributeA (in the new version).

The ArchestrA Object Toolkit can help you create the migration code by generating a list of which attributes were added, removed, or have changed. You simply select a previous object version, and the ArchestrA Object Toolkit inserts a code region containing the names of all attributes that have changed between the previous version and the current version you’re developing. You can then add migration code for each attribute. For a short example, see Example: Migrating a Previous Object Version.

To create a migration code section for a previous version.

1. In the ArchestrA Object Toolkit toolbar, click the Migrate icon. The Browse for aaPDF and aaPRI Files dialog box appears.
2. Select the .aaPDF file of the previous object version (or the .aaPRI file if you are developing a reusable primitive), and then click Open. You can now view the auto-generated migration analysis results.
3. In the Object Design View, expand the Configtime folder, and then double-click the Migrate item. The migration results section opens in the code editor.

Note that the ArchestrA Object Toolkit has inserted a new code region showing the differences between the two versions. Enter any required migration code for the previous version here. For more information on available methods, see the ArchestrA Object Toolkit Reference Guide.

The ArchestrA Object Toolkit has also automatically updated the ObjectAttributes.Migrate property to include the version number of the object that you selected in step 2. This tells Application Server that your ApplicationObject supports migrating from that version. For more information on this property, see the ArchestrA Object Toolkit Reference Guide.

You can repeat this process for multiple previous versions of an object. The ArchestrA Object Toolkit generates a separate code region for each previous version. This allows you to have migration code for multiple previous versions in the same object.

Example: Migrating a Previous Object Version

See the example code region of the Migrate config time event handler for a short example of migration code. In this example, major version 1 of the object had an attribute named “Eg_001,” which was renamed to “Example_001” in the current version. The migration code transfers the value and settings of the old attribute to the new attribute:

if (migrate.MajorVersion() == 1)
{
    //Transfer attribute value, lock and security classification
    Example_001 = migrate.GetValue("Eg_001");               //Gets value
    Example_001.Locked = migrate.GetLocked("Eg_001");       //Gets lock status
    Example_001.Security = migrate.GetSecurityClassification("Eg_001");   //Gets Security Classification
    
    //Transfer primitive values
    SetValue("Example_001.TrendHi", migrate.GetValue("Eg_001.TrendHi"));
    Set("Example_001.TrendHi", EATTRIBUTEPROPERTY.idxAttribPropLocked, migrate.GetLocked("Eg_001.TrendHi"));
    
    //Automatically migrate all child primitives
    migrate.AutoMigrateChildPrimitives = true;
}

Note the “if” condition at the beginning of the code. Using similar conditions, you can have additional, separate migration code sections for other previous major versions of the object.

Additional Guidelines for Migrating Objects

Note the following when developing migration code for your objects:

• Make sure that your migration code is aware of the presence or absence of child virtual primitives.
• When migrating attributes within a reusable primitive, the migration code must use the full primitive name to access the attribute in the original object being migrated from. You can use the OriginalPrimitiveFullName property in the MigrateHandler class for this purpose. For example:

    migrate.GetValue(migrate.OriginalPrimitiveFullName + ".Attribute1")