Configuration Application Block

Configuration Application Block

Enterprise Library for .NET Framework 1.1

patterns & practices Developer Center

Microsoft Corporation

June 2005

Summary

This page provides an overview of the Enterprise Library Configuration Application Block. This is reusable and extensible source code-based guidance that simplifies development of common configuration functionality in .NET-based applications.

* Important Note: The January 2005 release of Enterprise Library is no longer available to download, due to important issues discovered after the release. Customers building new applications should move to the June 2005 release. Customers who have already adopted the January release must apply the patches available on Enterprise Library Community site. Please direct any questions to the community site or to devfdbck@microsoft.com

Contents

Introduction to the Configuration Application Block
Design of the Configuration Application Block
Test Drive
Feedback and Support
June 2005 Release Updates
Roadmap
Authors and Contributors
Related Titles

Introduction to the Configuration Application Block

Almost every application requires some form of configuration information. This information can be as simple as a database connection string or as complex as multipart and hierarchical user preference information. How and where to store an application's configuration data are questions you often face as a developer. Typical solutions include the following:

• Using configuration files such as XML files or Windows .ini files
• Using the Windows registry
• Using databases such as Microsoft SQL Server

Each of these alternatives has its strengths and weaknesses; there is no solution that is best in every situation. In a single application, you may have to adopt more than one approach to accommodate the different types of configuration data that your application needs. For example, if your application runs in different environments, you may need to support multiple configuration storage solutions. Other important factors to consider include ensuring the security and integrity of your application's configuration data and minimizing the storage solution's impact on the application's performance.

The Enterprise Library Configuration Application Block addresses these issues and provides a solution that you can use across all of your applications to manage configuration data. Specifically, the Configuration Application Block provides a flexible data model, a simple method for retrieving configuration data, and extensibility.

The Configuration Application Block decouples the ability to read and write configuration data from the specifics of the underlying data store. It does this by using storage providers and transformers to transfer data between the application and the physical store. Storage providers are objects that can read or write to a particular physical store, such as an XML file or a SQL database. Transformers translate the configuration information between the form the application expects (for example a set of objects) and the form the storage provider requires (for example an XML document). The application block is packaged with an XML file storage provider and an XML serializer transformer.

You define the storage provider and transformer in a file that contains configuration metadata. Typically, this file is either the Machine.config file, the App.config file, or the Web.config file. The metadata includes information such as the name of the configuration section, the storage location, and the type names of the objects to be used when reading or writing configuration settings. This means that you can change from one type of store to another by changing the information in the file. There is no need to rewrite your application.

Similarly, you can change the attributes of your store, such as its location, by changing the same file. Again, there is no need to modify your application code. Deciding where to store configuration data can be done during deployment and operation.

Common Scenarios

