You can develop an application for MicroStation CONNECT using several different programming languages. Here are answers to questions about using the MicroStationAPI C++ Software Development Kit (SDK) and Microsoft Visual Studio.

Q Have you any hints about developing an application for MicroStation using the MicroStationAPI?

A You may want to read about application project structure and consult the MicroStationAPI documentation files provides with the SDK. It's not always easy to understand how to configure your computer to build a MicroStation application. This article discusses several aspects of configuration to get you started.

MicroStationAPI Project Structure

A MicroStationAPI project contains a number of header files, implementation code files and resource data files. The SDK provides tools that compile those code & resource modules into binary object files. Linker tools merge your object files into an executable application (.dll) file.

MicroStationAPI code lives in a set of source (.h, .cpp, .r & .mt) files. Source code is plain text, which you create with a suitable text editor. You could, if determined to make your life miserable, attempt to develop using Windows Notepad™, but you are well advised to find a programmer's text editor. There are some text editors mentioned here.

Of course, Visual Studio is an excellent source code editor, as well as integrating the build tools (compiler, linker etc) into a single environment.

Some people like to use Visual Studio as a code editor and use bmake to buid their project. That may seem a curious approach, but it has some merit, especially when your project contains a lot of MicroStation resources as well as C++ code.

Bentley Tools

Bentley provides tools (executable files) for building MicroStation applications in the
\MicroStation\SDK\bin folder. You don't normally use those tools directly: prefer to invoke them using the Bentley Make (bmake) utility.

A native application (.dll) for MicroStation is delivered in two files …

  1. An app. resource binary having a .ma extension. It contains …
    • Message lists
    • Command tables
    • Dialog box definitions
    • Type resource data
    • DLL management information
  2. A DLL executable binary having a .dll extension. It contains …
    1. Your compiled application implementation
    2. Windows compiled resources …
      • Windows dialog box definitions
      • Windows message lists
      • Version information

MicroStationAPI implementation code is plain old C++ and lives in a source code (.cpp) file. Typically your code file will #include a header (.h) file that defines various constants and C++ preprocessor macros common to all files in your project. You compile MicroStationAPI source code with the Visual Studio C++ compiler.

Application dialog and message list files live in resource code (.r) files. Type resource definitions live in resource type (.mt) files. Typically your resource code file will #include a header (.h) file that defines various constants and C++ macros common to all files in your project. You compile MicroStation resource code (.r and .mt files) with the Bentley rcomp tool.

The result of MicroStationAPI code and resource compilation is a set of object files. To create your executable application, those files are merged together using Visual C++ linker tools. MicroStation message lists and dialogs are linked using the Bentley Systems resource linker rlib. The Bentley Systems linker mlink is used to create a resource binary file.

Bentley Make Tool

The tools described above are typical of the tools found in many development environments. Long ago, developers became tired of the multi-stage process required to build an application, and developed the make file to control that build process.

A make file contains all the rules necessary to build a particular application from its source files. The rules invoke the appropriate tool for each step in the process. In the world of MicroStation, we use the Bentley make tool (bmake) to interpret the rules in a make file that you write for your MDL project.

Your make file (.mke) includes the set of rules required for your C++ application. When you invoke the make tool, it knows how to build your application. Instead of having to invoke each tool separately, your build task is simply this … 

bmake MyApp

Understanding make files is hard. The Bentley make files are especially convoluted and use many %include (*.mki) files. Although there's no definitive manual for Bentley make files, there is help elsewhere on the web. The O'Reilly press book Managing Projects with GNU Make may be helpful …

Managing Projects with GNU Make

Windows Environment Variables

The definitive source of environment variable settings for MDL development is the batch file MicroStationDeveloperShell.bat provided by Bentley Systems with the MicroStation SDK. See the section below for more information about that batch file.

When executed, MicroStationDeveloperShell.bat creates a command shell — a Windows environment — that defines a number of Windows environment variables for you. In other words, if you build an MDL project using MicroStationDeveloperShell.bat you don't need to define any environment variable. If you're new to MicroStation development, use the command shell to create your build environment.

For more advanced MicroStation developers, the following list attempts to describe the environment variables defined by MicroStationDeveloperShell.bat. If you want to build projects without the help of that command shell, you nonetheless must define these variables to persuade a project to build correctly. When you define a Windows environment variable that represents a path to a folder that will be used in your build process, pay special attention to the need for a trailing path terminator.

There are several Windows environment variables relevant to MicroStation CONNECT development …

MicroStation CONNECT Environment Variables for Developers

