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 CONNECT Software Development Kit (SDK) that software developers use to create their applications.

The SDK has two libraries: the MicroStationAPI, which provides a C++ interface. The DgnPlatformNet, which is a .NET API.

The MicroStationAPI is the sole API for C++ programmers. Earlier versions of MicroStation provided the MicroStation Development Library (MDL). MDL is not available as a separate API with MicroStation CONNECT, but is subsumed into the MicroStationAPI. This article attempts to clarify and explain the MicroStationAPI from a developer's viewpoint.

C++ Namespaces

Namespaces are part of the C++ standard. Visual Studio provides the C++ compiler and linker required for MicroStation development. The compiler implements the C++ standard. The Visual Studio IDE recognises C++ namespace definitions.

A namespace defines a scope. Variables and classes in that scope belong to that namespace …

namespace LA_Solutions
{
	int v1;
}

We've defined a namespace LA_Solutions. In that namespace we've declared variable v1. v1 can be used both inside and outside the namespace. However, outside the namespace it should be qualified with the namespace name …

namespace LA_Solutions
{
  int v1;
}

v1 = 1;                // Won't compile
LA_Solutions::v1 = 1;  // OK

Nested Namespaces

A namespace can be nested inside another namespace. If an entity is declared in a nested namespace, then it must be fully-qualified when used outside the enclosing namespace …

namespace A
{
  int v1;

  namespace B
  {
    double v2;
  }
}

v1 = 1;         // Won't compile
A::v1 = 1;      // OK

v2 = 1;         // Won't compile
B::v2 = 1;      // Won't compile
A::B::v2 = 1;   // OK

Namespaces are Open

A namespace defines a scope, as above. Namespaces are open, meaning that you can subsequently declare entities in that same namespace quite easily …

namespace A
{
  int v1;
}

A::v1 = 1;      // OK

namespace A
{
  int V2;
}

A::v2 = 1;      // OK

Visual Studio and Namespaces

The Visual Studio IDE understands C++ namespaces. Just as the example above won't compile if variable v1 is not qualified by the namespace, nor will the IDE recognise an unqualified variable. That is, IntelliSense will recognise LA_Solutions::v1, but it won't recognise v1 when used outside the LA_Solutions namespace. If you've typed a variable name and wonder why IntelliSense doesn't give you information about that variable, then think about namespaces.

MicroStationAPI Namespaces

The MicroStationAPI document says this about namespaces …

The APIs are contained within the Bentley Namespace. There are nested namespaces within the Bentley Namespace that hold various parts of the API. Refer to the Namespaces section for a list and description of all Namespaces. MicroStationAPI documentation namespaces

The MicroStationAPI makes extensive use of nested namespaces. For example, Bentley::MstnPlatform::Element.

MicroStationAPI Namespace Declarations

The Bentley Namespace is defined in header file Bentley.r.h.

MicroStationAPI Namespace Macros

The definition of Bentley Namespace is convoluted, because it's defined in terms of a macro …

#define BENTLEY_NAMESPACE_NAME Bentley
#define BEGIN_BENTLEY_NAMESPACE namespace BENTLEY_NAMESPACE_NAME {

Not forgetting …

#define END_BENTLEY_NAMESPACE   }

Using the Bentley Namespace

What you should write in your C++ source code is …

#include <Bentley.r.h>
BEGIN_BENTLEY_NAMESPACE
... your code that calls Bentley stuff inside Bentley namespace
END_BENTLEY_NAMESPACE

Or, write a using namespace declaration like this …

#include <Bentley.h>  //  Note different header
USING_NAMESPACE_BENTLEY
... your code that calls Bentley stuff inside Bentley namespace

When using namespace is called, you don't need to prefix entity names with the namespace prefix.

Nested Bentley Namespaces

There are many namespaces defined by Bentley Systems that are nested inside the scope of namespace Bentley.

For example, header file DgnPlatform.h introduces namespace Bentley::DgnPlatform. That in turn introduces namespace Bentley::DgnPlatform::DgnHistory. Macro USING_NAMESPACE_DGNPLATFORM_DGNHISTORY provides a consistent way to use that namespace.