Configuration Management Application Block for .NET
Related Links
Application Architecture for .NET: Designing Applications and Services
By Edward Jezierski (Microsoft Corporation), Michael Stuart (Microsoft Corporation), Allen Jones (Content Master Ltd), and Diego Gonzales (Lagash Systems)
June 2003
Summary: The use of standard .NET configuration files (both computer- and application-based) provides read-only access to application configuration data stored in XML files — an approach that is too restrictive for many applications. The Configuration Management Application Block provides a simple and efficient solution to overcome these limitations, allowing you to read and write application configuration data securely, regardless of its in-memory structure or the physical location and type of data store. (10 printed pages)
Contents
· What Does the Configuration Management Application Block Include?
· Downloading and Installing the Configuration Management Application Block
· Using the Configuration Management Application Block
Introduction
Almost every application requires some form of configuration information, from the very simple database connection string, to complex multi-part and hierarchical user preference information. How and where to store an application's configuration data is a problem that almost all developers face at one time or another. Common solutions include using:
· Configuration files such as XML or Windows .ini files
· The Windows registry
· Databases such as Microsoft® SQL Server™
Each of these alternatives has its strengths and weaknesses; there is no single solution that is best in every situation. Even within a single application, you might have to adopt more than one approach in order to cater to the different types of configuration data your application needs to store. The need for your application to run in different environments might also force you to support multiple configuration storage solutions.
Other important factors to consider include the ability to write — not only read — configuration data, the security and integrity of your application's configuration data, and the impact on performance that your configuration data solution creates. Having all of these issues to contend with, you can easily spend too much time working on mechanisms to manage your configuration data instead of working on what's really important: the functionality and features of your application.
The Configuration Management Application Block addresses these issues and provides a simple yet flexible solution that you can use across all your applications to manage configuration data. Specifically, the Configuration Management Application Block provides benefits in the following key areas:
· Simplicity – a simple set of static (C#) / shared (Visual Basic .NET) methods allows you to read and write application configuration data without the need to instantiate objects or perform complex data conversions in your code
· Flexible data model – an extensible data handling mechanism allows you to use any in-memory data structure to represent your configuration data
· Storage location independence – built-in support for the most common data stores and an extensible data storage mechanism give you complete freedom over where you store your application configuration data
· Data security and integrity – data signing and encryption can be used with any configuration data — regardless of its structure or where it is stored — to improve security and integrity
· Performance – optional memory-based caching improves the speed of access to frequently read configuration data
· Extensibility – a handful of simple, well-defined interfaces allow you to extend most aspects of the Configuration Management Application Block
Note This Application Block for .NET has been designed based on reviews of successful .NET applications. It is provided as source code that you can use "as-is" or customized for your application. It is not an indication of future direction for application configuration management within the Microsoft .NET Framework. Future releases of the .NET Framework may address application configuration management using a different model.
The remainder of this overview is divided into the following sections:
What Does the Configuration Management Application Block Include?
Downloading and Installing the Configuration Management Application Block
Using the Configuration Management Application Block
What Does the Configuration Management Application Block Include?
The source code for the Configuration Management Application Block is provided, together with QuickStart sample applications, which you can use to test the block's functionality. The Configuration Management Application Block also includes comprehensive documentation to help you work with and learn about the code provided.
The Visual Studio® .NET Projects
Microsoft Visual Basic® .NET and Microsoft Visual C#® .NET source code is supplied for the Configuration Management Application Block, along with QuickStart Sample applications (also in both languages) that you can use to test common scenarios. This helps increase your understanding of how the Configuration Management Application Block works. You are also free to customize the source code to suit your specific requirements.
Both the Visual Basic .NET and C# version of the Microsoft.ApplicationBlocks.ConfigurationManagement projects can be compiled to produce two assemblies named Microsoft.ApplicationBlocks.ConfigurationManagement.dll and Microsoft.ApplicationBlocks.ConfigurationManagement.Interfaces.dll. These assemblies contain all the classes and interfaces that comprise the block.
The download also contains the following QuickStart projects:
· Microsoft.ApplicationBlocks.ConfigurationManagement.Quickstarts.Read
This QuickStart shows how to read data from a variety of data stores using the Configuration Management Application Block.
· Microsoft.ApplicationBlocks.ConfigurationManagement.Quickstarts.Write
This QuickStart shows how to write data to a variety of data stores using the Configuration Management Application Block.
· Microsoft.ApplicationBlocks.ConfigurationManagement.Quickstarts.Hashtable
This QuickStart demonstrates the special support built into the Configuration Management Application Block for application configuration data stored in Hashtable objects.
The Documentation
Comprehensive documentation is provided in the form of a compiled Help file. This includes the following main sections:
· Design of the Configuration Management Application Block – This section provides details on the design and implementation of the Configuration Management Application Block, including all key components and interfaces.
· Developing Applications with the Configuration Management Application Block – This section contains information that helps you develop applications that use the Configuration Management Application Block. It shows how to use the standard features of the block and describes how to customize and extend the block to meet your specific needs.
· Deployment and Operations – This section includes installation information; it describes deployment options and use of the global assembly cache.
· Reference – This is a comprehensive API reference section that details the classes and interfaces comprising the Configuration Management Application Block.
System Requirements
To run the Configuration Management Application Block, you need the following:
· Microsoft Windows® 2000, Windows XP Professional, or Microsoft Windows Server 2003
· Microsoft .NET Framework version 1.1
· Visual Studio .NET 2003 (recommended but not required)
Downloading and Installing the Configuration Management Application Block
A Windows Installer file containing the Configuration Management Application Block projects, source code, and comprehensive documentation is available.
The install process creates a Microsoft Application Blocks for .NET submenu on your Programs menu. On the Microsoft Application Blocks for .NET submenu, there is a Configuration Management submenu that includes options to open the documentation, to open the Configuration Management Application Block Visual Studio .NET solutions, and to install demonstration applications (Quickstart applications).
After you install the Configuration Management Application Block, you should install the QuickStart applications using the Install Quickstarts option on the Configuration Management submenu. This configures a local instance of SQL Server databases for use by the Quickstart applications. To learn more about this install script, see the Readme.txt file in the application installation folder.
Click here to open the MS.com download page
Using the Configuration Management Application Block
The purpose of the Configuration Management Application Block is to provide simple and efficient read and write access to application configuration data. To meet this objective, the central element of the block — a class named ConfigurationManager —implements a simple public interface consisting of a set of overloaded static (C#) / shared (Visual Basic .NET) methods named Read and Write, and an indexer accessible through a property named Items. These mechanisms support a variety of usage models, impose different constraints, and accept different arguments; however, each performs fundamentally the same operation: to read or write a configuration section.
A configuration section is the basic unit of data storage and retrieval in the Configuration Management Application Block. A configuration section represents a block of configuration data — a group of related configuration settings — that you read or write in a single operation. Each configuration section is declared in your application's .NET configuration file and is identified by a name. The configuration section declaration specifies the following elements, which the Configuration Management Application Block uses when processing read and write requests for the configuration section:
· Configuration Section Handler – This transforms the configuration section back and forth between its correct in-memory structure and its standardized internal form as an XmlNode. There are two types of Configuration Section Handlers: read-only and a read/write. A read-only Configuration Section Handler implements the IConfigurationSectionHandler interface and can transform an XmlNode into its correct in-memory structure. This is the same model used by the ConfigurationSettings class in the .NET Framework class library. A read/write Configuration Section Handler implements the IConfigurationSectionHandlerWriter interface (which extends IConfigurationSectionHandler) and can transform data in both directions.
· Configuration Storage Provider – This reads and writes the configuration section to and from a particular type of data store; for example, Microsoft SQL Server or XML files. There are two types of Configuration Storage Providers: read-only and read/write. A read-only Configuration Storage Provider implements the IConfigurationStorageReader interface and can only read a configuration section from the underlying data store. This provides a higher degree of security for highly accessible and Internet-facing server applications. A read/write Configuration Storage Provider implements the IConfigurationStorageWriter interface (which extends IConfigurationStorageReader) and can both read and write configuration sections.
· Data Protection Provider – This provides encryption and message authentication code services to improve the security and integrity of stored configuration section data.
· Caching configuration – This determines whether caching is enabled for the configuration section. If enabled, whenever the ConfigurationManager needs to read the configuration section, it first tries the cache to see if the configuration section is already present; if it is, it fulfills the read request from the cache. You can configure how long a cached configuration section remains valid.
Figure 1 shows the architecture of the Configuration Management Application Block and illustrates how each of these elements relate to each other.
Figure 1
The Configuration Management Application Block
Reading and Writing Application Configuration Data
This section describes how the ConfigurationManager class implements support for the reading and writing of application configuration data.
Reading a Named Configuration Section
To retrieve a named configuration section, the ConfigurationManager provides a Read method overload in which you must specify the name of the required configuration section. The configuration section is returned as an object reference that you must cast to the appropriate type. The following example shows the code necessary to retrieve a Hashtable-based configuration section named AppConfig.
[Visual Basic]
Dim configData As Hashtable
' Read the configuration section named AppConfig
configData = CType(ConfigurationManager.Read("AppConfig"), Hashtable)
[C#]
Hashtable configData;
// Read the configuration section named AppConfig
configData = (Hashtable)ConfigurationManager.Read("AppConfig");
Writing a Named Configuration Section
To store a named configuration section, the ConfigurationManager provides a Write method overload in which you must specify the name of the configuration section being stored and the object containing the configuration section data. The following example shows the code necessary to store a Hashtable-based configuration section named AppConfig.
[Visual Basic]
Dim configData As Hashtable
' Write the configuration section named AppConfig
ConfigurationManager.Write("AppConfig",configData)
[C#]
Hashtable configData;
// Write the configuration section named AppConfig
ConfigurationManager.Write("AppConfig",configData);
Reading the Default Configuration Section
Many applications will use only one configuration section or have a primary configuration section that they use most often. This is considered the default configuration section. The Configuration Management Application Block includes additional functionality to simplify access to this configuration section.
To retrieve the default configuration section, the ConfigurationManager provides a Read method overload in which you do not need to specify the name of the configuration section. This method always returns a Hashtable, because the default configuration section must always be Hashtable-based. The following example shows the code necessary to retrieve the default configuration section.
[Visual Basic]
Dim configData As Hashtable
' Read the default configuration section (must be Hashtable-based)
configData = CType(ConfigurationManager.Read(), Hashtable)
[C#]
Hashtable configData;
// Read the default configuration section (must be Hashtable-based)
configData = (Hashtable)ConfigurationManager.Read();
Writing the Default Configuration Section
To store the default configuration section, the ConfigurationManager provides a Write method overload in which you must provide a reference to the Hashtable containing the configuration section data, but you do not need to specify the name of the configuration section. The following example shows the code necessary to store the default configuration section.
[Visual Basic]
Dim configData As Hashtable
' Write the default configuration section (must be Hashtable-based)
ConfigurationManager.Write(configData)
[C#]
Hashtable configData;
// Write the default configuration section (must be Hashtable-based)
ConfigurationManager.Write(configData);
Reading and Writing Default Configuration Section Data Elements
To simplify access to the default configuration section, the ConfigurationManager provides indexer-style access to individual data items through the Items property. The following example shows the code necessary to read and write individual data items to the default configuration section.
[Visual Basic]
' Write a data item to the default configuration section
ConfigurationManager.Items("Size") = "large"
' Read a data item from the default configuration section
Dim size As String = CStr(ConfigurationManager.Items("Size"))
[C#]
// Write a data item to the default configuration section
ConfigurationManager.Items["Size"] = "large";
// Read a data item from the default configuration section
string size = (string)ConfigurationManager.Items["Size"];
Frequently Asked Questions
What types of applications can I use the Configuration Management Application Block with?
Any application that needs to read and write application configuration data will benefit from the use of the Configuration Management Application Block. Instead of writing your own code to access configuration data, the Configuration Management Application Block is a flexible, proven, and well-tested solution that can provide access to any type of configuration data in any data store. In addition, the Configuration Management Application Block uses caching to improve performance when reading data, and it improves data integrity and security through the use of encryption and data signing.
Where can I store my application configuration data?
The Configuration Management Application Block provides the functionality to access application configuration data stored in Microsoft SQL Server, the Windows registry, and XML files. In addition, the extensible architecture of the Configuration Management Application Block means that you can easily add support for any type of data store with minimal coding and with no changes to the core code of the Configuration Management Application Block.
Why should I use the Configuration Management Application Block to store my application configuration data instead of using Microsoft SQL Server or an XML file directly?
The Configuration Management Application Block abstracts your application's configuration data from the physical characteristics of the underlying data store. This means that you can store any type of data in any data store. You can also change the data store where your application stores its configuration information with a simple change to your .NET configuration file; there is no need to modify and recompile your code. This means that the choice of data store is no longer a design time decision, but one of implementation and deployment. In addition, the caching and data security features of the Configuration Management Application Block can be enabled on any data store with no additional development.
What types of data can I store?
The Configuration Management Application Block provides support for storing application configuration data contained in Hashtable objects as well as any data type supported by the XmlSerializer class. In addition, the extensible architecture of the Configuration Management Application Block means that you can easily add support for any data structure with minimal development effort.
How does the Configuration Management Application Block improve the security and integrity of application configuration data?
Regardless of the type of data or the store in which the data is held, you can configure the Configuration Management Application Block to use the data signing and encryption services provided by a Data Protection Provider. The Configuration Management Application Block provides two Data Protection Provider implementations and the extensible architecture of the Configuration Management Application Block means that you can easily seamlessly integrate your own Data Protection Provider implementation.
Can I use XCOPY deployment to deploy the Configuration Management Application Block assembly?
Yes. After they are compiled, the Configuration Management Application Block assemblies can be XCOPY deployed.
Are there any other application blocks?
Yes. The Configuration Management Application Block is one of several Application Blocks that are being released. These Application Blocks solve the common problems that developers face from one project to the next. They can be plugged into .NET applications quickly and easily.
Feedback and Support
Questions? Comments? Suggestions? For feedback on the Configuration Management Application Block, please send an e-mail message to devfdbck@microsoft.com.
The Application Blocks for .NET are designed to jumpstart development of .NET distributed applications. The sample code and documentation is provided "as-is." Support is available through Microsoft Product Support for a fee.
The GotDotNet community site provides a place for .NET developers to share code and ideas. A GotDotNet workspace for the Configuration Management Application Block has been created at http://www.gotdotnet.com/community/workspaces/workspace.aspx?id=01875f69-9358-437b-a8ae-fa4bf2e3080f. Please share your Configuration Management Application Block questions, suggestions, and customizations with the community in this workspace.
A newsgroup has also been created to assist you with the Application Blocks for .NET. Use this newsgroup to consult with your counterparts, peers, and Microsoft Support Professionals in an online, open forum. Everyone else benefits from your questions and comments, and our development team is monitoring the newsgroup on a daily basis: Newsgroup: Web-Based Reader http://msdn.microsoft.com/newsgroups/loadframes.asp?icp=msdn&slcid=us&newsgroup=microsoft.public.dotnet.distributed_apps
Newsgroup: NNTP Reader news://msnews.microsoft.com/Microsoft.public.dotnet.distributed_apps
Do you want to learn and harness the power of .NET? Work side by side with technology experts at the Microsoft Technology Centers to learn development best practices. For more information, please visit http://www.microsoft.com/business/services/mtc.asp.
Collaborators
Many thanks to the following contributors and reviewers:
Alfredo Ramirez | Kostas Williams |
Anders Heick | Kunal Jain (Infosys Technologies Ltd) |
Angela Crocker | Lynne C. Lafleur |
Areeb Afsah | Mark (Inkmarc) |
Arvindra Sehmi | Martin Born |
Avi Ben-Menahem | Matt Morris |
Bijan Javidi | Michael Dereszynski |
Brenton Webster | Michael Freifeld |
Brian Hodgdon | Michael Kogotkov |
Brian Loomis | Michael Monte |
Chaitanya Bijwe (Infosys Technologies Ltd) | Michael Thomassy |
Chris Cichocki | Michel Baladi |
Chris Craft | Mike Benson |
Chris Henry | Mohamed Ayadi |
Chris Schoon | Nathan Hanks |
Chris Wafer | Neil Peterson |
Clementino Mendonca | Niroo Thaya-Paran |
Craig Huber | Omri Toppol |
Dan Green | Pablo Degrande (Lagash Systems) |
David Broussard | Patrick Long (Charteris) |
David Trowbridge | Paul Hoeffer |
David Weller | Peter Freeborn |
Deborah Kurata | Peter Ho |
Dimitris Georgakopoulos | Peter Russo |
Dwight Smith | Peter Tsang |
Ed Draper | Philip Ochu |
Eric Thomas | Philip Reilly |
Eugenio Pace | Philip Teale |
Evald Markinzon | Prashant Bansode (Infosys Technologies Ltd) |
Florent Mathery | Rick Harris |
Francisco Salguero | Rick Kopitzke |
Franco A. Ceruti | Rob Howard |
Gareth Jones | Robert Moore |
George Mondragon | Rohit Sharma (Infosys Technologies Ltd) |
Geralyn Miller | Ronald Kegge |
Greg Bybee | Ross Cockburn |
Gregg Hansen | Sameer Aras (Infosys Technologies Ltd) |
Gregory Kiefer | Scott Bellware |
Hanu Kommalapati | Scott Densmore |
Hemang Naik (Infosys Technologies Ltd) | Shanku Niyogi |
Irving De La Cruz | Sharon Bjeletich |
J Sawyer, Jr. | Shawn Cole |
Jaidesh Sethi (Cohesion) | Shawn Farkas |
James Bolles | Srinath Vasireddy |
Jamie Cool | Srinivas Bontu |
Jasen Tenney | Stephen Fulcher |
Jasone Cerasia | Steve Busby |
Jay Lewis | Steven Huang |
Jay Skelly | Sunit Carpenter |
Jeff Littrell | Tim Mallalieu |
Joe Castro | Tim Pearson |
Joe Stegman | Tom Gagne |
John Larrison | Tom Kudla |
John Martin | Torben Pedersen |
John Miller | Varsha Patil (Infosys Technologies Ltd) |
John Opalko | Vidyuth Muthanna |
Kenny Jones | William Hertha |
Kevin S Roberts | William Leary |
Kliment Mamykin | Zhanbo Sun |
Thanks, also, to the content team: Edward Lafferty, Sameer Tarey (Infosys Technologies Ltd), Ashish Babbar (Infosys Technologies Ltd), Tina Burden (Entirenet), and Kathy Ferguson (Entirenet).