Variable Purpose
MS Specifies the location of the MicroStation executable (ustation.exe), and the default location of the MDL tools root
PATH The location of executable and library files used by Windows
MSMDE Specifies the location for the SDK tools root
BMAKE_OPT Specifies default location for MicroStationAPI #include files
WindowsSdkDir Specifies root location for Windows Win32 header and library files
WindowsSDKVersion Specifies version of the Windows Win32 header and library files

Windows Path Terminators

When defining an environment variable that expands to a path, pay attention to the final path terminator. In Windows, the path terminator is the final backslash (\) character. In general, a path needs a terminator when used in a MicroStation development environment. Often, a path is used in your makefile (or in an %included Bentley makefile) as the starting point for a further path definition.

If your Windows path is terminated, then the make file can build a valid sub-folder name. Suppose you have defined a Windows environment variable MS … 

MS=C:\Program Files\Bentley\MicroStation

The build process may want to create a macro that points to the \mdl\bin folder …

MSMDE=$(MS)mdl/bin/

 … which expands to …

C:/Program Files/Bentley/MicroStationmdl/bin/

Which is wrong! There is no folder MicroStationmdl! The problem is the lack of a path terminator in environment variable MS. Fix it by setting that variable with the path terminator … 

MS=C:\Program Files\Bentley\MicroStation\SDK\

Now the makefile expands the variable to create a valid folder definition … 

C:/Program Files/Bentley/MicroStation/SDK/

Pay close attention to the definitions of Windows environment variables that are used in make files. Ensure that a trailing path terminator is included where required.

Environment Variable  MS

You should define a Windows environment variable MS. Environment variable MS points to the folder where the MicroStation executable (ustation.exe) is installed. That folder is version dependent …

SDK Folder Locations
MicroStation Version MicroStation Executable Location
MicroStation CONNECT C:\Program Files\Bentley\MicroStation\SDK\

Define MS in your computer's settings …

  1. Right-click My Computer on the Windows desktop
  2. Click Properties in the pop-up menu
  3. The System Properties dialog opens
  4. Click the Advanced tab
  5. Click the Environment Variables button
  6. The Windows Environment Variables dialog opens
Windows Environment Variables Dialog

Notice that there are two panes in this dialog. The upper pane, User variables for <USERNAME>, lists environment variables for the current Windows user. In this example, I'm logged into account V8.5. The lower pane, System variables, lists environment variables defined all users of Windows. If you don't have sufficient adminstrator privileges the lower pane may be greyed or absent from this dialog.

Use the upper pane to define your own variables. I use different logins for different MicroStation versions. I can define a unique MS value for each login, so the MDL development environment is always targetted at the right installation of MicroStation.

Use the New button to add a new environment variable. Select an environment variable and click the Edit button to change its value. In this example, I'm editing the MS variable …

Edit Environment Variable Dialog

You can't see the complete value because the text box is too short. Here's the complete string … 

G:\PROGRA~1\BENTLE~1.5\Program\MICROS~1\

Notes …

Windows Short File Names

Windows supports long file names that may include spaces. However, bmake does not support paths that contain spaces. When using bmake it's best to use DOS-style short file names. You can find DOS short file names by opening a Windows command prompt and using the dir/x command.

The manual process to determine a short file name is tedious. It involves a lot of manual cut-and-paste operations.

Mangle.bat

Bentley Systems staffer Robert Hook posted a useful Windows batch file (mangle.bat) to generate the DOS path of a Windows long path. This saves those tedious manual cut-and-paste operations … 

@echo off
:: Show mangled (DOS 8.3 format) path and file name of path provided,
:: or current directory if no arg provided
if /i {%1}=={} (for /f "tokens=*" %%d in ('cd') do echo %%~sd) else
  (for %%a in (%1) do echo %%~sa))

Environment Variable  MSMDE

You should define a Windows environment variable MSMDE. It points to the SDK location, which by default is
C:\Program Files\Bentley\MicroStation CONNECT\SDK You can specify a different location for MicroStation development tools using this variable.

Environment Variable  WindowsSdkDir

This variable points to the root folder that contains Windows platform SDK header and library files. The folder is created when you choose all options during Visual Studio installation.

The variable is set in a Windows shell by the MicroStation CONNECT tool MicroStationDeveloperShell.bat. It is typically something like
C:\Program Files (x86)\Windows Kits\10\

Environment Variable  WindowsSDKVersion

This variable is the name of a sub-folder in the root Windows platform SDK folder. The folder is created when you choose all options during Visual Studio installation.

