In all software projects, the need of Configuration Management is present in some extent. And since some of us are working on fixed price projects, all you can do to speed up the development process and increase software quality is important. As a consultants in Objectware, one of Norway’s leading consulting companies on .NET technologies. We are always discussing ways to increase software quality and precision of delivery, therefore a colleague of mine, asked me to write a Quick start article on CMAB.
Note: This document describes how to start using CMAB when developing in Visual Studio .NET 2003.
What is CMAB
The CMAB provides a simple jet flexible solution, that you can use across all of your applications to manage configuration data. Specifically, the CMAB provides benefits in the following key areas:
- Simplicity
- Flexible data model
- Storage location independence
- Data security and integrity
- Performance
- Extensibility
For download and more information about CMAB and other Application Blocks visit http://www.microsoft.com/resources/practices/code.mspx.
Example 1: How to use a hashtable and CMAB to store configuration data in app.config.
Create a new C# Windows Application project from the File, New, Project menu in Visual Studio. Then add a reference to the CMAB assemblies by right click on then project in the Solution Explorer and select Add reference. When the Add Reference dialog appears, click the Browse button, and navigate to the location where CMAB assemblies are stored. Select the Microsoft.ApplicationBlocks.ConfigurationManagement.dll. The next thing you have to do is to add the CMAB section handler to app.config. (If you project doesn’t contain the app.config, then add such a file.)
<?
xml version="1.0" encoding="utf-8" ?> <
configuration> <configSections> <section name="applicationConfigurationManagement" type="Microsoft.ApplicationBlocks.ConfigurationManagement.ConfigurationManagerSectionHandler, Microsoft.ApplicationBlocks.ConfigurationManagement, Version=1.0.0.0,Culture=neutral,PublicKeyToken=null"
/> </configSections></
configuration>
The CMAB section handler is responsible for parsing the CMAB configuration section. The next thing you have to do is to append the CMAB configuration section. Add the following lines below the </configSections> end tag.
<
applicationConfigurationManagement></
applicationConfigurationManagement>
The next thing you have to do is to add the section handler responsible for reading and writing your hashtable config data to and from the configuration file. Add the following lines below the CMAB section handler inside the <configSections> tag.
<
section name="HashedConfigData" type="Microsoft.ApplicationBlocks.ConfigurationManagement.XmlHashtableSectionHandler,
Microsoft.ApplicationBlocks.ConfigurationManagement,Version=1.0.0.0,Culture=neutral,
PublicKeyToken=null" />
You also have to add a configuration section where the hashed data are supposed to be. Add the following lines below the </configSections> end tag.
<
HashedConfigData></
HashedConfigData>
Now you have two section handler’s and to configuration section’s in you app.config file. The next step is to configure how the CMAB should manage your configuration data. Inside the <applicationConfigurationManagement> tag, you now have to define how the CMAB should Store, Cache and protect you data. Since you can several different types of config data and with individual settings, the first thing you have to do is to add a named configSection tag. Inside this tag add one configCache tag, one configProvider tag and one protectionProvider tag.
<
applicationConfigurationManagement> <configSection name="HashedConfigData"> <configCache enabled="true" refresh="1 * * * *" /> <configProvider assembly="Microsoft.ApplicationBlocks.ConfigurationManagement, Version=1.0.0.0,Culture=neutral,PublicKeyToken=null"
type="Microsoft.ApplicationBlocks.ConfigurationManagement.Storage.XmlFileStorage" refreshOnChange="false" signed="false" encrypted="false" /> <protectionProvider assembly="Microsoft.ApplicationBlocks.ConfigurationManagement, Version=1.0.0.0,Culture=neutral,PublicKeyToken=null"
type="Microsoft.ApplicationBlocks.ConfigurationManagement.
DataProtection.BCLDataProtection"
hashKeyRegistryPath="" hashKey="MyXuEd6f+go=" symmetricKey="VToaqZjp8C27V90oSmT/CF+afvRGClc9" initializationVector="ou95G2/WziI="/> </configSection></
applicationConfigurationManagement>
Now the worst part is over. You are now ready to start using CMAB to read and write Hashed configuration data. So now let us take a look at some C# code. The first thing you need is to append these to lines to the beginning of you cs file. Hopefully then don’t need more introduction.
using
System.Collections;using
Microsoft.ApplicationBlocks.ConfigurationManagement;
To read config data into you hashtable, do like this. Hashtable configData = (Hashtable)ConfigurationManager.Read();
The Configuration manager will now try to read de default configuration section as a hashtable. If you have more than one configuration section, you can define you default section by adding the defaultSection attribute to your <applicationConfigurationManagement> tag. Like this:
<applicationConfigurationManagement defaultSection="HashedConfigData">
To write config data back to you configuration file, is even more easy than reading from the file. Below is some code used append configuration data on a button click event. Read then code, it speaks for it self.
private
void btnAdd_Click(object sender, System.EventArgs e) { Hashtable configData = (Hashtable) ConfigurationManager.Read("HashedConfigData");
if (configData == null)
configData =
new Hashtable(); if (!configData.ContainsKey(tbxKey.Text))
configData.Add(tbxKey.Text, tbxValue.Text);
else
configData[tbxKey.Text] = tbxValue.Text;
ConfigurationManager.Write("HashedConfigData",configData);
}
If you need to encrypt you data, all you have to do is to change the encrypt attribute from “false” to “true” on your configProvider tag. For more information on how to encrypt your data, have a look at the CMAB documentation file provided by the download from Microsoft. If you have several configuration sections and need to read or write another then the default section, you simply specify the section name while using the Read and Write methods. Hashtable configData = (Hashtable) ConfigurationManager.Read("HashedConfigData");
ConfigurationManager.Write("HashedConfigData",configData);
Example 2: How to use the XmlSerializer Section Handler .
Using hashtable’s to store configuration data is ok for simple purposes, but when it comes to complex solutions, it is often better to define more complex structures to hold you configuration data. Something I often do, is to define a custom class to hold the configuration settings. This class may for example look like this:
public
class MyConfigSettings{
public MyConfigSettings() {} private string _color;
public string Color {
get { return this._color; }
set { this._color = value; }
}
private int _height;
public int Height {
get { return this._height; }
set { this._height = value; }
}
private int _width;
public int Width {
get { return this._width; }
set { this._width = value; }
}
}
An obvious advantage, with this way of storing configuration data is that you don’t have to use constants through you code. This is good design and removes a lot of potential error situations. One other advantage is that you can use typed configuration data.
To store this type of data in your app.config file, you have to add configuration settings to support this functionality. First you have to add the section handler. I user the XmlSerializerSectionHandler witch is supplied by the CMAB.
<
section name="MyConfigSettings" type="Microsoft.ApplicationBlocks.ConfigurationManagement.XmlSerializerSectionHandler,
Microsoft.ApplicationBlocks.ConfigurationManagement, Version=1.0.0.0,Culture=neutral, PublicKeyToken=null" />
Then I have to add the configuration section.
<
MyConfigSettings></
MyConfigSettings>
And the last thing I have to do in the app.config file is to add a new configSection to the <applicationConfigurationManagement> tag. I do this by adding the following code.
<
configSection name="MyConfigSettings"> <configProvider assembly="Microsoft.ApplicationBlocks.ConfigurationManagement,Version=1.0.0.0,Culture=neutral,PublicKeyToken=null"
type="Microsoft.ApplicationBlocks.ConfigurationManagement.Storage.XmlFileStorage"
signed="false" encrypted="true" /></configSection>
In this example I only added the configProvider, but if you need caching and encryption then you simply add the configCache tag and the protectionProvider tag as well.
Now let us have a look at some C# code:
private
void btnAddSection_Click(object sender, System.EventArgs e) { MyConfigSettings settings = (MyConfigSettings) ConfigurationManager.Read("MyConfigSettings");
if (settings == null) settings =
new MyConfigSettings();
settings.Color = tbxColor.Text;
settings.Width = Convert.ToInt32(tbxWidth.Text);
settings.Height = Convert.ToInt32(tbxHeight.Text);
ConfigurationManager.Write("MyConfigSettings", settings);
}
The code above, simply read the configuration section form the app.config file. If the section is empty, the Read method returns null. Then next lines of code updates the settings object with values from some textbox’s and then uses ConfigurationManager’s Write method to save the configuration data back to the app.config file.
About the examples
These quick start examples are both based upon the example code supplied by the Application Block itself. So if you need to have a closer look at the code, you know where to look for it. I hope these examples help you to start using the CMAB, it’s not rocket science. It’s easy.