Appendix A - Enterprise Library Configuration Scenarios

On this page:

Download:

About Enterprise Library Configuration | External Configuration | Programmatic Support - Using the Fluent Interfaces | Scenarios for Advanced Configuration | Scenario 1: Using the Default Application Configuration File | Scenario 2: Using a Non-default Configuration Store | Scenario 3: Sharing the Same Configuration between Multiple Applications | Scenario 4: Sharing Configuration Sections across Multiple Applications | Scenario 5: Applying a Common Configuration Structure for Applications | Scenario 6: Managing Configuration in Different Deployment Environments | More Information

The comprehensive configuration capabilities of Enterprise Library—the result of the extensible configuration system and the configuration tools it includes—make Enterprise Library highly flexible and easy to use. The combination of these features allows you to:

• Read configuration information from a wide range of sources.
• Enforce common configuration settings across multiple applications.
• Share configuration settings between applications.
• Specify a core set of configuration settings that applications can inherit.
• Merge configuration settings that are stored in a shared location.
• Create different configurations for different deployment environments.

This appendix provides an overview of the scenarios for using these features and demonstrates how you can apply them in your own applications and environments. For more information on the scenarios presented here, see "Configuring Enterprise Library" in the Enterprise Library Reference Documentation.

About Enterprise Library Configuration

Enterprise Library configuration information is retrieved using instances of classes that implement the IConfigurationSource interface, and are typically known as configuration sources. Figure 1 shows a high-level view of the two types of information for a configuration source and the different ways that an application's configuration can be defined and applied.

Figure 1 - Configuration sources in Enterprise Library

External Configuration

External configuration encompasses the different ways that configuration information can reside in a persistent store and be applied to a configuration source at run time. Possible sources of persistent configuration information are files, a database, and other custom stores. Enterprise Library can load configuration information from any of these stores automatically. To store configuration in a database you can use the SQL configuration source that is available as a sample from the Enterprise Library community site. You can also specify one or more configuration sources to satisfy more complex configuration scenarios, and create different configurations for different run-time environments. See the section "Scenarios for Advanced Configuration" later in this appendix for more information.

Programmatic Support

Programmatic support encompasses the different ways that configuration information can be generated dynamically and applied to a configuration source at run time. Typically, in Enterprise Library this programmatic configuration takes place through the fluent interface specially designed to simplify dynamic configuration, or by using the methods exposed by the Microsoft® .NET Framework System.Configuration API.

Using the Fluent Interfaces

All of the application blocks except for the Validation Application Block and Policy Injection Application Block expose a fluent interface. This allows you to configure the block at run time using intuitive code assisted by Microsoft IntelliSense® in Visual Studio® to specify the providers and properties for the block. The following is an example of configuring an exception policy for the Exception Handling Application Block and loading this configuration into the Enterprise Library container.

var builder = new ConfigurationSourceBuilder();

builder.ConfigureExceptionHandling()
       .GivenPolicyWithName("MyPolicy")
       .ForExceptionType<NullReferenceException>()
         .LogToCategory("General")
           .WithSeverity(System.Diagnostics.TraceEventType.Warning)
           .UsingEventId(9000)
         .WrapWith<InvalidOperationException>()
           .UsingMessage("MyMessage")
         .ThenNotifyRethrow();

var configSource = new DictionaryConfigurationSource();
builder.UpdateConfigurationWithReplace(configSource);
ExceptionPolicy.SetExceptionManager(new ExceptionPolicyFactory(configSource).CreateManager());

Scenarios for Advanced Configuration

The Enterprise Library stand-alone configuration console and the Visual Studio integrated configuration editor allow you to satisfy a range of advanced configuration scenarios based on external configuration sources such as disk files. When you use the configuration tools without specifying a configuration source, they default to using the System Configuration Source to create a single configuration file that contains the entire configuration for the application. Your application will expect this to be named App.config or Web.config (depending on the technology you are using), and will read it automatically.

You can select Add Configuration Settings on the Blocks menu to display the section that contains the default system configuration source. If you click the chevron arrow to the right of the Configuration Sources title to open the section properties pane you can see that this is also, by default, specified as the Selected Source—the configuration source to which the configuration generated by the tool will be written. When an application that uses Enterprise Library reads the configuration, it uses the settings specified for the selected source unless a different source is explicitly requested.

The following sections describe the common scenarios for more advanced configuration that you can accomplish using the configuration tools. Some of these scenarios require you to add additional configuration sources to the application configuration.

Scenario 1: Using the Default Application Configuration File

This is the default and simplest scenario. You configure your application using the configuration tool without adding a Configuration Sources section or any configuration sources. You must specify either your application's App.config or Web.config file when you save the configuration, or use the configuration tool to edit an existing App.config or Web.config file.

