MicroStation .NET: Configuration Variables

DgnPlatformNet

Introduction

This article is for C# developers who want to write an application for MicroStation CONNECT or later. It describes a way to handle configuration variables in your .NET code. This is not a complete application: rather, it describes what might otherwise be a non-intuitive approach to solve a problem.

Be Communities

If you want to ask questions about C# development for MicroStation, post your question to the MicroStation Programming Forum.

Configuration Variables

MicroStation uses configuration variables extensively. As an application developer, you probably want to provide similar flexibility for users of your app. The .NET APIs provides ways to read and set configuration variable values.

DgnPlatformNet Configuration Manager Class

Look in the DgnPlatformNet help documentation to find the ConfigurationManager class. The ConfigurationManager supplies methods that allow users and applications to customize the behavior of programs at runtime.

All ConfigurationManager methods are static, meaning that they are always available and you don't have to create a new instance of the class to use them.

using Bentley.DgnPlatformNET;

string CfgVarName = "MS_DEF"; // Example configuration variable MS_DEF
string cfgVarValue = ConfigurationManager.GetValue (CfgVarName);

Configuration Manager Methods

The ConfigurationManager methods you will often use are …

DefineVariable() defines or redefines a configuration variable and its value
GetVariable() gets the value of a configuration variable (but see Session below)
IsVariableDefined() tests if a configuration variable exists

A useful method, unavailable in other APIs, is ConfigurationManager.WriteActiveConfigurationSummary, which lets you write a list of configuration variables to a text file. It's a developer's version of MicroStation's DEBUG feature.

Temporary Files & Folders

The ConfigurationManager has some methods useful for creating temporary files …

GetLocalTemporaryDirectory() returns a local directory that can be used to store temporary files
GetLocalTemporaryDirectoryBaseName() returns the root of the local directory that can be used to store temporary files. This directory must have write access
GetNameForTemporaryFile() generates a unique name for a temporary file

MstnPlatformNet Session

The MstnPlatformNet Session class provides static member function ExpandEmbeddedVariables() and non-static member function ExpandMacros().

Use Session.ExpandEmbeddedVariables() when you have a string that contains configuration variables of the form $(CfgVar). Those wrapped variables may be embedded in a longer string including plain text. For example, something like …

$(MS_PROJECTDIR)standards/$(USERNAME).dgnlib

Session.ExpandEmbeddedVariables() should expand that string to a fully-qualified path.

Configuration Mgr Example

The Configuration Mgr Example Visual Studio solution uses all the above APIs and more …

You can test the value of a configuration variable and see the result of splitting semi-colon-delimited strings.

Download the Configuration Mgr Example

You can download the Configuration Mgr Example Visual Studio projects. The project was built using Visual Studio 2019 and .NET Framework 4.6.2 as required by MicroStation after Update 13.

The ZIP file contains two Viz Studio projects …

ConfigurationManagerCombined, which combines the ConfigurationManager and Session methods into one interface. It provides in addition a few useful utility methods.
CfgVarExample, which implements a user interface to the above DLL.

This solution is aimed at you, the MicroStation developer. It's intended to help explain the way you can use configuration variables in your code. It's not intended as a real application or pretends to be of any practical use.

MstnPlatformNet Workspace Interface

The MstnPlatformNet help doc tells us about the Workspace Interface. It's a wrapper around the VBA (COM) functionality via an InterOp. It is best avoided in favour of the ConfigurationManager class mentioned above.

Questions

Post questions about MicroStation programming to the MicroStation Programming Forum.