- Important Note
- Installing RemObjects Hydra
- Installing SystemWeaver Visual Studio Templates
- Create a New SystemWeaver Extension Module
- Types of Extensions
- Creating a New SystemWeaver ItemView
- Configuring the swExplorer Plugins
- Debugging the Plugin
- swExplorer Logging
- Assumes use of Visual Studio 2013
- RemObjects Hydra application framework version 188.8.131.527*
- SystemWeaver Visual Studio Templates
- swExplorer.exe installation, including SystemWeaverExtensionsAPI.dll
2 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.
3 Installing RemObjects Hydra
The SystemWeaver C# extensions are based on RemObjects Hydra technology. Therefore, you must first obtain and install RemObjects Hydra. We are currently using version 184.108.40.2067 of Hydra.
Under Custom installation > Visual Studio Integration, you must select to include "Integrate with Visual Studio 2013":
4 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 enclosed in a zip file attached to this article. These templates consist of these files:
- setupTemplates2017.bat (for Visual Studio 2017)
- setupTemplates2010-2015.bat (for Visual Studio 2010, 2013, 2015)
- Running Visual Studio 2019? We are working on making the files available. Contact firstname.lastname@example.org.
Once you have downloaded them, just run the setupTemplates.bat-file for your version of Visual Studio as administrator, and they should be automatically copied to the Visual Studio installation directory and registered with the Visual Studio development environment. The .bat file assumes that you have installed Visual Studio at the default place. If not, you have to edit it and change the path to vcvarsall.bat.
5 Create 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)
6 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.
7 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.
8 Configuring the swExplorer Plugins
The next step is to tell swExplorer where to find the plugin we 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:
9 Debugging the Plugin
To be able to run and debug from Visual Studio, add swExplorer.exe as the startup program for your project.
You will now be able to run the project and your new view should show up under the Extensions option:
If the view does not show up, double-check that the assembly exists in the swExplorerExtensions library and that you are running the swExplorer.exe next to that library.
10 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:
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.
* The version currently required for extension development for SystemWeaver is 220.127.116.117. 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 version 18.104.22.1687.