Scenario 2: Using a Non-default Configuration Store

In this scenario, you want to store your configuration in a file or other type of store, instead of in the application's App.config or Web.config file. To achieve this you:

1. Use the configuration tools to add a suitable configuration source to the Configuration Sources section. If you want to use a standard format configuration file, add a file-based configuration source. To store the configuration information in a different type of store, you must install a suitable configuration source. You can use the sample SQL configuration source that is available from the Enterprise Library community site at https://entlib.codeplex.com to store your configuration in a database.
2. Set the relevant properties of the new configuration source. For example, if you are using the built-in file-based configuration source, set the File Path property to the path and name for the configuration file.
3. Set the Selected Source property in the properties pane for the Configuration Sources section to your new configuration source. This updates the application's default App.config or Web.config file to instruct Enterprise Library to use this as its configuration source.

Scenario 3: Sharing the Same Configuration between Multiple Applications

In this scenario, you want to share configuration settings between multiple applications or application layers that run in different locations, such as on different computers. To achieve this, you simply implement the same configuration as described in the previous scenario, locating the configuration file or store in a central location. Then specify this file or configuration store in the settings for the configuration source (such as the built-in file-based configuration source) for each application.

Scenario 4: Sharing Configuration Sections across Multiple Applications

In this scenario, you have multiple applications or application layers that must use the same shared configuration for some application blocks (or for some sections of the configuration such as connection strings). Effectively, you want to be able to redirect Enterprise Library to some shared configuration sections, rather than sharing the complete application configuration. For example, you may want to specify the settings for the Logging Application Block and share these settings between several applications, while allowing each application to use its own local settings for the Exception Handling Application Block. You achieve this by redirecting specific configuration sections to matching sections of a configuration store in a shared location. The steps to implement this scenario are as follows:

1. Use the configuration tools to add a suitable configuration source for your application to the Configuration Sources section. This configuration source should point to the shared configuration store. If you want to use a standard format configuration file as the shared configuration store, add a file-based configuration source. To store the shared configuration information in a different type of store, you must install a suitable configuration source. You can use the sample SQL configuration source that is available from the Enterprise Library community site at https://entlib.codeplex.com to store your configuration in a database.
2. Set the relevant properties of the shared configuration source. For example, if you are using the built-in file-based configuration source, set the File Path property to the path and name for the application's configuration file.
3. Set the Selected Source property in the properties pane for the Configuration Sources section to System Configuration Source.
4. Click the plus-sign icon in the Redirected Sections column and click Add Redirected Section. A redirected section defines one specific section of the local application's configuration that you want to redirect to the shared configuration source so that it loads the configuration information defined there. Any local configuration settings for this section are ignored.
5. In the new redirected section, select the configuration section you want to load from the shared configuration store using the drop-down list in the Name property. The name of the section changes to reflect your choice.
6. Set the Configuration Source property of the redirected section by selecting the shared configuration source you defined in your configuration. This configuration source will provide the settings for the configuration sections that are redirected.
7. Repeat steps 4, 5, and 6 if you want to redirect other configuration sections to the shared configuration store. Configuration information for all sections for which you do not define a redirected section will come from the local configuration source.
8. To edit the contents of the shared configuration store, you must open that configuration in the configuration tools or in a text editor; you cannot edit the configuration of shared sections when you have the local application's configuration open in the configuration tool. If you open the shared configuration in the configuration tool, ensure that the Selected Source property of that configuration is set to use the system configuration source.

Note

You cannot share the contents of the Application Settings section. This section in the configuration tool stores information in the standard <appSettings> section of the configuration file, which cannot be redirected.

Scenario 5: Applying a Common Configuration Structure for Applications

In this scenario you have a number of applications or application layers that use the same configuration structure, and you want to inherit that structure but be able to modify or add individual configuration settings by defining them in your local configuration file. You can specify a configuration that inherits settings from a parent configuration source in a shared location, and optionally override local settings. For example, you can configure additional providers for an application block whose base configuration is defined in the parent configuration. The steps to implement this scenario are as follows:

1. Use the configuration tools to add a suitable configuration source for your application to the Configuration Sources section. This configuration source should point to the shared configuration store. If you want to use a standard format configuration file as the shared configuration store, add a file-based configuration source. To store the shared configuration information in a different type of store, you must install a suitable configuration source. You can use the sample SQL configuration source that is available from the Enterprise Library community site at https://entlib.codeplex.com to store your configuration in a database.
2. Set the relevant properties of the shared configuration source. For example, if you are using the built-in file-based configuration source, set the File Path property to the path and name for the application's configuration file.
3. Set the Parent Source property in the properties pane for the Configuration Sources section to your shared configuration source. Leave the Selected Source property in the properties pane set to System Configuration Source.
4. Configure your application in the usual way. You will not be able to see the settings inherited from the shared configuration source you specified as the parent source. However, these settings will be inherited by your local configuration unless you override them by configuring them in the local configuration. Where a setting is specified in both the parent source and the local configuration, the local configuration setting will apply.
5. To edit the contents of the shared parent configuration store, you must open that configuration in the configuration tools or in a text editor; you cannot edit the configuration of parent sections when you have the local application's configuration open in the configuration tool. If you open the parent configuration in the configuration tool, ensure that the Selected Source property of that configuration is set to use the system configuration source.

