MicroStation®
MicroStation is Bentley Systems' premier 3D/2D computer-aided-design product. One of its many strengths is its adaptability. Inherent to that adaptability are tools to customise and extend MicroStation.
User Customisation
MicroStation lets an administrator modify its user interface. You can create custom menus, toolboxes, and icon buttons that provide a fast track to commands and functions that you use frequently. You can store those customisations in a DGNLIB that you make available to all your users, so that everyone has the same user interface and task-specific tools. These customisation tools are not discussed further here: they are well documented in MicroStation's delivered help manuals.
Application Development
This article is written for application developers. It focusses on the formal programming languages provided with MicroStation CONNECT: VBA, the C++ MicroStationAPI and the C# DgnPlatformNet.
The MicroStation Development Library (MDL) still exists in MicroStation CONNECT. However, MDL is subsumed by the MicroStationAPI, and most functions have been moved into C++ namespaces.
Deprecated Languages
Some development languages have been deprecated in previous versions of MicroStation. Those languages have been removed from MicroStation CONNECT …
- MicroStation BASIC
- JMDL
If you are developing for Bentley PowerDraft, see these comments for PowerDraft developers.
VBA, MDL, MicroStationAPI, DgnPlatformNet
Bentley Systems provide several programming languages to enable the development of extensions to MicroStation. Extensions are also known as Plug-Ins or Add-Ins. Current development languages include …
| Visual Basic for Applications | VBA™ or MVBA |
| C# and VB.NET | .NET |
| MicroStation Development Library | MDL™ |
| MicroStationAPI | C++ Interface |
Older versions of MicroStation provided languages that are no longer used for new development. Obsolete development languages are …
| MicroStation BASIC | Not compatible with VBA |
| MicroStation Java | JMDL™ |
| User Command Macros | UCMs |
Development Strategies
For in-house development, use VBA, the MicroStationAPI or the DgnPlatformNet.
For commercial development, use the MicroStationAPI or the DgnPlatformNet. Each provides a robust development toolset. From MicroStation CONNECT Bentley encourages us to use Visual Studio 2013 as the primary development tool, writing code in Visual C++ or C#.
The MicroStationAPI: it provides a set of C++ classes and MDL functions. Most MDL functions exist in namespaces (with earlier versions of MicroStation, all MDL functions were in the public namespace).
The DgnPlatformNet API is a set of native C# classes. They let you write native C# code (Earlier versions of MicroStation require you to write C# code that calls VBA methods via a COM InterOp).
The Bentley MDL development tools don't have the most up-to-date Interactive Development Environment (IDE). However, from MicroStation V8 it's possible to use Visual Studio as a development tool, where the IDE is Microsoft Visual Studio.
Although VBA provides significant functionality, there are certain security aspects of the language that make it unattractive to commercial developers. At the time of writing, MicroStation VBA does not support all MicroStation CONNECT features.
Performance
A MicroStationAPI application written using Visual C++ always wins. Why? Because the MicroStationAPI is MicroStation's optimised API, and C++ is compiled using Microsoft's optimising compiler. With that combination, you have the best performing code. If your application needs to do heaps of number crunching, then an MDL project built using Visual C++ will provide the best result.
Here's what Herb Sutter has to say about C++ and performance. This citation is taken from Dr Dobb's Interview with Herb Sutter …
Managed languages are perfectly appropriate where your goal is to optimize programmer productivity above all else, even at the cost of performance by having always available garbage collection that you can't turn off, always available metadata, always available JIT execution, and a virtual machine whether you're actually using it or not, you bear the cost. But, you make the programmer so much more productive. Great. That's what you should optimize for if your biggest cost and constraint is programmer productivity. But more and more, at least part or all of your of your application needs to optimize for performance per dollar, or performance per watt, performance per transistor – because you can only put so many of them in a device. And that's why C++ is the preeminent language, because it's the king of performance per dollar. That's why it's making a comeback.
VBA is interpreted code.
It has a high overhead in procedure calls and especially when invoking object references (i.e. anything that requires a Set statement).
However, VBA provides a comfortable and fast development environment.
If speed of development is important to you, then VBA is a good choice.
If application performance is important to you,
then VBA is a good way to prototype an application before turning it over to the language experts.
UCMs? Not even Intergraph Corporation claimed any performance from UCMs, and the development environment (a text editor) is not what we expect in the 21st century.
Training
The Bentley Institute offers training in many Bentley technologies, including MicroStation VBA, the MicroStationAPI and DgnPlatformNet.
LA Solutions offers training and consultancy in VBA, the MicroStationAPI and DgnPlatformNet.
Contact LA Solutions using this
enquiry form.
Visual Basic for Applications
Bentley Systems have licensed Microsoft's Visual Basic for Applications Toolkit and extended it to provide MicroStation-specific functionality.
VBA is …
- well supported, both by Bentley and by the user community
- well documented
- provided with plenty of examples
- well integrated with MicroStation
- flexible
- suitable for small to medium size projects
- extensible with COM DLLs
- extensible by calling functions in …
MicroStation VBA shares its interactive development environment (IDE) with VBA implemented in other applications. In other words, if you've used the IDE with MicroStation VBA, you already know how to use VBA with other products, including Microsoft Office tools such as Word™ and Excel™. The IDE is similar, though not identical, to that of Microsoft Visual Basic.
One of MicroStation VBA's many strengths is extensibility.
You can create a generic project (a .mvba file) that provides functions and methods you want to use many times.
By referencing one project into another you can call the referenced procedures: you don't have to copy them or write them again.
You can also add functionality in an ActiveX component, which is a DLL created using Visual Basic.
There are a few more benefits obtained from creating an ActiveX component in this way.
Not only can you reuse the functionality in VBA, but also in other VB projects.
MicroStation VBA also provides the necessary COM interface that other applications can use.
In other words, you can write a VB or VBA program in some other application, such as Microsoft Word™ or Excel™.
By referencing the MicroStationDGN.Application object, other VB/VBA code can invoke MicroStation functionality.
There are a number of articles about MicroStation VBA.
VBA Implementations
For a long time, Microsoft has told us that VBA is old-fashioned and we should convert to VB.NET. However, their own Office products include VBA, and have done so for many years. Despite Microsoft's own words of advice, VBA remains in Office. What you may not have noticed, because Microsoft has chosen not to publicise it, is that VBA7 has arrived!
Yes, Office 2010® and later include VBA 7! There are both 32-bit and 64-bit versions of VBA 7. VBA 7 is implemented in MicroStation CONNECT.
Windows Win32 API
You can call the Windows Win32 API from VBA and MicroStationAPI native-code. You may want to make Win32 API calls to use features of Windows that are not exposed by VBA. To learn more about Win32 API possibilities, we recommend that you search the web for sites that offer VBA examples and help.
MDL API
The MicroStation CONNECT MDL API reference documentation no longer includes VB procedure declarations for most MDL functions. One obstacle is that MDL functions now live in MicroStationAPI namespaces, and there's no way to inform VBA about a function qualified by a namespace.
VBA as a language knows nothing about pointers, pointer arithmetic, or memory allocation and memory deallocation. Using such functions from VBA is rather like giving someone a map of Paris, France and asking them to use that map to find an office in Los Angeles, California.
In general, it's wise to stay clear of any MicroStationAPI function that requires you to allocate memory.
For example, mdlElmdscr_read reads an element and allocates memory pointed to by an MSElementDescr* pointer.
At some time you must deallocate that MSElementDescr block of bytes using mdlElmdscr_freeAll.
Debugging hybrid code is a nightmare.
If you fail to free that memory, your code will at best leak memory or, worse, crash MicroStation.
Because VBA knows nothing about C memory management, it can't respond when things go wrong.
If, through VBA, you cause a memory problem, there's no way to handle it.
Usually a memory problem results in a MicroStation crash,
and you don't know what part of your code caused it nor why it happened.
As a rule-of-thumb, if you find the need to use more than four or five MicroStationAPI functions in your code, it's time to re-think your development strategy. Using the wrong tools for a job, as we learn from experience, leads to a poorly-executed job. The right tool for the job gets the job done efficiently, in a timely fashion, and is easily maintained. The right tool for the job in this case is a real MicroStationAPI or DgnPlatformNet application.
DgnPlatformNet
Microsoft .NET languages provide a rich user interface. Visual Studio's IDE has of course excellent support for the .NET languages C# and VB.NET. Visual Studio .NET includes useful database and XML development tools. The LINQ technology provided with .NET 3.5 and later enhances productivity enormously.
You can write a COM server (ActiveX component) using .NET, then call it from your VBA or C++ code. This enables programmer productivity using Visual Studio combined with simple MicroStation interfacing via VBA.
When writing a .NET application that works with MicroStation CONNECT, you use the DgnPlatformNet API.
MicroStation CONNECT provides some C# examples \SDK\Examples folder.
MicroStationAPI
The MicroStationAPI is C++. Its functionality in some cases supersedes what is available through MDL. In other cases the MicroStationAPI provides functionality not available elsewhere.
Because it is C++, the MicroStationAPI can be used only for applications that are built using a C++ compiler and linker. You can continue to use MDL functions in the same source code as MicroStationAPI classes, so you get the best of both worlds.
The MicroStationAPI is …
- supported by Bentley
- tersely documented
- short on examples
- well integrated with MicroStation
- flexible
- optimum performance
- suitable for small to large projects
There are a number of articles about the MicroStationAPI.
MicroStation Development Library
MicroStation CONNECT includes many MDL functions in the MicroStationAPI. There is no longer a separate MDL: MDL functions live in C++ namespaces.
You can write an application using Visual Studio and call MDL functions from your C++ code. With MicroStation CONNECT, MDL code must be compiled using Microsoft Visual C++ as a native-code DLL. This both enhances programmer productivity through the use of C++ object-oriented concepts and provides better performance. When writing C++, you can additionally take advantage of the MicroStationAPI.
MDL continues to offer the most versatile development tool at the expense of complexity and a requirement to understand the C++ language …
- Well supported, both by Bentley and by the user community
- Well documented
- Plenty of examples
- Well integrated with MicroStation
- Flexible
- Optimum performance
- Suitable for small to large projects
There are a number of articles about the MicroStation Development Library.
In order to create a MicroStation application using the MicroStationAPI or the DgnPlatformNet API, you should understand at least five of the following …
- Your user requirements
- MicroStation
- 2D and 3D vector algebra
- An appropriate programming language
- The C++ language if planning to use the MicroStationAPI
- The C# language if planning to use the DgnPlatformNet
- Visual C++ 2013
Bentley PowerDraft®
Bentley PowerDraft is Bentley Systems' lower cost 3D/2D computer-aided-design product. PowerDraft supports VBA, MDL, and native-code DLLs just as MicroStation does. However, although it includes the VBE development environment it includes no MDL or MicroStationAPI development tools. Rather, you develop applications for PowerDraft using MicroStation as the development platform.
A further complication is created by two restrictions on PowerDraft that affect developers …
- Bentley Systems have restricted those native-code DLLs that will work with PowerDraft. Any DLL must be provided with a password to work with PowerDraft. Only Bentley Systems can provide the password, which is paired with the name of your DLL. For more information, contact Bentley Systems
- PowerDraft is not delivered with all the DLLs provided with MicroStation. In other words, some functionality is missing. From the developer's point of view, your application can't call functions in non-existent DLLs. The missing DLLs are documented in PowerDraft's ReadMe file.
For more information, contact Bentley Systems.
