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

User Interface (UI) Plugin Registration for COM UI Plugins

Once a COM UI plugin component has been built, it must be registered in the windows registry as well as being registered with a plugin point in the hosting environment. After the COM UI plugin is properly registered, it can be deployed to other computers for use by others.

Registering Engine Plugins in the Windows Registry

Because each COM UI plugin component is a COM object, it must follow certain COM paradigms. Most importantly, each component must 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:

Allow the running of these scripts via the MS AntiSpyware applications options menu.
Or run the script, and when it asks for it to allow the script, check the box indicating "Remember this action".

Compiled Plugins

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_UIPLUGINNAME'. For example:

regsvr32 YOUR_UIPLUGINNAME.dll

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

C:\Windows\SysWOW64\regsvr32.exe YOUR_UIPLUGINNAME

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

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

To register your COM UI plugin with the hosting environment, you need to list it in an XML registration file.

The registration file has the following form:

<?xml version = "1.0"?>
<AGIRegistry version = "1.0">
<CategoryRegistry>
<Category Name = "UiPlugins">
<UiPlugin DisplayName = "Optional Display Name" ProgID = "YOUR_ProgID" File = "Filepath/NameofComponent.dll" DisplayName = "YOUR_DISPLAYNAME">
</Category>
</CategoryRegistry>
</AGIRegistry>

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

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). Each file is capable of registering multiple plugins (here shown using the <UiPlugins> 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.

Display Name

In COM UI plugins, The DisplayName is used as a user-friendly short-hand for the ProgID listed. You may choose any DisplayName, but it must be unique amongst all registered plugins of the same category. See the sample registration files for the official category name of a plugin point.

Version Information

You can add version information to the xml manifest file, as shown in the following COM UI plugin example. (User-defined values are in green.)

 
 <UiPlugin ProgID="Agi.Ui.Plugins.CSharp.Basic" 

     File="C:\Source\DeveloperKit\CodeSamples\Extend\Ui.Plugins\CSharp\Basic\bin\Debug\Agi.Ui.Plugins.CSharp.Basic.dll" 
     DisplayName="Basic CSharp Plugin">          
            <VersionInfo Version="Version Number">

               <Publisher>Company Name</Publisher> 

               <SupportUrl>http://companyname.com/UIPlugin/</SupportUrl> 

               <Creator>Developer Name</Creator> 

               <Description>Description of UI Plugin</Description> 

            </VersionInfo>
  </UiPlugin>

You can view this version information from the STK GUI, by selecting Preferences->Ui Plugins from the Edit menu, and clicking the Details... button under Advanced Options.

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:

<STK installation folder>\STK 11\Plugins.
Windows All Users Application area (C:\Documents and Settings\All Users\Application Data\AGI\STK 11\Plugins on Windows XP and C:\ProgramData\AGI\STK 11\Plugins on Windows Vista and 7).
Windows Configuration area (C:\Documents and Settings\<user name >\My Documents\STK 11\Config\Plugins on Windows XP and C:\Users\<user name>\My Documents\STK 11\Config\Plugins on Windows Vista and 7).

XML registration files located in <STK installation folder>\STK 11\Plugins and <Windows All Users Application area>\AGI\STK 11\Plugins are available for every user; those located in <Windows Configuration area>\Plugins will be available only for that user.

You may also want to learn more about:

STK Programming Interface 11.0.1