After you build a plugin component, you may need to register it in the Windows registry. You must register it with a plugin point in the hosting environment. Afterward, you can deploy it 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, you might need to register the component 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.
Visual Studio provides the GuidGen.exe program that generates unique GUIDs. Access the GUID creation tool from the Tools menu in Visual Studio. If you don't have 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 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 MS AntiSpyware asks you to allow the script, check the box indicating "Remember this action".
Windows Script Component plugins
Components built as a Windows Script Component with a scripting environment (VBScript, JScript, Python) should have a filename extension 'wsc'. This is an XML text file declaring the implementation of the plugin interface. To register the component, create a command window. Right-click the Start menu, select Run, type 'Command' in the text box, and click OK. 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
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. Right-click the Start menu, select Run, type 'Command' in the text box, and click OK. 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
You can use .Net plugins with or without registration into the Windows registry.
With registration into the Windows registry
Compiled components with filename 'dll' are contained in a dynamic link library. To register the component, create a command window. Right-click the Start menu, select Run, type 'Command' in the text box, and click OK. Change your directory (using cd) to that of the file. At the command prompt, type 'regasm /codebase YOUR_FILENAME'. For example:
- 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 found in a subfolder 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
You can load he following engine plugins, written using the .NET framework, 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 with a plugin point (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 two or more plugins or even two or more plugins to two or more 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
- .Net Managed Plugins Not Registered into the Windows Registry
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 one or more plugins (here shown using the <Plugin> tag) and registering one or more 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. You can find example XML registration files 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 VGT Plugins VGT Vector Plugins <STK install folder>\CodeSamples\Extend\VGT.Plugins\VGT Plugins.xml
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.
.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:
<User friendly name>: The display name is used as user-friendly name when referencing the plugin from the user interface.
<Class Name>: This is the name of the .Net class that implements the plugin.
<Name of the assembly>: The assembly name identifies the .Net assembly. During development, you can use the filename of the DLL. When deploying, you can use the .Net fully qualified assembly name. It is also a recommended practice to use strong-named assemblies during deployment.
<Path to the directory containing the assembly>: This is the directory that contains the .Net assembly.
For example, using the CodeSamples\Extend\Constraints\CSharp\Range plugin:
- You can use “RangeConstraintPlugin” as the display name to be used when referencing the plugin in the user interface.
- For the type name field, you need the name of the .Net class (including the namespace) that implements the plugin interface. In this specific example the code looks like:
namespace AGI.Access.Constraint.Plugin.Examples.CSharp.RangeExample
{
public classRangeExample : IAgAccessConstraintPlugin
…and therefore the type name is:
AGI.Access.Constraint.Plugin.Examples.CSharp.RangeExample.RangeExample
For the assembly name, you can use the filename for the DLL during development. Once ready to deploy, Microsoft recommends signing your assembly with a strong name and then using the fully qualified assembly name (e.g., "NIIRS, Version=1.0.0.0, Culture=neutral, PublicKeyToken=...").
For the code base, use the path to your assembly.
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
Use DisplayName as 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.
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 startup will not take effect until the next time the application starts. STK looks at the following folders for XML plugin registration files:
<STK all users area>\Plugins
For example: C:\ProgramData\AGI\STK_ODTK 13\Plugins{STK_12_DIR in APPLICATION DATA For ALL USERS}\Plugins
For example: <STK all Users Area>\AGI\STK 13\Plugins<STK user area>\Config\Plugins
For example: C:\Users\<user id>\My Documents\STK 13\Config\Plugins
XML registration files located in <STK install folder>\Plugins and the <STK all users area>\Plugins area will be available for every user; those located in <STK user area>\Config\Plugins will be available only for that user.
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:
- Engine Plugin Points
- Engine Plugin Site Interface
- Implementing Key Interfaces
- Building Engine Plugins
- Engine Plugin Registration
- Installing and Deploying Plugins
- Engine Plugin Use Example
- Engine Plugin Component Lifecycle
- Access Constraint Plugin Lifecycle
- Engine Plugin Parameter Data
- Engine Plugins Libraries