Plugin Components

A plugin component is a software component built using Microsoft's COM technology. There are two types: (1) compiled code, which is usually a dynamic link library, and (2) script code.

You can implement compiled code in any language (C++, C#, Visual Basic .NET, etc.) that supports COM interfaces. Compiled code plugins will execute almost as fast as the application program itself. Another advantage is that you can debug your component using a standard debugger while it is in use. Of course, any modification of the code requires recompilation before you can use it. While you can use, modify, rebuild, and reimplement a C++ COM component while the application is still running, COM components built using a .NET language (C#, VB.NET, etc.) cannot. You can rebuild them once the application has exited.

Implement script code using Windows Script Components (WSC). You can implemented it in a variety of languages (VBScript, JScript, PerlScript, Python, etc.). Although script code is slower to execute than compiled code, you can edit scripts after each run. They cannot be debugged, however. Often, proofs-of-concept are developed using scripts before being written in a compiled language for speed.

Matlab is COM-aware, and you can call it through a COM interface. To use Matlab in a plugin, AGI recommends that you create a Windows script component using a script language and communicate with Matlab through its COM object model. The Ansys Orbit Determination Tool Kit (ODTK^®) application install provides samples that use a VBScript component that opens up Matlab and calls a Matlab m-file to perform a computation. Because Matlab is an application, not just a dynamic link library (DLL), function calls made between the plugin and Matlab are likely to be very much slower than just using the scripting environment itself, which of course is slower than using a compiled language. Speed penalties can reach up to 50 times the use of the scripting environment itself.

Building plugin components

Plugin components are built using Microsoft's COM technology, developed in the mid 1990s. It is the precursor technology to Microsoft's .NET framework. All the sample code provided was built using Microsoft's Visual Studio 2017.

It is best to use one of the samples provided as a guide. You can even modify the provided code to see how a feature will work. If you are unfamiliar with programming languages in general, then AGI recommends C# for the compiled code and JScript for the script code, unless you know Perl. While VB.Net and VBScript were developed to make programming simple, C- and C++-based programmers may feel ill at ease with these languages.

A program uninstall/reinstall will delete the example plugins and any changes made to them will be lost. It is recommended that you copy the examples to your own directories if you wish to modify them.

Essentially, each plugin point defines a functional interface that the plugin component must implement. The plugin help will identify the required methods. You must provide a method, even if the plugin does not use it. The plugin can turn a method off, however, to prevent it from being called unnecessarily and wasting time.

Because each plugin component is a COM object, it must follow certain COM paradigms. Most importantly, each different plugin must have a unique GUID (Globally Unique Identifier). Visual Studio provides the GuidGen.exe program that generates unique GUIDs. If you don't have Visual Studio, download the Windows Script Component Wizard from https://msdn.com/downloads. This can also generate GUIDs. It is very important not to have more than one component registered in the Windows registry with the same GUID.

Sample plugins

The ODTK application install provides sample plugins for each of the plugin points. See <Install Dir>\CodeSamples\Extend\ODTK\. Each sample is available in a several programming languages. The install also provides a scenario demonstrating the use of the sample code. You need to build the compiled examples to see their use; you need to register the Windows script components to see their use. For more information, see Installation and Deployment below. Moreover, for Perl examples, you will need to install Perl from activestate.com, which is available as a download from their website for free.

In addition to registration in the Windows registry, plugins must also be registered with a plugin point in the ODTK application. Use the XML registration files provided for all of the sample plugins in the sample code area. After registering a sample plugin, you must copy the corresponding registration file to an appropriate folder. See Registration as a Plugin Point below.

Registration in the Windows registry

Because each plugin component is a COM object, you must register each for use in the Windows registry. You must have administrative rights to add components to the Windows registry. In the sample code provided for the compiled languages, the build settings are configured to automatically register the sample plugin component during the build. You do not compile Windows script components, but you must still register them. The registration associates a GUID and ProgID defined by the component.

Before registering the components, if you have the Microsoft AntiSpyware application actively running, you will have to perform one of the following tasks:

- Allow the running of these scripts via the MS AntiSpyware applications options menu.

- Run the script and, when it asks for it to allow the script, select the Remember this action check box.

Registering Windows script component plugins with administrative rights

Components built as a Windows Script Component with a scripting environment (VBScript, JScript, Perl, Python) should have a filename extension 'wsc'. This is an XML text file declaring the implementation of the plugin interface. To register the component, go to the Start menu, type "Command", and to open a command prompt. Change your directory (using cd) to that of the file. At the command prompt, type 'regsvr32 YOUR_FILENAME'. For example:

regsvr32 VBScript.Example1.Hpop.wsc

Registering Windows script component plugins without administrative rights

Regsvr32.exe requires administrator rights to register a plugin. Once registered, it's available to all users on that machine, provided that the actual file location on the disk does not change. It's sometimes difficult to find a system administrator to register the plugin though. In this case, AGI has provided a VBScript utility "register_wsc_hkcu.vbs" located in your install under <Install Dir>\CodeSamples\Extend. The utility will register a Windows Script Component to the HKEY_CURRENT_USER area of the Windows registry rather than HKEY_LOCAL_MACHINE. To run the utility, open up a command prompt and change directories to the location of the utility. Then enter

cscript register_wsc_hkcu.vbs "Your WSC Name.wsc"

replacing "Your WSC Name.wsc" with the actual full path to the location of your Windows Script Component (WSC) file. The utility will parse your WSC file and make the appropriate entries into the Windows registry. You must run this utility for each user on the machine who wants to use that plugin.

Compiled plugins built without using .NET

Compiled components are contained in a dynamic link library with a DLL filename extension (.dll). To register the component, go to the Start menu, type "Command", and open a command prompt. Change your directory (using cd) to that of the file. At the command prompt, type 'regsvr32 YOUR_FILENAME'. For example:

regsvr32 Agi.As.Hpop.Plugins.CPP.Examples.dll

Compiled plugins built using .NET

regasm /codebase Agi.As.Hpop.Plugin.CSharp.Examples.dll

Your system may not recognize the regasm command. In that case, you will need to specify the full filepath to RegAsm.exe. The file itself is in a subfolder of C:\WINDOWS\Microsoft.NET\Framework\. The actual folder depends on your version of the .NET Framework installed on your machine.

Registration with a plugin point (i.e., category registration)

To register your plugin with the ODTK application, you need to list it in an XML registration file. You may choose to create a new XML file for each plugin you create, or you may choose to use one file to register more than one plugin or even many plugins to many categories. XML registration files located in <Install_Dir>\Plugins will be available for every user; those located in C:\users\<username>\Documents\STK_ODTK 13\Config\Plugins will be available only for that user.

The registration file has the following form:

<?xml version = "1.0"?> <AGIRegistry version = "1.0"> <CategoryRegistry> <Category Name = "Category Identifier 1"> <Plugin DisplayName = "Optional Display Name" ProgID = "ProgID of the Plugin 1"/> <Plugin DisplayName = "Optional Display Name" ProgID = "ProgID of the Plugin 2"/> etc... </Category> <Category Name = "Category Identifier 2"> etc... </Category> </CategoryRegistry> </AGIRegistry>

Each file is capable of registering many plugins, here shown using the <Plugin> tag, and registering many categories, here shown using the <Category> tag. You need not register all plugins of the same Category in the same file. The ProgID is the Program Identifier you chose to associate with your plugin's GUID. The Category Identifiers are names recognized by the ODTK application to identify each plugin point. Example XML registration files are in <Install_Dir>\CodeSamples\Extend\ODTK.

Here is an example file for HPOP plugins:

<?xml version = "1.0"?> <AGIRegistry version = "1.0"> <CategoryRegistry> <Category Name = "HPOP Plugins"> <Plugin DisplayName = "YOUR_DISPLAY_NAME" ProgID = "YOUR_PROGID"/> </Category> </CategoryRegistry> </AGIRegistry>
Tags (e.g., Plugin) and attributes (e.g., DisplayName) are case sensitive.

DisplayName is a user-friendly shorthand for the ProgID listed. You may choose any DisplayName you wish, but it should be unique amongst all registered plugins of the same category. See the sample registration files for the official category name of a plugin point.

When the ODTK application starts, it searches for XML files contained in identified folders and registers all plugins declared in each XML file found. Any changes made to these files after start-up will not take effect until the next time the application starts. The ODTK application looks at the following folders for XML plugin registration files:

<INSTALL_DIR>\Plugins
For example: C:\Program Files\AGI\STK_ODTK 13\Plugins
<CONFIG_DIR>\Plugins
For example: C:\Users\user_name\Documents\STK_ODTK 13\Config\Plugins

Installation and deployment

Once you build a plugin component, you can deploy it to other machines for use by others. To do this, you must copy all the appropriate files — the .wsc and script file for Windows Script Components, and all relevant .dll files for compiled components — built with the plugin to the other machine. Someone must register the plugin in the Windows registry and place an appropriate XML registration file in a registration search folder.

When you build a plugin in Debug mode, rather than Release mode, the component runs using Microsoft debug dynamic link libraries that are supplied with Visual Studio .NET. The plugin will not run on a machine that does not have those Debug libraries. Debug libraries are not redistributable and are not part of the standard Windows operating system installation. In most cases, you should build a plugin for deployment to other machines using Release mode.

Using a plugin component

Once you install a plugin, you can choose to use it by selecting its ProgID or DisplayName from the user interface. The plugin may choose to declare certain parameters as being editable by the user. If so, then the user interface allows a user to edit these settings as well.