Create a Valid Plugin

This section provides the necessary steps to create a project in Visual Studio which STK will recognize as a valid UI plugin.

1. Create a New Class Library
2. Add the COM Reference "AGI UI Plugins 11"
3. Define Class Attributes
4. Enable COM Visibility
5. COM Registration
6. Category Registration
7. Implement the IAgUiPlugin Interface
8. Confirm your UI Plugin in STK

Create a New Class Library

1. In Visual Studio, create a new Project, and select the Class Library Template in your language of choice. Code samples are given in C# and VB.NET.
2. Select .NET Framework 3.5. If you are using Visual Studio Express Edition and do not see this option, click here.
3. Give your project and solution a meaningful name (MySampleUIPlugin is used in this example).

4. Select the save Location for the project and click OK.

   

5. The project wizard automatically creates a public class (Class1), and adds it to your project. Give the class a more meaningful name:
   1. Right-click the Class1.cs or Class1.vb file in the Solution Explorer and rename the file. We again used “MySampleUIPlugin".
   2. Visual Studio will ask if you would like to rename all references to Class1. Click Yes.

Add the COM Reference “AGI UI Plugins 11”

Add a reference to the library containing the AGI UI Plugins type definitions (AgUiPlugins.dll).

1. Right-click References in the Solution Explorer and select Add Reference... (If the References folder is not shown, click the Show All Files button.)
2. On the COM tab, select AGI UI Plugins 11.
3. When you click OK, three items are added to your project references: AGI.Ui.Application, AGI.Ui.Core, and AGI.Ui.Plugins.

   

