he first article in this series showed how to create custom configuration sections in your ASP.NET application configuration file, while the second article demonstrated using Windows Group Policy at both the machine and domain level to control configuration settings from a central location, to impose those settings on some or all the servers that run your Web applications. This article shows how you can apply those techniques using the Manageable Configuration Provider that is part of Microsoft’s Enterprise Library.

Manageable Configuration in Enterprise Library
Enterprise Library 3.0, from Microsoft’s patterns & practices group, includes a Manageable Configuration Source provider that implements a process very similar to the manual process you saw earlier in this article series.

The provider loads the application configuration data from a local Web.config or App.config file. For each value exposed in the configuration, the provider checks in the registry for the corresponding key to see whether Group Policy settings define a value for that setting. If there is a Group Policy value, the provider returns that value rather than the value in the configuration file.

The documentation for Enterprise Library contains step-by-step guides to setting up and using the Manageable Configuration Source provider. This article briefly explains that process within the context of a sample application, and lets you experiment to discover how the final configuration affects the behavior of the application.

The Manageable Configuration Sample Application
The sample application uses four Enterprise Library Application Blocks:

• The Data Access Application Block with two databases configured, one using the SqlClient provider and one using the OleDb provider
• The Logging Application Block to record data access exceptions in Windows Event Log
• The Caching Application Block with the standard Isolated Storage provider and a custom file-based caching provider
• The Cryptography Application Block with a Hash provider and a symmetric encryption provider

	?
Figure 1. The Sample Application: The sample application demonstrates how to use the Manageable Configuration Provider in Enterprise Library

Figure 1 shows the sample application. It is, in fact, based on an application used in a previous series of articles “Using Enterprise Library in ASP.NET“. You can read these to see exactly how the example uses Enterprise Library application blocks and a custom caching provider.

The application uses two databases defined within the Data Access Application Block configuration to fill two list boxes with the names of products from Microsoft’s “Northwind” sample database. By default, these blocks use the SqlClient and the OleDbClient providers, as indicated by the connection strings displayed in the text boxes below each list.

The page also contains a “Cache a Dataset to Disk” button that creates a DataSet using the default database defined for the Data Access Application Block, and then caches it using the default caching provider defined for the Caching Application Block (the Isolated Storage Cache provider). The “Load Dataset from Disk Cache” button retrieves the DataSet from the default cache and displays the rows in the GridView control on the page.

Finally, there are three buttons that use features of the Cryptography Application Block to create a hash of the text in the Textbox control above the buttons, encrypt the text, and decrypt it again.

Adding the Manageable Configuration Source
The first step in using the Manageable Configuration Source provider is to create the application you want to manage. Each time you add or remove application blocks, providers, and other Enterprise Library features within the application configuration, you change the requirements of the administrative template that the Manageable Configuration Source uses. Therefore, you should build, test, and debug your application before adding the manageability features.

After the application is complete, follow this procedure:

1. Open the Web.config file into one of the two configuration editors (the Configuration Console or the Visual Studio Configuration Editor). See the sidebar “Editing Enterprise Library 3.0 Configuration Files” for more information.
2. Right-click the application node (the node immediately below the “Enterprise Library Configuration” node), select “New…,” and then click Configuration Sources. Doing that adds a Configuration Sources node and a child System Configuration Source node to the configuration tree.
3. Right-click on the new Configuration Sources node, select “New…,” and then click Manageable Configuration Source.
4. Right-click on the System Configuration Source child node added in step two, and click “Remove” to remove it from the configuration.

	?
Figure 2. Sample Application Configuration: Here’s the configuration for the Enterprise Library Manageable Configuration example open in the Visual Studio Configuration Editor.

Figure 2 shows the final configuration of the sample application, including the Configuration Sources section containing the Manageable Configuration Source. The next step is to set the properties of the Manageable Configuration Source provider.

Configuring the Manageable Configuration Source
The Manageable Configuration Source has six properties, five of which you can set using the configuration tools. At a minimum, you must set the ApplicationName and File properties. The ApplicationName property defines the name of the root registry key (within the HKEY_LOCAL_MACHINESoftwarePolicies section) that the provider will read to find Group Policy configuration values. The default is “Application.”

The File property defines the full path to the configuration file (Web.config in this example) from which the provider will read local configuration values. You can also specify the name for the provider.

Two other properties, EnableGroupPolicies and EnableWmi, specify whether the provider will read Group Policy values and/or emit details of the configuration through WMI. By default, both are set to True, though you can disable them as required. For example, you can turn off property and event generation for WMI if you do not require this feature, or disable Group Policy while you test and experiment with your application configuration.

You must also set the SelectedSource property of the parent Configuration Sources node to specify the Manageable Configuration Source you are using. You can select this from the drop-down list in the SelectedSource property of the Configuration Sources node.

If you want to encrypt this section of the configuration file, select a value in the drop-down list for the ProtectionProvider property of the Configuration Sources node. Finally, if you intend to run your application in partial trust mode, set the RequirePermission property of this node to False.

