[link="http://www.everdyn.com/blog/"]From Everdyn's blog[/link]

In ArchestrA, DLLs are a great way to extend the standard product – to bend it to your will and to allow almost any client requirement to be achieved.

Two categories of DLL

DLLs are used for 2 different things in ArchestrA. The way you use them is different, where and how they are deployed is different and where and how they bite you in the butt is also different. Before you read any Tech Note or follow any procedure, you need to know what type of DLL you are dealing with.

To make it more complex you can use one DLL as both categories – and really tie yourself in knots.

How to tell ArchestrA what type of DLL is being imported

Type 1: Script Function Library

Importing a DLL as a Script Function Library allows you to use it – as the name suggest – in a script. You can declare instance of classes from the DLL in your own script. You can then access its properties and methods. You can’t really use events as objects are executed cyclically.

In ArchestrA, Objects are executed by engines which are instances aaEngine.exe running as processes owned by the aaBootstrap service. Multiple engines may be on the save server, but there is only one copy of the DLL on the local hard drive. Each engine has it loaded into memory where all the objects on the same engine can access it. Objects on the same engine can actually share the same instance of a class from a DLL as all object on one engine share an App Domain.

Updating a DLL involves getting the new version of the DLL out to where it is needed. This means the GR, AOS hard drives and RAM.

Script Function Libraries can also be used in scripts in ArchestrA Graphics. In this case the scripts are executed by View.exe. Updating a DLL in this case involves getting the new version of the DLL to the HMI PC Hard drive and RAM.

Browsing for a property, method or class in a Script Function Library

Type 2: Client Control

A DLL that contains one or more Client Control classes needs to be imported as a Client Control. These appear in the Graphic Toolbox. They can’t be used directly in InTouch, but they can be pasted into ArchestrA Symbols which can then be used in InTouch. They can’t be instantiated with code like classes in Script Function Libraries. Because of this they can’t be used in objects – usually.

Imported Client Controls visible in the Graphic Toolbox

Client controls are hosted by ArchestrA Symbols, possible WinForms, and ultimately by View.exe

Avoiding the Pain

Importing either type of DLL is relatively straight forward the first time. The problems occur when you need to import a new version of the same DLL. This is common during development of a DLL. After upgrading the DLL you may find is performs the same as before. Is it because the fix didn’t work, or are you still using the old version of the DLL?

Here are some tips.

Test Externally

Do as much testing as possible before importing into ArchestrA

Expose Version Information

Expose a property that returns the version number. Log this to the logger or make it visible on a symbol. Always check you are testing the version you think you are.

UpRev

Wonderware advise increasing the version number for every import. While you can replace files directly, it gets difficult to detect mistakes. It’s not really supported either.

Version numbers are of the form a.b.c.d. ArchestrA does not see a change in d. The following is a suggestion that works.

a)      Major Version

b)      Minor Version

c)       Build

d)      Unused (0 or whatever)

Let’s say version 1.2.23.0 is in production and a new minor version is needed. The next version imported might be 1.3.0.0 .  Probably there will be some bugs found in testing, so the first bug fix version will be 1.3.1.0

Increment ‘c’ while debugging. Increment ‘b’ when adding new functionality. Reserve ‘a’ for bigger changes, re-writes etc.

Light Constructors (Client Controls)

When you instantiate a class in a script, you are in control. The constructor of a client control however is called at design time when you open a symbol containing it. You don’t want to try and connect to databases or read files etc during design time. This code should therefore never be put in a constructor. Put code that needs to run once when the control appears into an initialization method and then call it with an OnShow script in the symbol. Be careful when the symbol is re-opened from the cache. The OnShow script re-executes.

Methodology or Understanding

There are tech notes and procedures to help you avoid the pitfalls. However they are an open loop approach. “Do this and you should be OK”.

If you follow a long procedure and it doesn’t work, what do you do? How can you check that things are ok?

Understanding how to check that files are in the correct places is a good start.

Script Function Libraries – Actions

To summarize the ArchestrA advice:

• Import the new version – make sure the version number has been changed
• Validate the objects marked for Software Upgrade. How to find them? Code192 have a good tool!
• Deploy. Select the object and also the containing platform

Script Function Libraries – Tests

At this point the new version of the DLL should be on the target servers (assuming scripts used in objects here). Do a search to find all the versions. If the version numbers have changed, good. If not, go back to the GR and start searching for old versions there.

You should find your dll in

C:Program Files (x86)ArchestrAFrameworkBin

And

C:Program Files (x86)ArchestrAFrameworkBinScriptTemp

If there are old versions there then you have found the problem. Attempt to re-import. If it’s not going in why? Possibly another IDE. Often re-stating the GR will release the lock on the file.

The point is, isolate the problem and fix it. You will waste a lot of time if you simply attempt to follow a procedure a second (or third) time hoping it will work ‘next time’ if you don’t understand what went wrong.

Script Function Libraries – Final Actions

Once a good version of the DLL is on the server, it needs to be put in memory. To do that, the engine(s) must be stopped and re-started to purge the old one from the AppDomain. Again this assumes scripts used in Objects. If the scripts are used in symbols, then View.exe needs re-starting

Script Function Libraries – Final Tests

Assuming you added a version property, the value in this property should be written to the log or a UDA as soon as the constructor has been called. Check this value before beginning functional tests.

Client Controls

Client Controls can cause more problems that Script Function Libraries. With Script Function Libraries, the usual problem that is encountered is the old version is still in use. Client controls sometimes have the opposite problem. The correct version is on the HMI PC, but View wants the old one.

When this happens, there is nothing in the log to tell you. If you turn on Trace for ArchestrA.Visualisation.GraphicLibrary you will see the exception stating that the old version could not be found.

When this occurs, the problem is in the compiled symbol that directly contains the control.  Here is a procedure including checks that has proved to be effective.

1) Compile new version – make sure the version number changes

2) On your local IDE (not necessarily on the GR server) find the control, note which symbol(s) embed it directly, and delete the control from the graphic toolbox. It is not necessary to delete the control from the symbols. In fact that can be painful if you have a lot of bindings or event handlers. The symbols using it will be marked with warnings.

3) Restart the local IDE to remove the control from memory

4) Import the control

5) Validate the symbol(s) that directly contain(s) the control. Even if the warning is gone you still need to validate it. It normally gets checked out, and back in, by the IDE

6) (To be sure) Search program filesArchestrA on the GR for versions. Old versions are ok in deployed InTouch apps.

Make sure the new version is in the lower directories. Test the correct version is in the correct locations by deploying an InTouch app. The new version should be in the deployed app directories.

7) (To be sure.) In the deployed directories just checked, look for the .VEDEF file of the symbol(s) directly containing the control. Open with a text editor (DO NOT EDIT) and check that the new version number is in there. If so then you are finished

8) (If step 7 failed.) To correct the .VEDEF file, try and validate the symbol again on the GR. You will need to re-deploy the InTouch app to generate a new .VEDEF file. If it still contains the old version it will be necessary to re-start the GR service before validating again.

The post ArchestrA and DLL’s The Good, the Bad and the Downright Painful appeared first on EVERDYN.