MicroStation .NET: User Settings Manager

DgnPlatformNet

Introduction

This article is for C# developers who want to write an application for MicroStation CONNECT. It describes a way to handle our User Settings Manager 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.

The Problem that User Settings Manager Solves

An application, including MicroStation AddIns, often wants a user to set various variables or preferences. For example, the user might want to choose a specific folder as an location for the app. to place files. User may reasonably expect the app. to remember her choice the next time she uses it.

There is no default way that saves and restores user settings in a .NET app. The User Settings Manager is a universal way to persist and restore settings programmatically. You include the settings manager library in your .NET project and call the methods of UserSettingsManager.

Be Communities

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

User Settings Manager

An app often wants to persist user settings or preferences. This is just as true of a MicroStation AddIn as it is of a stand-alone executable. This article describes a settings manager that can be used in any .NET app.

User Settings Manager Specification

Settings Manager stores data in an XML file. The file and its folder must have read-write access for the Windows user. MicroStation stores its user preferences data in a location something like this …

C:\Users\user-name\AppData\Local\Bentley\MicroStation\10.0.0\prefs

Settings Manager stores data key-value pairs. The data are organised into named sections, each of which which holds one or more key-value pairs. Section names are created by you, enabling a semantic connection between the data and your AddIn. Sections may be nested.

Settings Structure

The storage medium is XML, and keys and data are not strongly typed and are visible as plain text in the XML file. Settings Manager offers methods to cast data to specified types.

Settings File Structure

Settings are stored in an XML file named after your application. You don't need to know anything about XML to use Settings Manager.

The root XML element is settings. The root is the parent of an arbitrary number of sections and key-value pairs. The structure is not pre-defined: you configure it programmatically to suit your app.

The API lets you add and remove sections, to which you can assign a name relevant to your app. You add key-value data pairs to a section. Keys are unique per section. Values are whatever you like. Here's an XML fragment that illustrates a small settings file …

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<settings>
  <ItemInstanceHarvester>
    <data key="prop 1" value="data 1.1" />
    <data key="prop 2" value="data 2.2" />
    <data key="prop 3" value="data 3.3" />
    <data key="prop 4" value="data 4.4" />
  </ItemInstanceHarvester>
  <cellHarvester>
    <data key="col 1" value="70" />
    <data key="col 2" value="60" />
    <data key="col 3" value="50" />
    <data key="col 4" value="40" />
    <data key="col 5" value="30" />
  </cellHarvester>
</settings>

.NET Assembly

SettingsManager is a 64-bit .NET assembly implemented in a DLL. It uses Framework v4.6.2 to be compatible with MicroStation CONNECT Update 13 and later.

Class UserSettingsManager

Manages user settings for a MicroStation add-in. Settings are stored in an XML file in the MicroStation user's home folder. For example, for Windows user CONNECT using the SettingsExample AddIn discussed below, the settings file might be …

C:\Users\<USERNAME>\AppData\Local\Bentley\MicroStation\10.0.0\prefs\SettingsExample.settings

Where USERNAME is the Windows user name of the current (logged-in) Windows account.

Constructor, File and DOM Management

UserSettingsManager Constructor

Construct a new UserSettingsManager object. Pass the app name as the only parameter. The app name is used to compose the settings file name.

You will find several methods of UserSettingsManager …

Create a data element that stores a key-data pair
Find a data element by its key
Find a named section
Create a named section

Settings Example

Settings Example is a Visual Studio project that builds a MicroStation AddIn. It uses the UserSettingsManager library. It has a dialog (.NET Form) that lets a user interact with preferences and settings. When the user clicks the Save button, or when the dialog is closed, the UserSettingsManager save method is called automatically. When the AddIn is loaded, it reads the settings file automatically.

User Interface

The Settings Example AddIn demonstrates two similar user interfaces implemented in different technologies:

A dialog using Windows Forms components
A dialog using Windows Presentation Foundation (XAML) components

Windows Forms User Interface

The UserInterface class provides methods specific to various widgets. Those include TextBox, ComboBox and CheckBox.

WPF Interface

The UserInterface class provides methods specific to various widgets. Those include TextBox, ComboBox and CheckBox.

The WPF user interface implements the MVVM idiom. It shows how to bind UI widgets with various data sources.

XML Settings File

The XML file used by Settings Example looks like this …

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<!-- Settings file concept developed by LA Solutions Ltd -->
<!-- Settings maintained by application SettingsExample -->
<!-- Created on 2020 May 20 -->
<settings>
  <data key="preferred-cell" value="Annotation-3" />
  <data key="preferred-text-style" value="HMC-BG_3.5" />
  <data key="preferred-level" value="Areas type 3" />
  <cell-options>
    <data key="3D-cells" value="True" />
    <data key="include-all-libraries" value="False" />
    <data key="include-parametric" value="False" />
    <data key="include-non-parametric" value="False" />
    <data key="include-shared" value="True" />
  </cell-options>
  <data key="your-text" value="This text was saved in a settings file!" />
</settings>

The root XML element is named settings. Data elements are children of settings. There is one section named cell-options, which is a child element of root. Section cell-options is the parent of several key-data pairs that store the state of CheckBox dialog items. Creating them as children of cell-options makes human interpretation easier.

When you press Save or close the dialog, UserSettingsManager is called. There is a number of methods in the UserInterface class of UserSettingsManager that transfer data between the dialog widgets and the settings DOM. After the DOM is updated it is persisted as an XML file having extension .settings.

When you press Load or open the dialog, UserSettingsManager is called. After the XML .settings file is opened it is read into a new DOM. There are methods in the UserInterface class of UserSettingsManager that transfer data between the settings DOM and the dialog widgets. Once in the DOM those methods are called to update the state of the Form widgets.

Design Library (DGNLib) Data

Incidentally, the Settings Manager example shows how to obtain cell library and DGNLib data. For example, the Cells, Text Styles and Level ComboBoxes display information obtained from DGNLibs.

Download the Settings Manager Example Project

The above code is available in this Visual Studio solution. Unpack the ZIP archive and copy the source code to a suitable location for Visual Studio.

The solution contains two Visual Studio projects: UserSettingsManager and the Settings Example. When you build the solution two DLLs are created, hopefully in ..\MicroStation\mdlapps. You may need to edit the Visual Studio project settings to set the correct location on your computer.

Questions

Post questions about MicroStation programming to the MicroStation Programming Forum.