Now save your configuration file and test your application to ensure that it reads the configuration information correctly, and that there are no errors. You may find that you need to add references to other application block assemblies (or copy the assemblies to your bin folder) for blocks and features that the manageable provider uses. Visual Studio generates an exception that indicates any missing assemblies when you run the application.

Creating the Group Policy Administrative Template
With the application complete, and the Manageable Configuration Source added to the configuration, you can create the Administrative Template that defines the Group Policy Object required to administer the application through Group Policy. The configuration tools can automatically generate a suitable template, which you can edit afterwards if required.

To create the template, right-click on the Manageable Configuration Source node in the configuration editor tree, and click Generate ADM Template. Specify the file name and location in the Save As dialog. The configuration editor generates the file automatically. Afterwards, you can open it in a text editor (or Visual Studio) to view the contents.

Notice that the file contains a CLASS MACHINE section and a CLASS USER section containing the same content. For an ASP.NET Web application (as discussed in the previous article in this series), you will probably not require the CLASS USER section, and so you can remove it from the ADM file.

The configuration tool generates a full set of PARTS (controls) for each configuration setting, including drop-down lists where appropriate. However, it does not generate any EXPLAIN text other than the very brief note of the section that the settings apply to. You may wish to expand this, perhaps using a [strings] section within the file as demonstrated in the previous article. The template files (named EntLibManageable.adm) included with the sample application have not been edited, so that you can see the default content that the configuration tools generate.

To give you a feel for the kind of content in the administrative template, the following listing shows the category that defines the settings for the Caching Application Block. Notice that it uses nested categories to give a structure of multiple levels within the root key named “EntLibManageableSample:”

   CLASS MACHINE   CATEGORY "EntLibManageableSample"   CATEGORY "Caching"   CATEGORY "Cache managers"     POLICY "Specify settings for cache manager 'Cache Manager'"       KEYNAME "SoftwarePoliciesEntLibManageableSample                cachingConfigurationcacheManagersCache Manager"       VALUENAME "Available" VALUEON NUMERIC 1 VALUEOFF NUMERIC 0       PART "Expiration poll frequency (secs.)"         NUMERIC         VALUENAME "expirationPollFrequencyInSeconds"         DEFAULT 60         MIN 0       END PART       PART "Maximum elements in cache before scavenging"         NUMERIC         VALUENAME "maximumElementsInCacheBeforeScavenging"         DEFAULT 1000         MIN 0       END PART       PART "Number to remove when scavenging"         NUMERIC         VALUENAME "numberToRemoveWhenScavenging"         DEFAULT 10         MIN 0       END PART       PART "Backing store settings"         TEXT       END PART       PART "Partition name"         EDITTEXT         VALUENAME "partitionName"         KEYNAME "SoftwarePoliciesEntLibManageableSample            cachingConfigurationackingStoresIsolated Storage"         MAXLEN 255         REQUIRED
?
Figure 3. Machine-level Settings Generated by the Sample Application Administrative Template: Notice how the nested categories in the template create a nested hierarchy of settings.
         DEFAULT "ASPNET-EntLib"       END PART     END POLICY     ... more settings for caching ...     ... application block here ...   END CATEGORY  ; "Cache managers"   END CATEGORY  ; "Caching"   END CATEGORY  ; "EntLibManageableSample"

The policies defined in the section of the template shown above provide the controls to set the configuration of the Caching Application Block for any application that has “EntLibManageableSample” as the ApplicationName property of its Manageable Configuration Source provider. You can see that this provides a useful opportunity for managing multiple applications from one policy. However, bear in mind that you can only configure one Manageable Configuration Source provider for an application.

Figure 3 shows the Group Policy Object Editor displaying the settings for the section of the administrative template shown earlier, together with the sections for the other application blocks defined within the sample application.

Setting Configuration Values in Group Policy
After installing the administrative template, the next step is to set the values you require for the application settings. You do not, of course, have to set all of the values. Only settings enabled in Group Policy will replicate to Windows Registry, and therefore affect the application.

	?
Figure 4. Setting Configuration Values: The figure shows the screens where you set configuration values for the Data Access and Caching Application Blocks in the Group Policy Object Editor.

Figure 4 shows an example of setting configuration values for the sample application. You can see that the settings for “Cache Manager” (the Isolated Storage cache manager and backing store added to the application configuration) are enabled. The controls in the dialog allow you to specify settings such as the expiration poll frequency, number of items to remove when scavenging, and the Isolated Storage partition name for storing cached values.

Figure 4 also shows the single setting available for the Data Access Application Block (the settings for each database connection are in child nodes below this node). The drop-down list shows all the available connections defined within the configuration, and you can set the default connection to use when code does not specify a connection.

	?
Figure 5: Registry Settings: The figure shows machine-level settings for the sample application in Windows Registry; only a few of the settings have been enabled and configured in Group Policy.

The settings you specify do not replicate immediately. You can log off the target machine and then log on again to force the application of local policies, or you can restart the target machine to force the application of domain-level policies. Otherwise, they will be applied during the next security policy update cycle.