The Configuration Application Block provides a simple interface for reading and writing application configuration data. Retrieving configuration data requires only a single line of code. The following example retrieves a database connection string from the configuration file.

 [C#]
string conString = (string)ConfigurationManager.GetConfiguration("connectionstring");

[Visual Basic]
Dim conString As String = ConfigurationManager.GetConfiguration("connectionstring")
  

You can extend the Configuration Application Block by creating custom storage providers that allow you to use other data stores, such as the Windows registry or a SQL database. You add these custom providers to the Configuration Application Block by changing the configuration metadata file. You do not need to modify or rebuild the Configuration Application Block to use different stores. You can also add custom transformers to translate the configuration data for the application and for the store.

Audience Requirements

This application block is intended for software architects and software developers. To benefit fully from this guidance, you should have an understanding of the following technologies:

• Microsoft Visual C# development tool or Microsoft Visual Basic development system
• .NET Framework

Highlights of the Enterprise Library Configuration Application Block

The Enterprise Library Configuration Application Block uses the Enterprise Library Configuration Console to manage configuration settings. It also lets you add your own storage providers and transformers.

Migrating from the Configuration Management Application Block

There are significant differences between the Enterprise Library Configuration Application Block and the Configuration Management Application Block:

• This version of the application block includes support for storing configuration data in XML files. If you have used other types of data stores, such as the Windows registry or a SQL database, you can either create a custom storage provider and transformer, or you can convert your data to XML.
• There is no longer support for using name/value pairs to represent configuration data or for hash table serialization. To read configuration data into your application or to write it to a configuration file, you declare a class that will contain the data. This class should be able to use the output of the transformer.

System Requirements

To develop application blocks using the Configuration Application Block, you need the following:

• Microsoft Windows 2000, Windows XP Professional, or Windows Server 2003 operating system
• Microsoft .NET Framework 1.1
• Microsoft Visual Studio .NET 2003

Configuration Application Block Dependencies

The Configuration Application Block depends on code included in the Enterprise Library, including common library functionality, such as instrumentation, which provides various functions for exposing events and data used for system management.

In addition, the application block uses XML files to store configuration information. The recommended way to modify this information is to use the Enterprise Library Configuration Console.

Design of the Configuration Application Block

The Configuration Application Block was designed to achieve the following goals:

• To provide a simple interface for both reading and writing configuration data
• To insulate applications from the physical storage location of the configuration data
• To provide an extensible model that allows for custom storage locations and the run-time representation of configuration settings

Design Highlights

Figure 1 shows the relationships between the classes and objects that comprise the Configuration Application Block. The figure assumes that you are using the XML file storage provider and transformer that are included with the application block. The XML file storage provider stores configuration data in a file. (Other providers use other forms of storage such as the Windows registry.) The XmlFileStorageProvider object points to a file that contains the configuration settings for a particular configuration section. The ConfigurationBuilder object points to a file that contains the configuration metadata for a particular configuration section. Typically, the file that contains the configuration metadata is named App.config for Windows-based applications or Web.config for Web-based applications.

Figure 1. Design of the Configuration Application Block

The Configuration Application Block separates configuration metadata from the actual configuration settings. The application block places the metadata in its own file separate from the location where the configuration settings are stored. Configuration settings are grouped together and referred to as a configuration section. Each Enterprise Library application block that your application uses has its own configuration section that is stored in its own file. The Configuration Application Block accesses the data in a configuration by using the configuration metadata.

The metadata points to the configuration storage location and contains information such as the type of transformer and storage provider that the Configuration Application Block needs to read and to write the configuration data. The configuration metadata file is divided into sections. Each section contains the information that is required to read and write a particular group of configuration settings from and to a configured storage location.

The ConfigurationManager class provides a static facade to read and write configuration settings for a specified configuration section in a defined storage location. The ConfigurationManager object reads configuration metadata from the application domain configuration file and uses that information to read and write the configuration section information.

The static methods of the ConfigurationManager class use an instance of a ConfigurationBuilder object. The ConfigurationBuilder creates the file storage provider and the transformer objects. These objects manage the configuration data and metadata.

The IStorageProviderReader interface defines the interface that is used to read configuration information from a storage location. The IStorageProviderWriter interface implements the IStorageProviderReader interface and also defines the interface that is used to write configuration information. The Configuration Application Block includes one provider that supports this interface, XmlFileStorageProvider, which reads and writes configuration data to an XML file.

The ITransformer interface transforms configuration settings objects between the application and the storage provider. The Configuration Application Block includes one provider, the XmlSerializerTransformer class, which implements this interface. The XmlSerializerTransformer class translates between application-defined run-time objects and XmlNode objects. Applications are not required to configure a transformer. If there is no transformer, configuration settings objects are returned to the application in the same form as provided by the storage provider.

The settings for each configuration section are cached in a hash table. When the client requests configuration data, the ConfigurationBuilder object looks for the data in the cache. If the configuration data is found in the cache, the ConfigurationBuilder object does not access the configuration data that is in storage. The ConfigurationBuilder object clears the cache if the file storage provider detects that configuration data has changed in storage. The ConfigurationManager object allows applications to clear the cache, either entirely or for only a given section name. If the cache is cleared, the next read operation accesses the configuration settings from the storage location.

In summary, the Configuration Application Block is designed so that you can store configuration data in your application in whatever way best suits the application's requirements. You are not constrained by the storage method. The IStorageProviderReader and IStorageProviderWriter interfaces and, optionally, the ITransformer interface, decouple the in-memory representation from the representation that is used in the physical store.

Test Drive

The Configuration Application Block has been developed as a result of analyzing common enterprise development challenges and successful solutions to these challenges. However, because each application is unique, you will not find this application block suitable for every application. To evaluate this application block and determine its applicability to your projects, Microsoft suggests you dedicate at least half of a day to explore the application block. The following is a suggested evaluation approach:

1. Download Enterprise Library.
2. Install Enterprise Library and compile all application blocks and tools.
3. Read the "Introduction" section of the documentation.
4. Compile and run the QuickStart samples, and read through the related "QuickStart Walkthroughs" and "Key Scenarios" sections of the documentation.
5. If the application block looks like a good fit for your application, try implementing a simple use case in your application or in a throw-away prototype application using the application block.

Feedback and Support

Questions? Comments? Suggestions? To provide feedback about this application block, or to get help with any problems, please visit the Enterprise Library Community site. The community site is the preferred feedback and support channel because it allows you to share your ideas, questions, and solutions with the entire community. Alternatively, you can send e-mail directly to the Microsoft patterns & practices team at devfdbck@microsoft.com, although we are unable to respond to every message.

Enterprise Library is a guidance offering, designed to be reused, customized, and extended. It is not a Microsoft product. Code-based guidance is shipped "as is" and without warranties. Customers can obtain support through Microsoft Support Services for a fee, but the code is considered user-written by Microsoft support staff. For more information about our support policy, see the Enterprise Library home page

June 2005 Release Updates

The June 2005 release of Enterprise Library is a minor update of the original version released in January 2005. Please see About the June 2005 Release for more information on the updates to the application blocks for the June 2005 release.

Roadmap

An updated release of the Configuration Application Block is planned for the next release of Enterprise Library. This release will target the .NET Framework 2.0 and Visual Studio 2005 and will include additional improvements based on customer feedback.

Authors and Contributors

The Enterprise Library Configuration Application Block was produced by the following people:

• Program Managers: William Loeffler (Microsoft Corporation), Linh Nguyen (Avanade Inc)
• Product Manager: Tom Hollander (Microsoft Corporation)
• Architects: Edward Jezierski (Microsoft Corporation), Kyle Huntley (Avanade Inc)
• Development: Scott Densmore, Peter Provost (Microsoft Corporation), Brian Button (Murphy and Associates), Paul Currit (Avanade Inc.), Fernando Simonazzi (Clarius Consulting)
• Test: Mohammad Al-Sabt, Carlos Farre (Microsoft Corporation), Mani Krishnaswami, Gokulaprakash Thilagar, Rohit Sharma, Prashant Bansode, Jeevarani Radhakrishnan, Dhananjaya Rao (Infosys Technologies Ltd), Pavan Kumar Sura (Volt)
• Documentation and Samples: RoAnn Corbisier, Nelly Delgado (Microsoft Corporation), Tim Osborn (Ascentium Corporation), Roberta Leibovitz (Modeled Computation LLC), Paul Slater (Wadeware LLC), Tina Burden McGrayne (Linda Werner & Associates Inc)

Many thanks to the following advisors who provided invaluable assistance:

• Rudy Araujo, Yen-Ming Chen, Mark Curphey and David Raphael of Foundstone Inc.
• Benoit Morneau and Shoichi Takasaki of Bowne Global Solutions.

Related Titles

• Enterprise Library

Start | Previous | Next