MicroStation CONNECT SDK - Introduction


MicroStation CONNECT Edition is one of the largest software undertakings Bentley has taken since the initial release of MicroStation V8.  This special edition of the BDN Newsletter will provide an overview of what programming options are available in the new MicroStation CONNECT Edition and MDL SDK. 

Please take a moment to review the detailed contents of this extended newsletter.  Questions regarding support issues for the MicroStation CONNECT Edition SDK should be posted in the Bentley Communities MicroStation Programming Forum.

How to Download and Explore the MicroStation CONNECT SDK - Video Overview

Programming Options with MicroStation CONNECT Edition

Whether you are a MicroStation user, CADD administrator, someone interested in getting started with programming in MicroStation, or an intermediate to advanced software developer; MicroStation CONNECT Edition provides everyone options suited toward your individual level of experience and needs. The graphic below helps illustrate each of the options available, what knowledge each solution requires, and the progression users with no programming experience can work towards someday creating the most robust MicroStation programming solutions possible.Beyond Configuration

MicroStation CONNECT Edition SDK Overview

The following sections describe new features within the new SDK. It should be noted that MicroStation CONNECT Edition SDK requires Microsoft Visual Studio 2013.

Reorganized and Refactored: APIs, includes, and libraries
The MicroStation CONNECT Edition SDK now installs as a "stand-alone" product separate (yet dependent) on the MicroStation parent product. Allowing developers to install multiple versions of the SDK side-by-side or install to custom locations that meet your individual needs or requirements.  MicroStation APIs, includes and libraries have been reviewed, organized, and isolated, to help ensure a new level of improved consistency between native and managed APIs opening up new API possibilities.

Completely New: Native MDL C++ and Managed MDL .NET APIs
Within the new SDK you will find, a comprehensive set of MDL C++ API libraries you can more fully leverage within Microsoft Visual Studio 2013; apply elegant C++11 coding styles and techniques, STL programming, and much more. MDL .NET APIs are a thin managed wrapper around the high performance MDL C++ libraries and use similar library and terminology naming conventions. The new .NET managed API assemblies are no longer based on MicroStation VBA’s – Microsoft COM object model. This more direct level of access ensures improved performance and reliability; as well as more accurate error messages.

Leverage MicroStation's GUI administrative tools to make creating and designing common UI components with ease. Choose to extend your application UI using your choice of preferred UI development APIs; like:

  • Bentley's MDL native dialog manager
  • Microsoft's native MFC, WinForms, or WPF APIs

Enhanced: MicroStation Developer Shell.
The development environment has been improved to be more developer-centric and friendly. The MicroStationDeveloperShell.bat (previously known as: mstndevvars.bat) has received a complete refresh providing useful environment troubleshooting information and the ability to perform your own or shared custom pre and post processing actions via "MicroStation Developer Shell Extensions"

The MicroStation Developer shell title bar can quickly determine:

  • If you are using a 64-bit or 32-bit Microsoft command shell (cmd.exe)
  • If you are running as an administrative user
  • The Microsoft Visual Studio required for the MicroStation version you are developing for

Pathing includes the standard development tools and the new MigrationTools

Updated: Many new code samples
A number of new MDL programming samples are available to explore and learn, as well as, an improved organization of samples using easy to identify categories of application development.  It is now easier to find what you need with even more samples to come!

A "legacy" MDL samples directory is provided as a point of reference when performing 1:1 application migrations. Exploring the new API programming samples and documentation, ensures you will find practical, modern, and preferred coding samples using the most recent MicroStation APIs.

Updated: API Documentation
The MDL SDK documentation has undergone a large number of changes.   Some of the changes and additions to the SDK documentation are:

  • API documentation is automatically generated as part of our product build process, directly extracting developer comments embedded within the API header files, and a list of expanding documentation Contents and Articles.  Bentley developers are now able to provide quick and consistent documentation changes for the next release all right from within their source code editor.
  • API documentation implements an improved organizational layout strategy providing and improving consistency and organization of content.
  • MicroStationAPI.chm  - A convenient single help file that allows you to explore documentation for both the MDL native C++ and C APIs.  Since the documentation is derived directly from the include files, this makes it convenient to search in one spot a less frequently search include directories directly.
    TIP: Make sure to check out a number of new and updated MDL API topics located under: "Modules > Contents & Articles"
  • DgnPlatformNet.chm - A convenient single help file that allows you to explore managed code documentation for the MDL DgnPlatformNET API and namespace, DgnEC, and Elements.

