Introduction

The MicroStation Development Library (MDL) and MicroStationAPI provide APIs 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.

When editing your source code, you can choose whether to use Microsoft Visual Studio, Microsoft Visual Studio Code, or one of your favourite text editors.

When building your app, you can use Visual Studio or the Bentley Systems make (bmake) tools.

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.

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.

Questions

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