4. Add using directives for the three AGI.Ui namespaces, as well as the System.Runtime.InteropServices namespace (which promotes interaction with external type libraries):

   [C#]
   using AGI.Ui.Application; using AGI.Ui.Core; using AGI.Ui.Plugins; using System.Runtime.InteropServices;

   [Visual Basic .NET]
   Imports AGI.Ui.Application Imports AGI.Ui.Core Imports AGI.Ui.Plugins Imports System.Runtime.InteropServices

Define Class Attributes

The GUID, ProgID, and ClassInterface attributes must be defined for the class.

The GUID is a Globally Unique IDentifier, used to uniquely identify your component in the Windows registry. On the Visual Studio Tools menu, use the Create GUID function to generate a new GUID for your plugin. If you are using Visual Studio Express Edition and do not see this option, click here.

The ProgID is a unique string used to identify your plugin to STK. AGI recommends a "MyCompanyName.MyPluginName" convention.

The ClassInterface defines whether the public methods and properties of class are exposed to COM clients. In most cases, the "None" class interface type will suffice. Use of the AgUtPlugin library requires the "AutoDispatch" type, as described in a later section.

The attribute definition will resemble this format:

namespace MySampleUIPlugin
{
    [Guid("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")]
    [ProgId("MyCompany.MySampleUIPlugin")]
    [ClassInterface(ClassInterfaceType.None)]
    public class MySampleUIPlugin
    {
    ...

<Guid("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"), _
ProgId("MyCompany.MySampleUIPlugin"), _
ClassInterface(ClassInterfaceType.None)> _
Public Class MySampleUIPlugin
    ...

Enable COM Visibility

Ensure that the types in the assembly are visible and accessible to COM components. For this example, set the ComVisible attribute to true for the entire assembly (if desired, you can override for individual types and type members in the public class).

1. Expand the Properties folder in the Solution Explorer and open AssemblyInfo file.
2. Locate the ComVisible attribute and set it to true:

3. [C#]
   [assembly: ComVisible(true)]

   [Visual Basic .NET]
   <Assembly: ComVisible(True)>

4. Save and close the AssemblyInfo file.

COM Registration

If you are using a COM UI plugin, your plugin must expose a COM object (a COM-callable wrapper for your application) so that the plugin can communicate with STK. There are two options for registering your COM UI plugin as a COM component: use Visual Studio settings to register at build, or use the command prompt to register your plugin. Either option requires administrative privileges on your machine.

To use the Visual Studio settings to register your plugin at build time:

1. Right-click the project (MySampleUIPlugin) in the Solution Explorer and select Properties.
2. Select the Build tab (C#) or the Compile tab (VB).
3. Select the Register for COM interop check box.
4. Save and build your project.

Depending on your configuration, you might get a build error:

“Cannot register assembly "<filpath>\MySampleUIPlugin.dll" - access denied. Please make sure you're running the application as administrator. Access to the registry key 'HKEY_CLASSES_ROOT\MyCompany.MySampleUIPlugin' is denied.”

If you get this error:

1. Close Visual Studio.
2. Open Visual Studio, but instead of a click or double-click to launch Visual Studio, right-click and select “Run as administrator.”
3. Open your plugin project and build again. The “access denied” error should not appear.

The plugin only needs to be registered once, so you can turn off the Register for COM interop flag and run under normal user privileges for rest of the project.

If you are using a .NET UI plugin, you do not need to register it.

Category Registration

STK uses an XML manifest file to discover and load plugins at run-time. Using either Visual Studio or a text editor, create a new XML file. AGI recommends naming the XML file with the same name as your plugin (MySampleUiPlugin.xml). Below are examples of the required format for COM UI plugins and .NET UI plugins. Note that for COM UI plugins, the ProgID specified in the XML manifest must match the ProgID specified in the class attributes.

COM UI Plugin Manifest

<?xml version = "1.0"?>
<AGIRegistry version = "1.0">
  <CategoryRegistry>
    <Category Name = "UiPlugins">
      <UiPlugin ProgID = "MyCompany.MySampleUIPlugin" DisplayName = "MySampleUiPlugin">
      </UiPlugin>
    </Category>
  </CategoryRegistry>
</AGIRegistry>

.NET UI Plugin Manifest

<?xml version = "1.0"?>
<AGIRegistry version = "1.0">
  <CategoryRegistry>
    <Category Name = "UiPlugins">
<NETUiPlugin 
         DisplayName="Rectangular Sensor UI Plugin (Examples)"
         TypeName="RectangularSensorPlugin.RectangularSensorPlugin"
         AssemblyName="RectangularSensorPlugin, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"
         CodeBase="C:\ProgramData\DeveloperKit\CodeSamples\Extend\Ui.Plugins\CSharp\RectangularSensorPlugin\RectangularSensorPlugin\bin\Debug">
          </NETUiPlugin>
        </Category>
  </CategoryRegistry>
</AGIRegistry>

This XML file must be saved in one of these three locations, where STK will see it:

1. STK User Config Plugins directory (usually My Documents\STK 11\Config\Plugins)

   Plugins registered here will be available only to the single user with access to this My Documents folder. Usually does not require administrative privileges.

2. All Users Application folder (C:\ProgramData\AGI\STK 11\Plugins on Windows 7 and Vista, or C:\Documents and Settings\All Users\Application Data\AGI\STK 11\Plugins on Windows XP)

   Plugins registered here will be available to all STK users on this machine. Usually does not require administrative privileges.

3. STK install directory (usually C:\Program Files (x86)\AGI\STK 11\Plugins)

   Plugins registered here will be available to all STK users on this machine. Usually requires administrative privileges to save/modify files here.

For more detailed information and additional options for creating the XML manifest, refer to the Registration with a Plugin Point (i.e. Category registration) help topic.

Implement the IAgUiPlugin Interface

The next step is to change the class to implement the IAgUiPlugin interface.

1. Add a class variable to store a pointer to the IAgUiPluginSite interface:

   [C#]
   private IAgUiPluginSite m_psite;

   [Visual Basic .NET]
   Dim m_psite As IAgUiPluginSite

2. Append the interface name to the class declaration:

   [C#]
   public class MySampleUIPlugin: IAgUiPlugin

   [Visual Basic .NET]
   Public Class MySampleUIPlugin Implements IAgUiPlugin

3. For C#, right-click the interface (IAgUiPlugin). Select Implement Interface, then Implement Interface again. For VB, at the end of the Implements IAgUiPlugin line, hit the Enter key.

   This will implement the IAgUiPlugin interface, exposing its members.

4. Edit the OnStartup method as follows:

   [C#]
   public void OnStartup (IAgUiPluginSite PluginSite) { m_psite = PluginSite; }

   [Visual Basic .NET]
   Public Sub OnStartup(PluginSite As AGI.Ui.Plugins.IAgUiPluginSite) Implements AGI.Ui.Plugins.IAgUiPlugin.OnStartup m_psite = PluginSite End Sub

5. Edit the OnShutdown method as follows:

   [C#]
   public void OnShutdown () { m_psite = null; }

   [Visual Basic .NET]
   Public Sub OnShutdown() Implements AGI.Ui.Plugins.IAgUiPlugin.OnShutDown m_psite = Nothing End Sub

6. Save and build the project.

The OnInitializeToolbar and OnDisplayContextMenu methods are addressed in the topic Add a Toolbar Button or Menu Item. The OnDisplayConfigPage method is addressed in the topic Add a Custom Config Page.

Confirm your UI Plugin in STK

1. Launch STK.
2. From the Edit menu, select Preferences, then UI Plugins.
3. Locate the plugin that you just created ("MyCompany.MyCSharpUIPlugin") in the list of available UI Plugins. Ensure that the Active flag is enabled.

The Active flag is enabled when a valid UI plugin is running. If the "Active" flag is not enabled, open the STK Message Viewer and look for any related error messages. Check that:

• The assembly is registered for COM Interop.
• The ProgID in the XML manifest matches the ProgID specified in the public class of your UI plugin.
• The XML manifest must be properly formatted and saved in the proper location.

STK Programming Interface 11.0.1