New: MigrationTools
The MigrationTools directory contains remapping tools that allow you to begin the process of porting existing MDL application code to MicroStation CONNECT Edition.

A majority of MDL developers are likely to take a 1:1 migration path first. The MigrationTools directory provides a convenient starting point to remap (search and replace) over 2800 common items within your project source code files.

Consider using migrate.bat as your first pass in a 1:1 migration. Since it performs these common, repetitive, and possibly error prone tasks:

  • Create a zip file of all files (and child folders) under the current directory
  • Locates a list of all current valid source code files to process
  • Modifies each file directly with search and replace actions defined in the delivered .remap (regular expression file)
  • Creates MigrationReport.txt a report containing (the number of) changed items (per file), start and finish times, or troubleshooting information if errors occur

Please note: the MigrationTools require the download and installation of Python 2.7. The resulting Zip file generated is not intended to replace a well-founded backup solution or strategy. Always make sure to back up your source code and/or source code management system data regularly

Overview: Migration Tools

The MigrationTools directory provided in the MDL SDK is an entry point to help developers get started when performing a 1:1 source code migration of existing MicroStation V8 MDL applications to MicroStation CONNECT Edition.

As with all source code projects, a good backup and branching strategy is highly recommended prior to performing bulk or unintended edits of your source code files necessary when migrating to a new product version.  With that said and your backup complete, let's take a look at the purpose of Migrate.bat and the delivered files and their purpose.

Migrate.bat

  • Validates MSMDE being defined (standard when run from the MicroStation Developer Shell), otherwise logs the current environment variables for your or peer review in the log file: MigrationReport.txt
  • Validates Python 2.7 being installed, otherwise logs the current environment variables and decision when prompted to download and install a compatible version.
  • Performs a recursive zip archive of all files under the current parent project directory.
  • Performs a recursive search of all valid source code file extensions; currently: .c .cpp .h .fdf .hpp
  • Calls Python.exe passing the following arguments:
    • ApiRemapper.py.  The overall python script that performs source code file remapping
    • 0811to1000Published.remap.  The regular expression search and replace (remap) file
    • SourceCodeFileSpec.  The full path, name, and file extension (FileSpec) of a valid source file to remap
  • Opens MigrationReport.txt using your default .txt source code editor.
    • The top section of the report provides:
      • Processing Start Time
      • Search path and method used to find Python 2.7. e.g. Registry or OS Path
    • The bottom section of the report provides
      • Start/Finish Times
      • Number of valid source code files processed
      • Summary list of modified files and number of edits performed

NOTES:  If a prior zip file in the naming convention of ParentDirectoryName.zip is encountered the file will be renamed to include the Current Time backup was performed as part of the new file name, then the current project files will be added to ParentDirectoryName.zip.

A future update will likely change the behavior to rename the file to use the LastModified date and time of the original file vs. the current method.

After running Migrate.bat and reviewing the report results your next step will be to attempt to compile each migrated application under your parent project.  If you have not done so, we highly recommend to confirm the integrity of your development environment by compiling one or more of the delivered MDL example projects (e.g. ..\examples\buildallexamples.bat) from the MicroStation Developer Shell.

Once you can compile the delivered examples you should attempt to compile one of your applications with confidence having been processed by the MigrationTools.  Please note that unless you have the most basic app, you can and should expect to make several iterative passes: compiling, searching includes and forums, making edits, and re-compile; until you finally have an MDL application converted and ready to run in MicroStation CONNECT Edition.  This process is typical of what application developers are required to perform when migrating a source code project from a major version change of product; like when going from MicroStation v08 to MicroStation v10.

Applying the steps above should help provide a productive first step to assist in your migration efforts.  Depending on your application complexity, substantial product and API changes and your need for input and guidance, or skills and timelines; below are some relevant links for finding some additional assistance.

For more information on Migrating to CONNECT please visit: Developers Migrating to MicroStation CONNECT

Resources

Whether you are new to MicroStation Programming or the BDN program, or a seasoned developer familiar with both; it is good to have a list of high-level links to make sure you can find the right information you need quickly.  Below is a list of useful links to help get you started in the right direction.  Please note the second set of links requires BDN membership to obtain access.