Creating promis.e V8i Plug-ins


 Product(s):Promis.e V8i
 Version(s):08.11.08 and higher
 Environment:N/A
 Area:APIs_VBA
 Subarea:N/A

Background

For years, Microsoft has provided developers with the tools needed to produce software applications. Beginning in 2005, Microsoft began to offer a free version of the Visual Studio software to enable anyone with a computer to write their own software applications.

The promis.e V8i software allows the development of custom plug-ins using the Microsoft .NET Framework. Whether you are an experienced software developer with access to the professional versions of Visual Studio, or you are just getting started with the Express Edition, this guide will help you develop your first promis.e V8i Plug-in.

Setting Up the Development Environment

Any version of Visual Studio 2005 or 2008 and any .NET language can be used to develop plug-ins for promis.e. This guide covers using Visual Basic 2008 Express Edition, as it will be the easiest product to obtain and use for most Promis.e users. However, a more advanced version of Visual Studio may be used, just as the C# language may be used.

The following URL is the starting point for downloading the Express Edition products from Microsoft. Download and install the Visual Basic 2008 Express Edition, unless you have a desire to use an alternate product.  A download link may need to be searched for, but Visual Basic 2008 Express Edition could be downloaded from the following link when this article was last updated.

http://www.microsoft.com/en-us/download/details.aspx?id=6506

Upon completion of the install, start Visual Basic. Your screen will look something like this:

VB Startup Dialog 

Create the Plug-In

Create your first plug-in by following these steps:

  1. Go to File > New Project… This will bring up the New Project window.  Click the Class Library icon to select it, then enter "MyPlugin" into the Name field.
    New Project 
  2. In the Solution Explorer window, right-click on MyPlugin and select Properties.
    Solutions Explorer 
  3. The project properties will appear in the main window. Here we will set several project properties that control how the project is built and run. Click the Compile tab. For the "Build output path" field, click Browse and select the "plugins" subfolder of the [[5366|Program data folder]].  The MyPlugin folder will not exist initially. You may create this folder manually, or Visual Basic will create it when the project is first built.

     
  4. Click the References tab. Here we will add references to the promis-e assemblies. Click the Add… button. Select the Browse tab. In the "Look in" field, browse to the [[5365|Program folder]]. Select the file: ECT.ECAD.API.dll – (General API)


    When the file is added to the references list, its Copy Local property will be set to True. Set Copy Local to False by selecting the reference and changing the value in the Properties window.


     
  5. At this time we should save the project. Go to File > Save All. You will be prompted to save the project. You may use the default settings or change the Location path.
    Save Project 
  6. In the Solution Explorer, right-click on MyPlugin and go to Add > New Item… In the Add New Item dialog, click the icon for Text File to select that type, and enter config.xml into the Name field. Click the Add button.  
  7. The config.xml file should open.  If not, double click it in the Solution Explorer to open it in the main window. Add the following content to the file:

    <?xml version="1.0" encoding="utf-8" ?>
    <Config Enable="true" EntranceModule="MyPlugin.dll" EntranceClass="MyPlugin.Class1" />

     
  8. In the Solution Explorer, right-click on MyPlugin and go to Add > New Item… In the Add New Item dialog, click the icon for Text File to select that type, and enter description.xml into the Name field. Click the Add button. 
  9. The description.xml file should open.  If not, double click it in the Solution Explorer to open it in the main window. Add the following content to the file:

    <?xml version="1.0" encoding="utf-8" ?>
    <Descriptions Author="My Company"
    Name="MyPluginName"
    Version="XX.XX.XX.XX"
    ReleaseDate="">
      <Desc>MyPlugin</Desc>
    </Descriptions>
     

    The Plug-in Manager which you can access within promis.e by selecting Manage > Plug-in Manager uses the information in this description.xml to populate the dialog as shown here:
    Plug-in Manager  
    The Active toggle determines whether or not this plug-in will be loaded the next time you start the software. If you don’t wish the software to automatically load your plug-in you can turn off this toggle.

    Note: Advanced users can edit the Assembly Information (either in the project properties or in the AssemblyInfo.vb file) to enter this information. If you use this method it is not necessary to use this description.xml file.

  10. For both config.xml and description.xml, select the file in the Solution Explorer. In the Properties window, set the Copy to Output Directory property to Copy if newer. 
    Config XML Properties 
  11. In the Solution Explorer, double-click the Class1.vb file to open it in the main window. It is time to write the code for the plug-in. Enter the following into the code editor (note that the "_" line continuation character is used for readability):

    Imports ECT.ECAD.API
    Imports ECT.ECAD.API.PlugIn
    Imports System.Collections

    Public Class Class1
         Implements IPlugInBase

    Public Sub Init() Implements ECT.ECAD.API.PlugIn.IPlugInBase.Init
         Root.App.DrawingTool.RegisterCustomMenu("My Plugin")
    End Sub

    Public Sub OnCustomMenuCommand(ByVal strCommand As String) _
         Implements ECT.ECAD.API.PlugIn.IPlugInBase.OnCustomMenuCommand

         Dim cmd As String = UCase(Replace(strCommand, "#", " "))
         Select Case cmd
              Case "MY PLUGIN"
                   MsgDemo()
         End Select
    End Sub

    Public Sub RegisterCustomMenu(ByRef arrMenu As ArrayList, _
                                                                   ByRef arrMode As ArrayList) _
         Implements ECT.ECAD.API.PlugIn.IPlugInBase.RegisterCustomMenu
         arrMenu = Nothing
         arrMode = Nothing
    End Sub

    Public Sub Unload() Implements ECT.ECAD.API.PlugIn.IPlugInBase.Unload

    End Sub

    Private Sub MsgDemo()
         MsgBox("This is my plug-in!")
    End Sub

    End Class

  12. The plug-in is now complete. Select File > Save All.
  13. Select Build > Build MyPlugin.
  14. Copy the MyPlugin folder and its contents from the "plugins" subfolder of the [[5366|Program data folder]] to the "plugins" subfolder of the [[5365|Program folder]].  The only file that needs to be in the \plugins\MyPlugins subfolder of the [[5366|Program data folder]] is the config.xml.  Similarly, this file can be removed from the \plugins\MyPlugins subfolder of the [[5365|Program folder]]. 
  15. Start promis.e V8i. There should be a Plug-Ins menu. Go to Plug-Ins > My Plugin. You will see the message box called out by the plug-in code.
    Message Box 

