Introduction

The MicroStationAPI provides an Application Programming Interface for developers wanting to create custom applications for MicroStation^® from Bentley Systems. We create a MicroStation application as a DLL, written using C++ and built with the Microsoft C++ compiler and linker provided with Visual Studio.

Init App

Most applications (or AddIns) for MicroStation are intended to be interactive. A user loads an AddIn using the key-in command …

mdl load AddIn

The AddIn loads and presents its user interface (UI).

Quiet Operation

We may want to automate MicroStation in some way; for example, to execute a multi-file analysis. In that case we don't want to show MicroStation to the user — we want to do something with one or more files and then finish. That's the purpose — the raison d'être — of an MS_INITAPP (InitApp) application: it starts, it performs some work and then, quietly, it terminates.

An InitApp is loaded with the Windows key-in …

MicroStation.exe -waInitApp

Where InitApp is the name of your AddIn. The -wa switch instructs MicroStation to start without graphics, and load the AddIn named InitApp.

Depending on how your InitApp operates, you may want to pass one or more arguments. It's customary for an InitApp to prefix each argument with -i. For example …

MicroStation.exe -waInitApp -iArg1 -iArg2  …

MicroStation doesn't use arguments Arg1 or Arg2, which are for your InitApp to interpret.

You can specify multiple InitApps using configuration variable MS_INITAPPS. You provide a list of AddIns that you want processed as MicroStation starts.

DGN App

Another way to load AddIns automatically is through the MS_DGNAPPS configuration variable. You provide a list of AddIns that you want processed as MicroStation opens each design file.

The difference between an InitApp and a DgnApp is that a DgnApp is started after MicroStation has started and shown to the user. An InitApp is loaded before MicroStation has shown any Windows or graphics. When an InitApp loads, MicroStation has not opened any DGN file.

InitApp C++ Example

The InitApp example, which you can download below, is written with C++ using the MicroStationAPI library. The .NET API available with MicroStation CONNECT lets you do something similar using C#.

MdlMain

The MdlMain is the entry point for all MicroStation C++ AddIns. The function classifies the way in which the app was start by checking the MdlApplicationClass …

#include <Mstn/MdlApi/mssystem.fdf>

MdlApplicationClass appClass {mdlSystem_getMdlAppClass (nullptr)};
switch (appClass)
{
    case MdlApplicationClass::User:
    {
        StartedByUser (argc, argv);
        break;
    }
    case MdlApplicationClass::InitApp:
    {
        StartedAsInitApp (argc, argv);
        break;
    }
    case MdlApplicationClass::DGNApp:
    {
        StartedAsDgnApp (argc, argv);
        break;
    }
}

StartedAsInitApp

Our function StartedAsInitApp is called if the app was started with the -wa switch. Remember, at this point MicroStation is invisible to the user: it is not displaying any dialogs or views.

StartedAsInitApp examines the command-line arguments and switches. It's looking for a DGN file name work on. If it doesn't find a file name, then it has nothing to do and exits. If it does find a file name, then it operates as follows …

• MicroStation -wainitapp — Will not work because a design file name was not passed
• MicroStation -wainitapp -itest.dgn — will work without graphics initiated
• MicroStation -wainitapp -itest.dgn -ig — will work with graphics initiated

If StartedAsInitApp finds a DGN file name, then it …

1. Opens the DGN file
2. Performs some processing
3. Writes the results of the processing to a text file
4. Exits

In this example, the processing performed in step 2 is trivial. The app searches the active DGN model for lines and line-strings, and returns the number found. Because no graphics are visible, we can't display the line-count to the user. Instead, we write the line-count to a text file linecount.txt in the current working directory.

If the -ig switch is present, then StartedAsInitApp calls mdlSystem_enterGraphics() and MicroStation appears to the user.

Useful C++ Classes

BeFileName

StartedAsInitApp shows how to use the BeFileName class to compose a file name from other components.

BeTextFile

StartedAsInitApp shows how to use the BeTextFile class to open and write to a text file.

std::filesystem

std::filesystem is a standardisation of Boost::FileSystem. It's a welcome alternative to the hotch-potch of file and folder functions in the C library.

Download the InitApp Example

The InitApp example code is provided as-is and without guarantee of suitability for any particular purpose. The source code is available in this MicroStation C++ project. Unpack the ZIP archive and copy the source code to your preferred folder. A good place to copy it, if you're using MicroStation CONNECT, would be ..\SDK\Examples\Miscellaneous. You can then build it from the SDK command shell.

Questions

Post questions about C++ and the MicroStationAPI to the MicroStation Programming Forum.