How to create a managed document plugin
Recently a partner, experimenting with creating a managed document plug in, discovered that it was not nearly as simple to create a .net document plugin for SuperOffice, as it is with the default VB6 sample application, SoDocPluginSoArc. In this article I would like to describe and demonstrate the steps necessary to get a .NET SuperOffice document plugin assembly working. Essentially, the steps required are listed in the following ten step process.
- Use SN.exe to create two new KeyPair files. You'll use these for creating strong name assemblies - one for the Type Library DLL, and one for the document plugin (or you can choose to use the same SNK file for both).
- Copy DocumentInterface.tlb from the ClientSDK to a known directory.
- Using DocumentInterface.tlb, use TLBIMP to generate a managed, signed assembly that contains the
- Reference the assembly in your document plugin project.
- Implement the methods of
- Copy both the managed reference
IDocumentInterfaceassembly and your document plugin to the SuperOffice directory.
- Place your document plugin and reference managed
IDocumentInterfaceassembly, in the GAC (Drag and drop or use GACUTIL). As an alternative, skip this step and use the RegAsm /codebase switch in step eight to hard-code the assembly path (See InstallDocPlugin.bat). (Not recommending for deployment scenarios, only in testing).
- Use REGASM to register the document plugin, as well as create a type library file for your document plugin, and register it. As an alternative to step 7, use the RegAsm /codebase switch to hard-code the assembly path (See InstallDocPlugin.bat).
- Append a Module section in the SoLoader.ini file (located in Client directory, for example C:\SuperOffice\Client) and the filename of your document plugin under the [Files] section.
- Start SuperOffice and select the document archive plugin from the Preferences\System options.
Start off by creating a strong name key file that will be used to sign the assembly that will contain the
IDocumentInterface definition, as well as your document plug in assembly. As seen below, open a Visual Studio Command Prompt and use the SN.exe utility to generate the keypair file.
Next, you will need a managed version of the
IDocumentInterface declaration to reference in the document plugin. Using the DocumentInterface.tlb and the keyfile you just generated, use the TLBIMP.exe utility to generate a managed assembly that contains the
IDocumentInterface definition. See code below. Do not forget the /keyfile:yourKeyFile.snk switch, as both this assembly, and the document plugin, require a strong name.
Now you should have a strong name key file to sign your document plugin assembly, as well as the signed assembly that contains the
IDocumentInterface definition. Now it is time to create the solution.
Create a new class library solution and name it in accordance with the SuperOffice naming scheme for document plugins, for example SoDocPlugin_YourPluginName. When the class library project is created, create a reference to the assembly that contains the IDocumentInterface, see below. Rename the default class to something you like, for example
Since this assembly is being consumed in a COM environment, it will need to be visible in that COM environment. To make this happen, a few things first need to be set. This includes making the class COM Visible, assigning the class a GUID value, as well as setting the class interface type. Using VB.NET in VS 2005, this is all done for you if you creating a COMClass library when first creating the solution. However, in C#, this is accomplished by decorating the class declaration with the appropriate attributes. As seen below, these include: COMVisible, GUID, and ClassInterface. Optionally, you can also set these values in the project properties>AssemblyInformation window.
Next, you must implement each method defined in the
IDocumentInterface in accordance with guidelines specified in the Client SDK (Reference > Plugin Systems > Document Plugin API).
The most crucial method in the interface is
GetPlugInProperty. When SuperOffice starts, the method is called and the pluginId value is requested. If the value returned is not unique, an error will be displayed telling you two plugins have the same id and then the offending document plugin will not be loaded.
When finished implementing the plugin, copy all referenced assemblies into the SuperOffice directory.
Next, your document plugin assembly, as well as the managed
IDocumentInterface assembly, needs to be placed in the Global Assembly Cache (GAC). Do this by either dragging and dropping your assembly into the WINDOWS\assembly directory, or using the GACUTIL.exe utility:
In order for SuperOffice to discover your document plugin, SuperOffice must be able to detect the class that implements
IDocumentInterface, and call each interface method as necessary. Since SuperOffice is not be able to read a ,Net assembly, you must generate a type library with the same name as your plugin (or at least starting withSoDocPlugin), which exposes this information for your assembly. To do this, use the REGASM.exe utilty. Open a Visual Studio Command Prompt and generate the type library:
Finally, modify the SoLoader.ini file and test the plugin.
Open the SoLoader.ini file, found in the SuperOffice\Client directory, and create a new module section:
[Module:SuperOffice Plugin] Regsvr = No ForceRegsvr = No NoOverWrite = No RebootIfInUse = Yes UpdateOnly = No Shared = No
As seeing in Listing Two, add your document plugin assembly name and module group assignment to the [Files] section.
[Files] ; ... List Omitted For Brevity SoDocPluginMyDocumentPlugin.dll = SuperOffice Plugin
Now it's time to test. Open SuperOffice and verify your plugin is listed in the Preferences > System > Default document archive list:
In this article, I talked about how to create a SuperOffice Document Plugin using managed code. As you can see, creating a managed document plugin for SuperOffice is not exactly an easy task - but not impossible either.
I want to thank Jose Aparicio (Scarp) for kicking off the experimentation, and contributing the VB.NET code (See downloads above). I would also like to thanks Christian Mogensen for his insight to the plugin process and hints, as well as Helene Hansen for her tireless efforts of actually stepping through the debugging process and allowing me to see the SuperOffiice plugin process first hand. Good Job!