Debugging a Plug-In

When there are errors in a program, it is often helpful to run the program line-by-line in order to find where a problem is occurring. It is possible to set up Visual Studio to launch MicroStation or AutoCAD (or simply promise.exe if using promis.e V8i Standalone SELECTseries 5 or higher) and start promis.e. You can then have breakpoints set in your code in order to watch and debug the execution of your program.

MicroStation/PowerDraft Debugging

The first step is to enable advanced build configurations. Go to Tools > Options… Under Project and Solutions>General, check Show advanced build configurations if it is not already checked. Click OK.

Advanced Build Options 

Go to Build > Configuration Manager... Select Debug as the Active solution configuration. Click Close.

Configuration Manager 

Right-click MyPlugin in the Solution Explorer and select Properties. Select the Debug tab. The following items need to be set:

Command line arguments:

"C:\Program Files\Bentley\promis-e\EctEcad.dgn" "-wsms_dgnapps=C:\Program Files\Bentley\promis-e\EctEcad.ma" "-r" -wc"C:\Program Files\Bentley\promis-e\support\promisev8i.cfg"

Working directory:

C:\Program Files\Bentley\promis-e\

Debug Settings 

At this point, the project has been set up to build under the Debug configuration, which will include additional data in the build that Visual Studio will use to enable line-by-line debugging of the plug-in. The Start Options that were just set will direct MicroStation to load the promis.e environment. The only thing that hasn’t been done yet is to tell Visual Basic to launch MicroStation. The method of doing this depends on whether you are using Visual Studio Express Edition or Professional Edition.

Express Edition

If you are using Visual Basic Express Edition, there is no option in the Debug settings to launch an external application. This feature was intentionally left out of the Express Edition user interface. Fortunately, there is a workaround to this by editing a project file.

Save the project. Use Windows Explorer to go to the project folder. (If you are not sure where the project folder is, select MyPlugin in the Solution Explorer. The project folder will be listed in the Properties window.) Look for the file “MyPlugin.vbproj.user”.

Explorer 

Open this file in Notepad. If the file is not present, make sure you have followed the other steps in this section and have saved the project.

Two new elements need to be added to the XML, StartAction and StartProgram. The content of the MyPlugin.vbproj.user file should end up looking similar to the following. The StartAction and StartProgram elements that must be added are shown in blue.

Startup Actions 

Note: The actual path to use for ustation.exe (MicroStation) or draft.exe (PowerDraft) depends on where the software is installed.

Close and reopen the project in Visual Basic in order for the updated file settings to be loaded. Open Class1.vb and set a breakpoint at the line “MsgBox("This my plug-in!")”. Go to Debug > Start Debugging. The project will build and MicroStation will start and load promis.e. From the Plug-ins menu, select My Plugin, as you did earlier. This time, execution will pause at the breakpoint.

Note: If you get any errors related to LoaderLock you can ignore them and click continue to proceed. If you wish you can turn of LoaderLock by deselecting it in Debug > Exceptions > Managed Debugging Assistants.

Debugger 

Visual Studio Professional Edition

If you are using Visual Studio Professional, setting up the debugging environment is a somewhat easier than in the Express Edition. In addition to the Start Options set earlier in the Debug page, you should also select Start external program and enter the path to the main MicroStation executable.

Debug Options 

Standalone Debugging

To debug promis.e V8i Standalone (SELECTseries 5 or higher), follow the instructions above, but use the settings in this section instead.

In the Debug tab of the Properties dialog make these settings:

Command Line Arguments: "C:\ProgramData\Bentley\promis-e V8i(M)\Config\Ecad.dgn"

Working Directory: C:\Program Files (x86)\Bentley\promise V8i\promise\

To execute an External program enter this: C:\Program Files (x86)\Bentley\promise V8i\promise\promise.exe

AutoCAD Debugging

To debug promis.e using AutoCAD, follow the instructions above, but use the settings in this section instead.

In the Debug tab of the Properties dialog make these settings:

Command Line Arguments: "C:\Program Files\Bentley\promis-e\ECAD.dwg" /b "C:\Program Files\Bentley\promis-e\autocad2007\autoload2009.scr"

Working Directory: C:\Program Files\Bentley\promis-e\autocad2007\

To execute an External program enter this: C:\Program Files\AutoCAD 2009\acad.exe

Note: The actual external program path to use depends on the location of acad.exe. If AutoCAD 2006 is used, use the autocad2006 subfolder and the script file in that folder. If AutoCAD 2007 – 2009 is used, use the autocad2007 subfolder and the appropriate script file in that folder.

 Original Author:David Graat & Scott Walker, Bentley Software