Bentley Communities
Bentley Communities
  • Site
  • User
  • Site
  • Search
  • User
OpenUtilities
  • Product Communities
OpenUtilities
OpenUtilities Wiki Creating promis.e V8i Plug-ins
    • Sign In
    • +OpenUtilities
    • Access Service Request Manager
    • +Bentley sisHYD Multi Utility
    • Design Features - promis.e Functionality - Promis.e Standard
    • +OpenUtilities sisNET - English
    • +OpenUtilities Substation
    • Promis.e Paths
    • -Promis.e Wiki
      • +CONNECT Edition - Promis.e
      • About Promis.e
      • +Administration Features - Promis.e
      • -APIs_VBA - Promis.e
        • Creating promis.e V8i Plug-ins
      • +Automation Features - Promis.e
      • +Component Features - Promis.e
      • +Component Management - Promis.e
      • +CONNECT Services - Promis.e
      • +Data Manager - Promis.e
      • +Database Platform Support - Promis.e
      • +Display - Promis.e
      • +Drawing Management - Promis.e
      • +Engineering Design Considerations - Promis.e
      • Error - Object reference...General
      • +Find_Replace - Promis.e
      • Finding the Tutorial
      • +Installation_Configuration - Promis.e
      • +Interoperability - Promis.e
      • +Licensing - Promis.e
      • +Maintenance Features - Promis.e
      • +Migration - Promis.e
      • +OS Support - Promis.e
      • +Panel Layout - Promis.e
      • +Performance - Promis.e
      • +PowerPlatform Support - Promis.e
      • +Print_Publish Features - Promis.e
      • +ProjectWise Integration - Promis.e
      • Promis.e Help file
      • +Reports_Output Features - Promis.e
      • +Template Management - Promis.e
      • +Text Tools - Promis.e
      • Training FAQs
      • +Wire Numbering - Promis.e
      • +Wiring Features - Promis.e
      • +Project Management - Promis.e
      • Promis.e Title
      • Working from home with Promise.e
    • Replace Family - Find_Replace - Promis.e
    • SQL Server Login

     
     Questions about this article, topic, or product? Click here. 

    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 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 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 Program data folder to the "plugins" subfolder of the Program folder.  The only file that needs to be in the \plugins\MyPlugins subfolder of the Program data folder is the config.xml.  Similarly, this file can be removed from the \plugins\MyPlugins subfolder of the 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
    • APIs_VBA
    • promis.e
    • Programming
    • how to
    • Customization
    • Bentley Substation
    • en
    • Share
    • History
    • More
    • Cancel
    • Jordan Stierly Created by Jordan Stierly
    • When: Thu, Jun 3 2010 10:12 AM
    • Matt_P Last revision by Communities MVP Matt_P
    • When: Thu, Mar 15 2018 5:21 PM
    • Revisions: 15
    • Comments: 11
    Recommended
    Related
    Communities
    • Home
    • Getting Started
    • Community Central
    • Products
    • Support
    • Secure File Upload
    • Feedback
    Support and Services
    • Home
    • Product Support
    • Downloads
    • Subscription Services Portal
    Training and Learning
    • Home
    • About Bentley Institute
    • My Learning History
    • Reference Books
    Social Media
    •    LinkedIn
    •    Facebook
    •    Twitter
    •    YouTube
    •    RSS Feed
    •    Email

    © 2023 Bentley Systems, Incorporated  |  Contact Us  |  Privacy |  Terms of Use  |  Cookies