Configuration Management Application Block for .NET

Configuration Management Application Block for .NET<?xml:namespace prefix = o ns = "urn:schemas-microsoft-com:office:office" />

<?xml:namespace prefix = v ns = "urn:schemas-microsoft-com:vml" />

Related Links

patterns and practices Index

.NET Architecture Center

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

·                     Introduction

·                     What Does the Configuration Management Application Block Include?

·                     Downloading and Installing the Configuration Management Application Block

·                     Using the Configuration Management Application Block

·                     Frequently Asked Questions

·                     Feedback and Support

·                     Collaborators

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

·       
4000
              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

Frequently Asked Questions

Feedback and Support

Collaborators

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.

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.

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.

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.

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.

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).