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.
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).
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.
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.
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#.
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; } }
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 …
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.
StartedAsInitApp
shows how to use the BeFileName
class to compose a file name from other components.
StartedAsInitApp
shows how to use the BeTextFile
class to open and write to a text file.
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.
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.
Post questions about C++ and the MicroStationAPI to the MicroStation Programming Forum.