The variable is set in a Windows shell by the MicroStation CONNECT tool MicroStationDeveloperShell.bat. It is typically something like
10.0.10586.0\

Window Platform SDK Location

The location of the Windows SDK header and library files is found by concatenating WindowsSdkDir, WindowsSDKVersion and some text strings. For example, the folder containing header files is …
%WindowsSdkDir%Include\%WindowsSDKVersion%\um which, when expanded, turns out to be
C:\Program Files (x86)\Windows Kits\10\Include\10.0.10586.0\um

Environment Variable  BMAKE_OPT

You should define a Windows environment variable BMAKE_OPT. This defines a list of folders that contain MDL include files. In a default installation those folders are …

If you have the SDK installed in MicroStation's sub-folders (the default location on installation), then you can define the above variables in terms of the MS variable. In the Windows Environment Variables dialog, define BMAKE_OPT like this … 

BMAKE_OPT=-I%MSMDE%include\

Environment Variable  PATH

You should define additions to the Windows environment variable PATH. PATH is likely to be defined already: it's needed by many applications so that Windows may locate their executable code and relevant DLL files. For more information about PATH, consult the Windows documentation.

It's important not to overwrite the existing definition of PATH. If you assign a value to path PATH=C:\Program Files\xxx your computer will probably not function properly. You need to define PATH by extending its existing definition, like this: PATH=%PATH%;C:\Program Files\xxx.

For C++ development, the folders to add to PATH are the MicroStation folder, which contains DLLs; the \SDK\bin folder, which contains the Bentley make tools (bmake.exe, mcomp.exe, etc.); and the \SDK\library folder, which contains precompiled object library files. 

PATH=%MSMDE%\bin;%MSMDE%\library;%MS%;%PATH%

Visual Studio

You can use Microsoft Visual Studio to build a MicroStation CONNECT application. You can also use the Bentley make tool, bmake, which invokes the C++ compiler and linker provided with Visual Studio.

Visual Studio Versions

Use Visual Studio to build a Windows DLL that links to MicroStation. You must use the correct version of Visual Studio to ensure that your app. is compatible with MicroStation.

Visual Studio 2017

Visual Studio 2017 is not currently supported by the MicroStation CONNECT SDK.

Visual Studio 2015

Installing Visual Studio for C++ development is not as straightforward as it used to be. Please read these notes about Visual Studio installation

Bentley Development Shell

The development shell is a batch script that configures a Windows environment for C++ development. You can find this file in …

To use MicroStationDeveloperShell.bat, open a Windows command prompt and execute it. MicroStationDeveloperShell.bat sets up the Windows environment for you, by defining the environment variables described above. You'll find more about MicroStationDeveloperShell.bat in the MicroStationAPI SDK documentation.

MicroStationDeveloperShell.bat makes it easy to set up the correct environment for compiling and linking an MDL application. The MicroStation installation process updated this batch file with the location of your MicroStation executable, and defines MS, BMAKE_OPT, and MLINK_STDLIB for you.

C++ Projects

Visual Studio

If you are using Visual Studio, then add the …\MicroStation\SDK\include path to the list of include folders in Project Properties.

Your source implementation (.cpp) file should have a list of MicroStationAPI headers beginning something like this … 

#include <Mstn/MdlApi/mdl.h>

That #include statement assumes that the compiler has a directive to find the root include folder, which is ..\SDK\include.

Bentley Make (BMake)

If you are building using Bentley Make (bmake.exe), then add the path to the include list using the cincapnd.mki macro. In your make file, add something like this … 

dirToSearch = $(MSMDE)include/
%include cincapnd.mki

You can pass macro definitions to the compiler with the cdefapnd.mki include file … 

nameToDefine = DEBUG
%include cdefapnd.mki

Pure MDL Projects

The MicroStation Development Language (MDL) was part of MicroStation V4 released in 1993. MDL was a C-style language, supported on versions of MicroStation up to V8i.

With MicroStation CONNECT you can write a project using one of several languages. You can't, however, write a C-style implementation using MDL. MDL is not supported by MicroStation CONNECT.

Return to programming articles index.

Questions

Post questions about MicroStation programming to the MicroStation Programming Forum.

Bentley Technology Partner

Trademarks

All trademarks are acknowledged. Trademarks may be registered in some jurisdictions.
e-mail Contact LA Solutions using this enquiry form.

Home
Home 		Updated on 03-Apr-2020 Copyright © 2007…2025 Jon Summers