After the Group Policy settings replicate, you can view the results in the Windows Registry Editor (regedit.exe). Figure 5 shows the section from the HKEY_LOCAL_MACHINE hive that contains the sample application settings specified in Group Policy. You can see that only those settings enabled within Group Policy appear in the registry, and they are arranged in the same hierarchy as in the Group Policy Object Editor.

Testing the Manageable Configuration Source
The sample application uses the Enterprise Library Manageable Configuration Source provider to make it Group Policy aware. When you run the application with no Group Policy settings enabled, or if you set the EnableGroupPolicies property of the Manageable Configuration Source to False, it displays the default behavior. The left-hand list box uses the default SqlClient database provider, whereas the right-hand one uses the OleDb provider (see Figure 6).

	?
Figure 6. Sample Application: Here’s the default behavior of the two lists populated from the Northwind database when Group Policy is not applied.

The connection strings differ because the code that populates the left-hand list does not specify a database provider type, and so the Data Access Application Block generates one using the type specified as the default in the Web.config file:

   Database db = DatabaseFactory.CreateDatabase();

However, the code that populates the right-hand list does specify a database provider type?the LocalOleDbConnection defined in the Web.config file:

   Database db = DatabaseFactory.CreateDatabase(      "LocalOleDbConnection");

In addition, the code that runs when you click the Cache a Dataset to Disk button uses the default cache manager, as specified in the Web.config file:

   CacheManager diskCache = CacheFactory.GetCacheManager(); 

To see the effects of Group Policy, specify the settings in the Group Policy Editor for the Default database (in the Specify Database Block settings section) and the Default Cache Manager (in the Specify settings for Caching Block section). For example, select LocalOleDbConnection as the default database, and Custom Cache Manager as the default cache manager.

Now, when you run the example (after the settings replicate to Windows Registry), you’ll see that the code that populates the left-hand list box is now using the OleDb database provider instead of the SqlClient provider. The Manageable Configuration Source reads this setting from the registry and exposes it as the DefaultDatabase property for the Data Access Application Block (see Figure 7).

? Figure 7. Effect of Default Database Setting: The setting for the default database in Group Policy causes the application to use the OldDb provider for both lists.

? Figure 8. Effect of Default Cache Manager Setting: The setting for the default cache manager in Group Policy changes the behavior of the application to use the custom caching backing store provider, which writes cached data to disk files instead of Isolated Storage.

In addition, if you now click the Cache a DataSet to Disk button, you will see two files appear in your C:Temp folder (provided that you have this folder on your disk, and that ASP.NET has permission to write to it!). The Group Policy settings change the default cache manager from “Cache Manager,” which uses the Isolated Storage backing store provider, to “Custom Cache Manager,” which uses the custom file-based backing store provider (see Figure 8).

Other Group Policy settings you can experiment with in the sample application include:

• Turning on or off the instrumentation implemented within Enterprise Library using the settings in the Instrumentation section. You can turn on or off event logging, performance counters, and WMI event generation.
• Changing the connection strings for each of the database providers for the Data Access Application Block in the Connection Strings section under the Database node. If you specify an invalid connection string for the LocalOleDbConnection database provider, code in the application will write exception details to Windows Event Log.
• Changing the settings for the Formatted EventLog Trace Listener in the section for the Logging Application Block. The sample application writes exception details to Windows Event Log if an error occurs when populating the right-hand (OleDb) list box from the Northwind database. For example, if you change the setting for the name of the log from the default of “Application” to “System” (or to a custom Event Log you create), the messages will appear there instead. You can also specify a remote machine where message will be logged (provided that the ASP.NET has the relevant permission), and change the message format in the Log formatters section.
• Changing the settings in the Cryptography section for the hash provider and symmetric encryption provider used by the sample application. For example, you can turn on or off SALT hash generation, or specify a different symmetric encryption key file and scope.

So, Why Is All This Useful?
One of the strengths of Enterprise Library?besides the more obvious features such as providing you with ready-built and tested code that simplifies development?is that you can change the behavior of the application blocks and the core functionality through configuration. This reduces downtime and removes the error-prone task of updating the code and recompiling.

However, unless you store configuration centrally (for example, in a shared database), each instance of the application requires a local configuration file that defines the behavior of that instance. In a server farm for an ASP.NET application, or in an office where there are hundreds of desktop machines, application configuration files can (will) become out of synch as administrators (and users, if they have permission) edit the file to solve problems, debug code, or experiment with settings.

Group Policy lets you apply and enforce settings for an application, and ensures that all machines within an Active Directory forest or domain contain the correct settings. It is still possible for users that have access to the local configuration file to change the behavior (they could simply remove the Manageable Configuration Source provider from the configuration!), but otherwise, changing settings locally will have no effect.

In addition, Group Policy makes configuration updates easier, by letting administrators apply and deploy configuration remotely, removing the need to visit each machine, or manually deploy updated versions of the configuration files. And, when situations or requirements change, administrators can quickly apply new configuration settings to all machines. For example, if a database server should fail, it’s easy to change Group Policy settings to point all the machines at a different database server.