Note

The way that the configuration settings are merged, and the ordering of items in the resulting configuration, follows a predefined set of rules. These are described in detail in the Enterprise Library Reference Documentation.

Scenario 6: Managing Configuration in Different Deployment Environments

In this scenario, you want to be able to define different configuration settings for the same application that will be appropriate when it is deployed to different environments, such as a test and a production environment. In most cases the differences are minor, and usually involve settings such as database connection strings or the use of a different provider for a block. Enterprise Library implements this capability using a feature called environmental overrides. The principle is that you specify override values for settings that are different in two or more environments, and the differences are saved as separate delta configuration files. The administrator then applies these differences to the main configuration file when the application is deployed in each environment. To achieve this:

1. Use the configuration tools to add a file-based configuration source to the Configuration Sources section.
2. Open the Environments menu and click New Environment for each desired environment. This adds a drop-down list for each environment, Overrides on Environment Name, to each configuration element. If you select Override Properties in an environment’s drop-down list, you can specify the setting overrides for the element in that environment.
3. Open the properties pane for each of the environments you added to your configuration by clicking the chevron arrow to the right of the environment title, and set the Environment Delta File property to the path and name for the delta file for that environment.
4. Specify the overrides to the configuration elements that need environment-specific settings.
5. Save the configuration. The configuration tool generates a normal (.config) file and a delta (.dconfig) file for each environment. The delta file(s) can be managed by administrators, and stored in a separate secure location, if required. This may be appropriate when, for example, the production environment settings should not be visible to developers or testers.
6. To create a run-time merged configuration file (typically, this is done by an administrator):
   • Open the local configuration (.config) file.
   • Select Open Delta File from the Environments menu and load the appropriate override configuration (.dconfig) file.
   • Set the Environment Configuration File property in the properties pane for the environment to the path and name for the merged configuration file for that environment.
   • Right-click on the title of the environment and click Export Merged Environment Configuration File.
7. Deploy the merged configuration file in the target environment.

Enterprise Library also contains a command-line utility named MergeConfiguration.exe that you can use to merge configuration and delta files if you do not have the configuration console deployed on your administrator system. It can also be used if you wish to automate the configuration merge as part of your deployment process. For more information about MergeConfiguration.exe, see "Configuring a Deployment Environment" in the Enterprise Library Reference Documentation.

Note

You cannot use environmental overrides with redirected sections or inherited configuration settings. You can only use them when the entire configuration of your application is defined within a local configuration source.

For more information on all of the scenarios presented here, see "Configuring Enterprise Library" in the Enterprise Library Reference Documentation.

More Information

All links in this book are accessible from the book's online bibliography on MSDN at https://aka.ms/el6biblio.

For more information on the scenarios presented here, see "Configuring Enterprise Library" in the Enterprise Library Reference Documentation.

To store configuration in a database you can use the SQL configuration source that is available as a sample from the Enterprise Library community site.

The way that the configuration settings are merged, and the ordering of items in the resulting configuration, follows a predefined set of rules. These are described in detail in the Enterprise Library Reference Documentation.

For more information about MergeConfiguration.exe, see "Configuring a Deployment Environment" in the Enterprise Library Reference Documentation.

General Links:

• There are resources to help if you're getting started with Enterprise Library, and there's help for existing users as well (such as the breaking changes and migration information for previous versions) available on the Enterprise Library Community Site at https://www.codeplex.com/entlib/.
• For more details about the Enterprise Library Application Blocks, see the Enterprise Library Reference Documentation and the Enterprise Library 6 Class Library.
• You can download and work through the Hands-On Labs for Enterprise Library, which are available at https://aka.ms/el6hols.
• You can download the Enterprise Library binaries, source code, Reference Implementation, or QuickStarts from the Microsoft Download Center at https://go.microsoft.com/fwlink/p/?LinkID=290898.
• To help you understand how you can use Enterprise Library application blocks, we provide a series of simple example applications that you can run and examine. To obtain the example applications, go to https://go.microsoft.com/fwlink/p/?LinkID=304210.

Next Topic | Previous Topic | Home | Community