Registering Engine Plugins in the Windows Registry | Registration with a Plugin Point (i.e. Category registration)

Engine Plugin Registration

Once a plugin component has been built, it may need to be registered in the windows registry and it must be registered with a plugin point in the hosting environment. Afterward, it can be deployed to other machines for use by others. Refer to the instructions for installing and deploying plugins for more information.

Registering Engine Plugins in the Windows Registry

Depending on the development tool, component might need to be registered for use in the Windows registry with a unique GUID (Globally Unique Identifier).You must have administrative rights to add components to the Windows registry.

Note: Visual Studio provides the GuidGen.exe program that generates unique GUIDs. Access the GUID creation tool from the Tools menu in Visual Studio. For users without Visual Studio, download the Windows Script Component Wizard from www.msdn.com/downloads which can also generate GUIDs. It is very important not to have more than one component registered in the Windows registry with the same GUID.

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

Windows Script Component Plugins

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

Compiled Plugins built without using .NET

Compiled components are contained in a dynamic link library, whose filename has an extension 'dll'. To register the component, create a command window (under the Start menu, hit "Run ...", type 'Command' and hit OK). Change your directory (using cd) to that of the file. At the command prompt, type 'regsvr32 YOUR_FILENAME'. For example:

Compiled Plugins built using .NET

.Net plugins can be used with or without registration into the Windows registry.

With Registration into the Windows registry

Compiled components are contained in a dynamic link library, whose filename has an extension 'dll'. To register the component, create a command window (under the Start menu, hit "Run ...", type 'Command' and hit OK). Change your directory (using cd) to that of the file. At the command prompt, type 'regasm /codebase YOUR_FILENAME'. For example:

Note: 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 found in a sub-folder of C:\WINDOWS\Microsoft.NET\Framework\. The actual folder depends on your version of the .NET Framework installed on your machine.

Without registration into the Windows registry

The following engine plugins written using the .NET framework can also be loaded into STK without registering them using regasm: Ephemeris File Reader, Density Model, Drag Model (Particle Reflection), Equation of Motion Function, HPOP Force Model, Solar Pressure Light Reflection, STK Astrogator Attitude Controller, Astrogator Engine Model, STK Astrogator Search, GPSSatSelect, and Access Constraints. To use this approach use the XML element <DotNetPlugin> in the XML registration file.

Registration on 64-bit machines

When using regsvr32 on a 64-bit machine, it is important to know whether the COM object is built using a 32 or 64 bit architecture. In most cases, it is using 32 bits. To register a 32 bit built COM object, you must use the 32 bit version of regsvr32. Normally this is found in C:\Windows\SysWOW64. By default, 64 bit machines use the 64 bit version of regsvr32, so you should use:

when registering 32 bit COM objects. Currently, Windows Script Components are all 32 bit.

Registration with a Plugin Point (i.e. Category registration)

To register your plugin with the hosting environment, 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 multiple plugins (even multiple plugins to multiple categories). XML registration files located in <STK install folder>\Plugins will be available for every user; those located in {CONFIG_DIR}\Plugins will be available only for that user. Select one of the following to register your plugin with a plugin point:

Plugins Registered with regsvr32 or regasm

 

<?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 multiple plugins (here shown using the <Plugin> tag) and registering multiple 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 hosting environment to identify each plugin point. Example XML registration files can be found in <STK install folder>\CodeSamples\Extend:

Plugin Type Category Name Example file
Engine Model Engine Models <STK install folder>\CodeSamples\Extend\Gator.EngineModels\Engine Models.xml
Attitude Controller Attitude Controls <STK install folder>\CodeSamples\Extend\Gator.AttitudeControllers\Attitude Controls.xml
Search Search <STK install folder>\CodeSamples\Extend\Gator.Search\Search.xml
HPOP Force Model HPOP Plugins <STK install folder>\CodeSamples\Extend\Hpop.ForceModels\Hpop Plugins.xml
Solar Pressure Force Model LightReflection <STK install folder>\CodeSamples\Extend\SRP.LightReflection\SRP.LightReflection.xml
Drag Model DragModel <STK install folder>\CodeSamples\Extend\DragModels\DragModels.xml
Access Constraint Access Constraint Plugins <STK install folder>\CodeSamples\Extend\Constraints\Access Constraints.xml

An example file is shown below 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>

Note: Tags (e.g., Plugin) and attributes (e.g., DisplayName) are case-sensitive.

.Net Managed Plugins without Registry Registration

For .Net managed plugins without registry registration, the XML element <DotNetPlugin> must be used instead of the <Plugin> element in the XML registration file. The following information needs to be provided with the <DotNetPlugin> element:

<Category Name="…">
    <DotNetPlugin
      DisplayName="<User friendly name>"
      TypeName="<Class Name>"
      AssemblyName="<Name of the assembly>"
      CodeBase="<Path to the directory containing the assembly>"/>
</Category>

where:

So for instance using the CodeSamples\Extend\Constraints\CSharp\Range plugin:

  namespace AGI.Access.Constraint.Plugin.Examples.CSharp.RangeExample
  {
           public class RangeExample : IAgAccessConstraintPlugin
           …

and therefore the type name is: 

         AGI.Access.Constraint.Plugin.Examples.CSharp.RangeExample.RangeExample

Here is the completed XML fragment to declare the Range plugin example:

<?xml version = "1.0"?>
<AGIRegistry version = "1.0">
        <CategoryRegistry>
          <Category Name = "Access Constraint Plugins">
            <DotNetPlugin
                DisplayName="RangeConstraintPlugin"
                TypeName="AGI.Access.Constraint.Plugin.Examples.CSharp.RangeExample.RangeExample"
                AssemblyName="AGI.Access.Constraint.Plugin.Exanples.CSharp.RangeExample"
                CodeBase="C:\Tmp\CodeSamples\Extend\Constraints\CSharp\Range\bin\x64\Debug"/>
          </Category>
        </CategoryRegistry>
</AGIRegistry>

Display Name

The DisplayName is used as a user-friendly short-hand 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.

Manifest Location

When the host 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. STK looks at the following folders for xml plugin registration files:

XML registration files located in <STK install folder>\Plugins and the {STK_11_DIR in APPLICATION DATA For ALL USERS}\Plugins area will be available for every user; those located in {CONFIG_DIR}\Plugins will be available only for that user.

Note: Previous STK versions used a Category Identifier (CAT_ID) to associate a given COM component with its intended Plugin Point in the Windows Registry. This is no longer necessary. The CAT_ID registration has been obsoleted in favor of the XML file registration.

Related Topics:

You may also want to learn more about:

STK 11.2.1 Programming Interface