The article is an introduction to the SystemWeaver Extension API and explains how to get started developing extensions for the swExplorer client. 


Prerequisites

  • Visual Studio version 2013, 2017, or 2019 - Professional or Enterprise.
    May work with other editions as well. This article uses version 2013. 
  • RemObjects Hydra application framework of the version that is compatible with your version of SystemWeaver.
    It must be the version documented here.
RemObjects Hydra Version*SystemWeaver Version
6.2.101.1237R33 or later
  • SystemWeaver Visual Studio Templates (The templates are attached at the bottom of this article.)
  • An installation of the SystemWeaver Explorer client (swExplorer)


Important Note

The SystemWeaver API interfaces and their methods accessible through the extension layer from the client application have been constructed to be as similar to the functions in the .NET Client API as possible. For their usage, we refer to that documentation and generated help texts. However, there are a couple of differences:

Methods Returning Strings: Our .NET Client API follows the best practice that you should never return null, but an empty string instead. However, the way COM works, which is the underlying technology used, empty strings are returned as null. Thus, when using the Extensions API, you have to beware of null strings.


You should also be aware that multi-threading is not supported for the functionality in the Extensions API.   

Windows COM technology is used when calling the swExplorer host, so all the interfaces are only valid and can be called from the thread that starts the extension. This is also the thread that is driving the WPF UI, so the extension API can be used directly from WPF. If you try to call the API on any other thread, you will get the exception: 


System.InvalidCastException: 'Unable to cast COM object of type 'System.__ComObject' to interface type '...'. This operation failed because the QueryInterface call on the COM component for the interface with IID '{GUID}' failed due to the following error: No such interface supported...


Things to Consider

  • SupportsItems and GetGUID make continuous calls so it is important that when either of these two are implemented that the code you include executes as fast as possible. For SupportsItems, e.g., it may not be only the item type it is looking for; there may be other variables. 
  • Use IswExtensionInfo for Stack Trace Display (requires version R38 or later)


Installing RemObjects Hydra

The SystemWeaver C# extensions are based on RemObjects Hydra technology. Therefore, you must first obtain and install a version of RemObjects Hydra that is compatible with your version of SystemWeaver. See Prerequisites above.

Under Custom installation > Visual Studio Integration, you must select to include "Integrate with Visual Studio 2013":



Installing SystemWeaver Visual Studio Templates

To make it easy to create new plugins, we recommend that you use our templates. The SystemWeaver Visual Studio Templates are attached at the bottom of this article. 



Once you have downloaded them, just run the .vsix as administrator, and they should be automatically copied to the Visual Studio installation directory and registered with the Visual Studio development environment. The assumed path for the .vsix and .bat files is Documents\Visual Studio 2019\Templates. If not, you have to edit it and change the path to vcvarsall.bat.

Creating a New SystemWeaver Extension Module

A SystemWeaver extensions module is a .NET assembly containing one or several extensions. If you have correctly installed the SystemWeaver Visual Studio Templates, you should be able to create a new project of type SystemWeaver Extension Module (WPF):



You must keep the beginning of the name: “SWExtension.” since it is used by convention by the swExplorer to find the extension modules. Next, add a reference to the SystemWeaverExtensionsAPI.dll which you should be able to find in the folder swExplorerExtensions in your swExplorer installation directory:



You should now have:

  • The RemObjects Hydra references
  • A SystemWeaverExtensionsAPI reference
  • A Module Controller (which is provided by Hydra to act as a broker between the host and the extensions)



Types of Extensions

Today, there are three types of extensions:

  • Item-view: Adds a new item view to the specification view pane to the right of the structure tree.
  • Item-command: Adds a new button to the Items tab ribbon, which can be enabled depending on what item has been selected in the application.
  • Attribute-popup-editor: Adds a new attribute-editor which is shown as a modal window when you click the Edit button in the attribute-editor.
  • MultiInstanceItemView: Adds a new item view to the specification view pane to the right of the structure tree. It allows for multiple, simultaneous configured ItemViews unlike Item-view which can have only one active instance. 


Creating a New SystemWeaver ItemView

Select add item and select the appropriate template as below:



This will create the files necessary for an item-view:

There are two classes. One class implements the item-view extension interface. This is a small class, of which a single instance is created at the start of the SystemWeaver client. It contains the logic for when the view should be displayed in the GUI, depending on what is selected in the structure tree in an Item tab. The other class is the actual visible form, i.e., the content to be shown. When a user selects this view in the SystemWeaver client, an instance of this content-class will be created and displayed by the client.


At this stage it should be possible to compile the project. However, to run the project, continue reading.


Note: Available icons for GetImageIndex can be found in Available Icon Images for Configuration Items.


Configuring the swExplorer Plugins

The next step is to tell swExplorer where to find the plugin you are developing. At this time, there is only one way to do this. By default, the swExplorer.exe always looks for extensions in the directory swExplorerExtensions which should we located beside the swExplorer executable. In this library, the swExplorer searches for all names with the name: 'SWExtension*.dll', i.e., all dlls starting with the text: "SWExtension."


We suggest that you change the output path in your extension assembly to the swExplorerExtensions directory:



Debugging the Plugin

To be able to run and debug from Visual Studio, add swExplorer.exe as the startup program for your project.



Be sure that the assembly exists in the swExplorerExtensions library and that you are running the swExplorer.exe next to that library. 



In addition, make sure that the extension view is set to Active in Configure the explorer. 



You will now be able to run the project and your new view should show up under the Extensions option:



swExplorer Logging

If you have a problem getting the extension to load at all, you can get more details during the startup of swExplorer by enabling the swExplorer logging mechanism. This is done by putting an swExplorer.props in the same directory as the executable. There should be a template called swExplorer.props.example in your distribution directory. Rename it and edit the line:


log4d.appender.Fil1.fileName=D:\SystemWeaverClient\swExplorer.log


to specify where to put the log file. If you run the swExplorer with this props file, you can see details about the loading of the extensions and if they have succeeded or if something went wrong.


* Systemite does not sell or provide RemObject Hydra. The Hydra that is delivered in our installation is used by those extensions that Systemite provides with the delivery. If customers want to develop their own extensions using Hydra, they must purchase a Hydra license from RemObject.  When you purchase RemObjects Hydra, you are purchasing a license to access any of their versions. You can then log in to RemObjects Software Customer Portal where you can download the version that is compatible with your version of SystemWeaver.