Information for Plugin Developers
SAP2000 external plugins can be developed to make use of the SAP2000 API from inside the program.
No license is required to use the API beyond having a valid license for SAP2000 or CSiBridge. However, technical support for developing with the API is not included. For qualified users and third-party developers who would like technical support to help them build solutions and integrations with SAP2000 using the SAP2000 API, Computers and Structures, Inc., has created a subscription-based service, CSI Developer Network (CSIDN) (see http://www.csiamerica.com/support). You would need to subscribe to CSIDN to be eligible for technical support for SAP2000 API.
Plugins can be developed in a .NET compatible language (e.g. Visual Basic 2012, Visual C#, etc.), or any language capable of creating a COM server compiled as a DLL. An example plugin project can be found at: https://wiki.csiamerica.com/display/kb/Sample+Plugin+1
Requirements and suggestions:
- SAP2000 will look for the plugin by Type Library name (usually the name of the PlugIn project), which you define when developing your COM server DLL. We suggest using a unique name such as SAP2000PlugIn_xxx_yyy, where xxx is your (company) name, and yyy is the name to distinguish the plugin from other plugins that you develop. For example, SAP2000PlugIn_ABCinc_Template1.
- SAP2000 is not looking for specific GUID’s. Choose unique GUIDs for the plugin.
- The plugin must reference the SAP2000v20 API library (either SAP2000v20.DLL or SAP2000v20.TLB ), which must be registered on the developer’s and the user’s systems.
- Before SAP2000 can call the plugin, the plugin must be registered for COM (or for COM interop for .NET DLLs) on the user’s system. It is your responsibility to instruct the user how to install the plugin. This should be done after SAP2000 has been installed.
- We will attempt to maintain a stable interface in SAP2000, however, that cannot be guaranteed, and updates to your plugin may be required for future versions of SAP2000.
- All functionality must be implemented in a class called cPlugin.
- Class cPlugin must have a subroutine cPlugin.Main() that expects a reference to SAP2000v20.cSapModel and SAP2000v20.cPluginCallback:
Public Sub Main(ByRef SapModel As SAP2000v20.cSapModel, ByRef ISapPlugin As SAP2000v20.cPluginCallback)
- Class cPlugin may have an optional function cPlugin.Info() that expects a reference to a string, and returns a Long (32-bit signed integer). The return value should be zero if successful. The string is to be filled in by the function, and may be plain text or rich text. If this function is found and returns zero, the string will be displayed when the user first adds the plugin to SAP2000. You can use this string to tell the user the purpose and author of the plugin. This is in addition to any information you may provide when the user executes the plugin.
Public Function Info(ByRef Text As String) As Integer
- SAP2000v20.cPluginCallback contains a Finish() subroutine that is to be called right before the plugin is ready to close (e.g., if the plugin has a single main window, at the end of the close event of that form). It expects an error flag (0 meaning no errors) to let SAP2000 know if the operation was successful or not. SAP2000 will wait indefinitely for SAP2000v20.cPluginCallback.Finish() to be called, so the plugin programmer must make sure that it is called when the execution of the plugin code is completed.
Public Sub Finish(ByVal iVal As Integer)
- It is OK for cPlugin.Main() to return before the actual work is completed. (e.g., return after displaying a form where the functionality implemented in the plugin can be accessed through different command buttons). However, it is imperative to remember to call SAP2000v20.cPluginCallback.Finish() to return the control back to SAP2000 when the plugin is ready to close.
- Our testing has indicated that modal forms in .NET DLL’s are problematic when shown within a SAP2000 external plugin, especially if you try to perform refresh operations to the views or windows.
- If you want to provide multiple functionality in your plugin, you can provide options for the user when subroutine Main is called. Options for the user to obtain information about the product, developer, technical support, and help should be provided. Support for your plugin will not be provided by Computers and Structures, Inc.
- As currently implemented, the cPlugin object will be destroyed between invocations from the SAP2000 Tools menu command that calls it, so data cannot be saved. All operations in the plugin must be completed before the user can perform any other operations within SAP2000 itself.
- Please make sure your plugin is stable, handles errors well, and does not cause any unintended changes to the user’s model.
