MicroStation and Application Development

MicroStation® is a computer-aided-design (CAD) tool produced by Bentley Systems. It is used by engineers, architects, and draughting technicians to create 3D models and 2D drawings.

MicroStation can be customised. Bentley Systems themselves have many applications for specialised markets that use MicroStation as a platform. Third-parties likewise may use MicroStation as a platform on which to develop their application software. Bentley Systems provide the MicroStation Software Development Kit (SDK) that software developers use to create their applications.

The CONNECT SDK has three libraries …

This article concerns the MicroStationAPI. The MicroStationAPI contains thousands of functions that provide a C++ interface.

This article provides a note about the various iterators available to examine or modify DGN data.

Collection Enumeration Diagram

MicroStationAPI Enumerable Objects

A MicroStation DGN file is a container: it contains one or more DGN models. A DGN model is also a container: it contains DGN elements, reference attachments and other objects. Some DGN elements, such as a cell, are also containers: they contain nested elements and perhaps other data.

If we want to interrogate or modify a DGN file, DGN model or a complex DGN element we need some way of iterating that structure to enumerate each object that it contains. This article provides a brief overview of those enumerators.

Enumeration Patterns

We can enumerate each object in a conforming container using C++ 11's ranged-for syntax …

for (auto o: container) { /* do something with o */ }

That provides a concise replacement for the hand-written for loop you may have written in the 20th century …

for (int index = 0; index != some-value; ++index) { auto o = container [i]; }

However, the container must be iteratable for the ranged-for to compile successfully. More precisely, it must provide the following methods and operators …

The standard containers, such as std::vector<>, meet those requirements. For example, if you have a vector of 3D data points, you can iterate it like this …

VectorDPoint3D points { /* fill point array from somewhere */ };
for (DPoint3dCR point: points)
  /* Do something with point */

For an explanation of VectorDPoint3D, see MicroStationAPI Boost and the C++ Standard Library. For an explanation of DPoint3dCR, see MicroStationAPI Structures, Typedefs, and #include .

Enumerable Classes in the MicroStationAPI

The MicroStationAPI and its ancestor MDL (the MicroStation Development Library) provide both legacy (i.e. C-style) enumeration functions and 21st century enumerable collections. Many C++ class methods fill a standard collection of objects (e.g. bvector<T>) which are simple to enumerate using legacy or ranged-for iteration.

The Bentley Vector (bvector<>) is a proprietary design based on std::vector<>. The MicroStationAPI documentation tells us: This class is used in the Bentley APIs to avoid dependencies on compiler-supplied implementations of std::vector<> that sometimes vary with compiler settings or compiler versions. The bvector<> class does not suffer from these problems. This makes bvector<> suitable for use in Bentley public APIs.

In our own code, we can use the standard collection classes std::vector<>, std::deque<>, std::map<> etc.

VirtualCollectionIterator class

The MicroStationAPI provides a template class VirtualCollectionIterator<IteratorImplementation>.

You can inherit from that class to make your own class iterable if you don't want to reveal its internal structure. If your IteratorImplementation class has the following public methods, then you can use it in ranged-for and other loops …

For example, the ModelIndex class, mentioned below, inherits from VirtualCollectionIterator<IteratorImplementation>.

In the topics that follow, I'll show some MicroStationAPI collections and the MDL function family they replace.

Object Description Example
ModelIndex Each DGN file has a list of models, stored in the model index ModelIndex Example
Loaded Models Collection A list of DGN models that are currently loaded Reachable Model Collection Example
Reachable ModelRef Collection A list of references attached to a model Reference Iteration Example
Enumerating Elements Enumerate the elements in a DGN model Element Iterators
Complex Element Iteration Enumerate the nested elements in a complex header ChildElemIter Example
Item Type Instance Iteration Find instances of Item Types attached to a DGN element EC Instance Iterator Example