NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

ConfigManager Class

The Configuration System is designed to give system runtimes, administrative tools, applications and other consumers of configuration information easy and efficient access to configuration information, regardless of the details of the storage format and location of the configuration information.

Object
   ConfigManager

[Visual Basic]
Public Class ConfigManager
[C#]
public class ConfigManager
[C++]
public __gc class ConfigManager
[JScript]
public class ConfigManager

Remarks

Reading Configuration Information: Refer to the documentation on the Get methods for details and examples.

Writing Configuration Information: Refer to the documentation on the Put methods for details and examples.

Defining your own schema:

By simply defining schema information for their application's configuration information, application developers obtain a large number of benefits:

In the PDC release, some of the core system components already use the configuration system to retrieve their configuration information at runtime (assembly binding resolution, AppDomain configuration). Other system components define their configuration information in such a way that it can be accessed through the configuration system (most ASP+ configuration), while others are currently only configurable by direct file manipulation or through specific APIs (code access securitypolicy).

The details on the configuration information of system components can be found in the respective documentation.

Application developers can store their application's configuration information using the same Configuration System and can access their configuration information through the ConfigManager. In order to access your own configuration information through the ConfigManager, you need to define schema for your configuration information.

The ConfigManager introduces several key concepts:

Configuration Files

While the configuration system is designed to be storage independent, and any applications or administrative tools written against configuration system APIs can be easily moved to a different backing store in the future, it is highly recommended to store configuration information in XML text files.

Using XML text files has the following advantages:

Most system configuration is stored in user-editable XML text files.

Configuration File Format

The XML format for configuration files is optimized for human readability: Configurable properties are expressed as XML attributes and related properties are grouped under XML elements, to render a compact, yet legible representation.Configurable properties should have a well-defined XML schema that can be used by XML editors and other XML-aware applications to perform validation or provide syntactic hints to the user. The XML schema also makes all configurable properties discoverable to generic consumers, like some administrative tools and development tools.

Example 1: Singleton item- AppDomain configuration

An example of a singleton configuration entry is the AppDomain configuration: AppDomain settings can be specified at most once in each application configuration file:

<?xml version ="1.0"?>
<configuration xmlns="x-schema:catalog.xms"> 

  <AppDomain 
      PrivatePath=".\bin;.\blaa" 
      SharedPath="c:\common\bin;c:\suite\utils" 
      ShadowCopy="True"/> 

</configuration>

The first line ("<?xml ...>") declares that this file is an XML document. It is optional, but should be specified to leverage XML editingtools.

The second line ("<configuration ...>") defines the root element of the XML document and declares the XML schema to be used to validate the content of the root element. The "xmlns" attribute on the root <configuration> element is optional, but in order to fully leverage XML editing tools (ie. Visual Studio's XML editor with autocomplete etc.) it is highly recommended to include the "xmlns" attribute. The root element in NGWS RUNTIME configuration files must have the name "configuration". XML is casesensitive.

The subsequent lines (<AppDomain.../>) carry actual configuration information, in this example the settings for the Application Domain. Individual configuration properties are expressed as XML attributes ("ShadowCopy" and "PrivatePath"). An XML element ("AppDomain>") groups these properties into logicalunits.

The last line ("/configuration>") closes the root element and thus the XMLdocument.

Example 2: Collection of items- Assembly Binding Policy

<?xml version ="1.0"?>
<configuration xmlns="x-schema:catalog.xms"> 

    <BindingPolicy>
        <BindingRedir Name="MyDll" Originator="xxxx" Version="1.0.0.0" VersionNew="3.0.0.0"/>
    </BindingPolicy>

</configuration>

The Assembly Binding Policy- used here again merely as an example of configuration information- is typically specified in an application configuration file. There can be one for every assembly that is to be loaded into an application. A binding redirection has several properties ("Name", "Version" etc.). In the configuration file, each binding redirection is represented by an XML element ("BindingRedir"), while each of its properties is an attribute of this element. All binding redirection elements are grouped together by a containing element ("<BindingPolicy>"), to ensure that all binding policy is stored in a single location in the file.

Note   Refer to the Runtime Configuration documentation for more information on code base hints.

Example 3: Nested Collections- Window/Toolbarpositions

Often, configuration information is more complex and requires one or more sub-items for each configurationentry.

Take the example of a (fictitious) Windows application that needs to store information for each of its windows: the window position, the background color and the applicable toolbars and theirposition:

<?xml version ="1.0"?>
<configuration xmlns="x-schema:catalog.xms"> 

  <Windows> 

    <Window Name="MainWindow" PosX="0" PosY="0" Width="100" Height="100" Color="Green" >
        <Toolbar Name="Formatting" PosX="0" PosY="0" /> 
        <Toolbar Name="Standard" PosX="0" PosY="40" />
    </Window> 

    <Window Name="StockTicker" PosX="0" PosY="101" Width="100" Height="20" Color="Red">
        <Toolbar Name="BuySell" PosX="0" PosY="0" /> 
    </Window> 

  </Windows> 

</configuration>

This example represents the definition of two "Windows" (a collection of "Window" items). Each Window in turn has one or more "Toolbar" items. The simple properties of a "Window" are expressed as XML attributes ("Name", "PosX" etc.). The "Toolbars" that the used chose for each Window are expressed as "Toolbar" sub-elements of the "Window" element, which in turn have attributes. The last line ("/configuration>") closes the root element and thus the XML document.

Example 4: Directives

In some cases, configuration information needs to be accumulated across a hierarchy of configuration files. Directives can be used to control the accumulation (or merge) process across the hierarchy:

<?xml version ="1.0"?>
<configuration xmlns="x-schema:catalog.xms">
  <assemblies>
    <add assembly="System.Data"/>
    <add assembly="System.Web.Services"/>
    <remove assembly="System.Xml.Serialization"/>
    <add assembly="System"/>
    <add assembly="System.Text.RegularExpressions"/>
    <add assembly="System.Drawing"/>
    <add assembly="*"/>
   </assemblies>
</configuration>

In this example (from an ASP+ configuration file), the element name of each of the items in the <assemblies> list controls if the item is to be added to or removed from the list during merge of configuration files. Each item can carry one or more additional attributes, just like any configuration item. The only difference to regular configuration is that the element name is replaced with the directive.

For more information on configuration file hierarchies refer to the documentation of Interceptors.IConfigTransformer.

Tip   Configuration information is automatically exposed through Microsoft's WMI infrastructure:

Requirements

Namespace: System.Configuration

Assembly: System.Configuration.dll

See Also

ConfigManager Members | System.Configuration Namespace | Interceptors.IConfigTransformer