MicroStation CONNECT .NET Development

Introduction

These articles discuss .NET programming from the viewpoint of a MicroStation developer.

When implementing functionality in .NET, there are Windows environment variables to consider. Questions are posted by developers on the MicroStation Programming Forum.

Q Have you any hints about developing an application for MicroStation using .NET?

What development tools does the SDK provide?
Do I need to define any Windows environment variables?
How do I use the Bentley development tools?
Can I use Microsoft Visual Studio?
Which version of Visual Studio can I use?
What references should I have in my Visual Studio project?

Visual Studio Versions

A Can I use Visual Studio to build my .NET AddIn?

A Which version of Visual Studio can I use?

Read this article for information about versions of Visual Studio.

MicroStation delivers a version of the .NET CLR runtime. You need to make sure that the runtime installed with MicroStation is compatible with your code developed with your installed version of Visual Studio.

Windows Environment Variables

A Do I need to define any Windows environment variables?

When building a .NET project with Visual Studio, you need to specify the correct version of the .NET CLR. From MicroStation CONNECT Update 13 the .NET Framework version is v4.6.2. Earlier versions of MicroStation CONNECT required .NET Framework version v4.6.1.

For unknown reasons it's not always possible to change the .NET framework version in Visual Studio project properties. You can circumvent that problem by defining a Windows environment variable. The variable to set is TargetFrameworkVersion and for MicroStation CONNECT Update 13 its value should be v4.6.2. Once you've set that variable, your Visual Studio projects should use that framework version automatically.

BMake

If you build your MicroStation .NET project using Bentley Make (BMake), then you don't need a Windows environment variable. First, start the SDK shell provided by Bentley Systems: it opens a Windows command prompt with the relevant environment variable defined for you. When you invoke BMake, it calls a number of make include (*.mki) files. Among those is AssertToolSet.mki, which chooses the right .NET framework for you.

References in Visual Studio

A Microsoft calls a .NET DLL an assembly. MicroStation delivers a number of assemblies. You can see those assemblies in folder \MicroStation\assemblies. You should reference some, but not all, of those assemblies in your Visual Studio project.

The assemblies you have always to reference in your .NET add-in project are …

…\MicroStation\assemblies\ECFramework\Bentley.General.1.0.dll
…\MicroStation\assemblies\bentley.interop.microstationdgn.dll
…\MicroStation\assemblies\bentley.microstation.dll
…\MicroStation\assemblies\bentley.microstation.interfaces.1.0.dll
…\MicroStation\ustation.dll

Additionally, if you want to make your dialogs dockable, you have to reference also
…\MicroStation\assemblies\ECFramework\bentley.windowing.dll.

.NET Hints

A Have you any hints about developing an application for MicroStation using .NET?

At the end of the build process you should end up with a .NET assembly that either has the command.xml file embedded in the assembly or as an external resource (.xml file) next to the assembly. Now you need to tell MicroStation where the assembly is located by augmenting the MS_ADDINPATH configuration varialble in MicroStation. We typically do this by creating a configuration file in the appl directory under MicroStation/config/appl. In the file we have one line that is MS_ADDINPATH > "location of where my assembly is". Now once that is in place we can load the addin in MicroStation using the command MDL LOAD AssemblyName. Make sure that your MDL Task ID is not greater than 15 characters (legacy limit).

Visual Studio Hints

Target Framework

In the project Properties|Application page, ensure that the Target Framework is correct for your version of MicroStation. Here, I've chosen .NET Framework version 4.6.2 to match MicroStation CONNECT Update 16.

Class Library

A MicroStation .NET AddIn is always a DLL, not an EXE. That is, your application runs in MicroStation's address space and not as a stand-alone executable.

In the project Properties|Application page, you must ensure that your Visual Studio project creates a DLL. In the project Properties|Application page, ensure that the Output Type is set to Class Library and not Windows Application.

Output Folder

In the project Properties|Build page, ensure that Visual Studio delivers your DLL to the ..\MicroStation\mdlapps folder. Set the Output Path to your location …

Notes …

You may have to scroll down the Properties|Build page to see the Output Path text field.
The MicroStation folder is write-protected. You must run Viz Studio with Windows Administrator privileges to be able to write to the mdlapps folder.

Command Table

If your application has a MicroStation command table then your commands are defined in an XML file named something like Commands.xml. Commands.xml is part of your Visual Studio project and is an embedded resource.

However, it's not sufficient for your project to include a command table. It must also have a special directive in the project configuration (*.proj) file. That file includes an ItemGroup that specifies your command table. However, the LogicalName element may be missing and you must add it manually …

  <ItemGroup>
    <EmbeddedResource Include="Commands.xml">
      <SubType>Designer</SubType>
      <!-- LogicalName name may be missing -->
      <LogicalName>CommandTable.xml</LogicalName>
    </EmbeddedResource>
  </ItemGroup>

Irrespective of the name of your commands file, the LogicalName is always CommandTable.xml.

The LogicalName element is not created automatically: you must edit your project .proj file (it's an XML file, so use a plain text editor) to add that element.

The LogicalName text content is the name of your Commands.xml file. If you name your command table file CommandTable.xml then that ItemGroup should appear thus …

  <ItemGroup>
    <EmbeddedResource Include="CommandTable.xml">
      <SubType>Designer</SubType>
      <LogicalName>CommandTable.xml</LogicalName>
    </EmbeddedResource>
  </ItemGroup>

Return to .NET articles index.

Questions

Post questions about MicroStation programming to the MicroStation Programming Forum.

MicroStation .NET Development