Configuration

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
The latest Enterprise Library information can be found at the Enterprise Library site.

On this page:

Configuring Enterprise Library | Configuration in XAML Files | Options for Generating XAML Configuration Files | Creating Application Configuration Files Using the Configuration Console - Configuration Console with Visual Studio Integration, Stand-alone Configuration Console, Selecting Types in the Configuration Console, Using Non-default Configuration Sources | Generating XAML Configuration Using the Configuration Console | Generating XAML Using the MSBuild Task | Generating XAML Configuration Files Using the Command Line | Using Custom Enterprise Library Extensions - Place Custom Extensions in a .NET Assembly, Adding a XAML Alias | XAML Translation Considerations - Mapping Types between .NET Framework Types and Silverlight, Silverlight 4 Types in Configuration Will Also Work in a Silverlight 5 Application | Security Considerations for Using XAML Configuration Files

One of the strengths of Enterprise Library has always been the flexibility it provides through its configuration settings. By making changes to an application's configuration you can, for example, change the way the Enterprise Library logs exceptions or handles validation.

In the Enterprise Library 5.0 Silverlight® Integration Pack, the process for configuring Enterprise Library is largely the same as in Enterprise Library 5.0. You can either create a configuration file using the configuration console, create the configuration files by hand, or programmatically configure Enterprise Library.

In this chapter, we’ll describe several options for creating configuration files with the Enterprise Library 5.0 Silverlight Integration Pack, for example by using the configuration console. We’ll also discuss several things to keep in mind when creating configuration files. We’ll also describe several options for consuming the configuration files in a Silverlight application. At the end of this chapter, we’ll have a look at how the Stock Trader V2 Reference Implementation uses configuration.

Configuring Enterprise Library

The most common way to configure Enterprise Library is to use the configuration console. This tool provides an easy-to-use graphical user interface for creating configuration files. The following image shows an example of a configuration file as it is shown in the configuration console.

This configuration file shows how exceptions and logging errors and warnings are being logged to the Windows Event Log. The Text Formatter is used to create an easy-to-read log message. There is a section in the configuration console for each application block.

For more information on creating application configuration files using the configuration console, please refer to the chapter on Using Configuration Tools in the Enterprise Library documentation on MSDN.

Configuration in XAML Files

The Enterprise Library 5.0 Silverlight Integration Pack does not rely on application configuration files, because the System.Configuration namespace is not available in Silverlight. Instead, it stores configuration information in XAML configuration files. The following snippet shows an example of such a XAML configuration file, which configures the Logging Application Block to write log messages to isolated storage.

<el:ConfigurationDictionary  
        xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation" 
        xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml" 
        xmlns:el="https://schemas.microsoft.com/practices/2011/entlib">
    <el:LoggingSettings DefaultCategory="default" 
             x:Key="loggingConfiguration" 
             LogWarningWhenNoCategoriesMatch="False">
        <el:LoggingSettings.TraceListeners>
            <el:IsolatedStorageTraceListenerData 
                 Name="isolated" 
                 RepositoryName="LogMessagesInIsolatedStorage" 
                 MaxSizeInKilobytes="256"/>
        </el:LoggingSettings.TraceListeners>
        <el:LoggingSettings.TraceSources>
            <el:TraceSourceData Name="default" DefaultLevel="Warning">
                <el:TraceSourceData.TraceListeners>
                    <el:TraceListenerReferenceData Name="isolated"/>
                </el:TraceSourceData.TraceListeners>
        </el:LoggingSettings.TraceSources>
    </el:LoggingSettings> 
</el:ConfigurationDictionary>  

One of the drawbacks of using XAML for storing configuration is that it's more verbose than the traditional XML configuration files. Fortunately, you don't have to edit the XAML files by hand. In the next chapter, we'll describe how you can generate the XAML configuration files from application configuration files, which can be edited using the configuration console.

Options for Generating XAML Configuration Files

While it's possible to edit the XAML configuration files used by the Enterprise Library 5.0 Silverlight Integration Pack by hand, it's much easier to generate them from application configuration files, which can be edited by the Enterprise Library Configuration Console.

The following diagram shows several ways for generating XAML configuration files:

When you have created an application configuration file, you can convert it to a Silverlight XAML configuration file using a wizard in the configuration tool. There are also two options for automating this XAML generation process: using an MSBuild task, which allows you to integrate the XAML generator in an automated build process and using a command line executable, which makes it easy to execute the XAML generator from a script.

Creating Application Configuration Files Using the Configuration Console

The process for creating configuration files is largely the same as it was with Enterprise Library 5.0. First, you’ll start up the configuration console, and then add configuration sections for the required application blocks, update the configuration, and save the file. For the Enterprise Library 5.0 Silverlight Integration Pack, this process is largely the same. However, depending on how you installed the configuration console, you will get a slightly different experience.

Configuration Console with Visual Studio Integration

If you have installed the configuration console from the Extension Manager, then you can launch the configuration console from Microsoft® Visual Studio®, by right clicking on an application configuration file. It also allows you to start the console with a new feature called profiles, which allows the console to only show application blocks that make sense for a particular environment. If you are creating a configuration file that will be consumed by the server, then you shouldn’t be able to add application blocks that only work in Silverlight, and vice versa.

When your configuration file is in a web application project, then you can start the console with: Edit Server configuration (the desktop profile, which shows only the application blocks that work with the Microsoft .NET Framework) and Edit Silverlight configuration (the Silverlight profile, which only shows the application blocks for Silverlight). However, when your configuration file is in a Silverlight project, then you will only be able to select Edit Silverlight Configuration and start with the Silverlight profile.

Sharon Says:

You can edit an application configuration file from a Silverlight using this Visual Studio integration. However, the Silverlight project template will not allow you to add an application configuration file. If you want to add a configuration file to a Silverlight project so that you can use that file to generate a XAML configuration file, you will need to add the file as a regular XML (.xml) file, then rename it to an application configuration file (.config) file and add an empty <configuration/> element to it. Then you can edit it using the configuration console with Visual Studio integration.

Stand-alone Configuration Console

If you have installed the configuration console using the Microsoft Enterprise Library 5.0 installer, then you will not be able to start the configuration console from Visual Studio. You will also not be able to use the profiles, so you will see all the application blocks that are currently installed.

The stand-alone configuration console is compiled for different platforms: .NET Framework 4.0, .NET Framework 4.0 32-bit, .NET Framework 3.5. If you want to edit Silverlight configuration files, you will need to select the .NET Framework 4.0 32-bit version for the configuration console, because Silverlight 4 only supports 32-bit applications.

Selecting Types in the Configuration Console

In certain situations, the configuration console allows you to select certain types. For example, while configuring an exception handling policy for the Exception Handling Block, you will need to select the type of exception that you want to handle. There are some limitations to which types the configuration console can select.

The configuration console uses reflection to load the types from the assembly. To do this, the configuration console must actually load the assembly into the appdomain. Silverlight has support for binary compatibility, though it will not work on any type. You can only use types that reference only the following assemblies:

• Mscorlib
• System
• System.Core
• System.ComponentModel.Composition
• Microsoft.VisualBasic

Usually, this means that you can select Silverlight exception types, but custom extensions, such as a custom exception handler you can likely not select from the configuration console. The section on Using Custom Enterprise Library Extensions describes how you can use these.

Note

When you select an exception formatter to export to XAML, you will need to take an additional step for this to be exported correctly. The runtime only expects a partial type name, but the XAML generation logic needs a fully qualified name. In order for the export to XAML logic to work, you will either need to change the type name to the fully qualified name, or reselect the type using the type picker.

Using Non-default Configuration Sources

The Enterprise Library configuration tool allows you to store configuration information in a different location than application configuration files. For example, you can store your configuration in an external XML file by using a file-based configuration source.

Only the wizard in the configuration console will honor the non-default configuration sources. The other tools, such as the MSBuild task, cannot use non-default configuration sources. That is why this option has been removed from the Silverlight profile. It is still present in the desktop profile though.

However, if you store the configuration for a particular block in a separate file using the file-based configuration source, then you can use the XAML generation tools directly on the separate configuration file.

Ed Says:

In Stock Trader V2, we're using this feature to share validation configuration between client and server. The validation configuration was stored in a separate configuration file, called validation.config. The web.config uses this file as a file-based configuration source. We're also using this file to generate the validation.xaml file. And we've built a mechanism in Stock Trader V2 to read and merge multiple configuration files.

Please refer to the online documentation on Non-Default Configuration Sources on MSDN.

Generating XAML Configuration Using the Configuration Console

The most direct option for creating XAML configuration files is using the configuration console. The configuration console contains a wizard that will take the information in the configuration file and export it to XAML.

It is possible for the configuration wizard to encounter problems during the generation process. For example, if you have configured a trace listener that is not supported in Silverlight, or have selected a type that does not exist in Silverlight, then the export wizard will report this as a warning. If you choose to continue, then the Export to XAML wizard will ignore the sections that cannot be converted to XAML. The application settings and database, which are added by default by the configuration console, will also be ignored by the wizard, since they are not supported in Silverlight.

Ed Says:
	The export wizard does not support exporting the configuration for custom blocks to XAML. This feature is supported by the command-line tool and the MSBuild task, so if you use custom configuration blocks, you should choose these options.

Creating a XAML configuration file using the wizard

1. Launch the Configuration Console

2. Select File Open to open a configuration file

3. Select Wizards Export To XAML to export the file to XAML

   

4. Enter the output filename in the wizard and press Finish. If you don't select a location and just enter a filename, then the file will be placed in your My Documents folder.

   

5. Include the configuration file in your Silverlight application, as described in the chapter on Consuming XAML Configuration from a Silverlight application.

Generating XAML Using the MSBuild Task

The Enterprise Library 5.0 Silverlight Integration Pack also ships with an MSBuild task that you can use to automate the generation of XAML configuration files in a build script.

The following shows an example of an MSBuild project file:

<Project xmlns='https://schemas.microsoft.com/developer/msbuild/2003' 
      DefaultTargets='Translate'>
  <UsingTask 
      AssemblyFile='Microsoft.Practices.EnterpriseLibrary.
      Configuration.ExportToXaml.MsBuild.dll' TaskName='ExportToXamlTask'/>
  <Target Name='Translate'>
      <ExportToXamlTask Assemblies='$(PathToBinaries)' 
          Source='Configuration.config' Destination='Configuration.xaml'>
          <Output TaskParameter='EffectiveDestination' 
                 PropertyName='EffectiveDestination'/>
      </ExportToXamlTask>
      <Message Text='The value for output is $(EffectiveDestination)'/>
  </Target> 
</Project>

This MSBuild file first configures the ExportToXamlTask, which resides in the assembly called Microsoft.Practices.EnterpriseLibrary.Configuration.ExportToXaml.MsBuild.dll. It then creates a new Target that will execute the ExportToXamlTask. This task supports the following parameters:

• Assemblies (required). You will need to specify where the binaries, required for the translation process, are located.
• Source (required). The name of the source application configuration file that should be converted to XAML.
• Destination. Allows you to specify the name and location for the generated XAML file.
• EffectiveDestination (output). Returns the actually used output file. This is useful if you don't specify a destination and want to use the output of this file further in the process.
• OverwriteDestination. Allows you to specify whether the output file should be overwritten.
• Verbose. Display all output, including information messages.
• Sections. Name of a section to include in the conversion, in addition to the Enterprise Library sections. Allows you to specify additional custom configuration sections that you want to have converted.
• NameMappings. Changes the name of the XAML element for the specified type (using the full type name, with no assembly name) to the specified expanded XAML name (using the "{namespace}element" syntax).
• TypeMappings. Indicates a type name translation for configuration settings containing type names.

Generating XAML Configuration Files Using the Command Line

It is also possible to generate XAML configuration files from the command line. This can be useful for automating the configuration generation if you're not using MSBuild.

The syntax for the command-line tool is:

ExportToXaml.exe "source file" [options]

There are several options you can specify:

Option	Description
-out:destination	Name of the output XAML file. Defaults to the name of the source file with a .xaml extension.
-force	Forces the file to be overwritten, even if the file is read-only.
-verbose	Display all outputs, including information messages.
-assemblies:path	Path to the folder with the assemblies required to load the configuration file.
-section:section	Name of a section to include in the conversion, in addition to the Enterprise Library sections. Allows you to specify additional custom configuration sections that you want to have converted.
-nameMapping:type=xname	Changes the name of the XAML element for the specified type (using the full type name, with no assembly name) to the specified expanded XAML name (using the "{namespace}element" syntax).
-typeMapping:type=mapping	Indicates a type name translation for configuration settings containing type names.
-translator:type=translator	Indicates a custom translator for a type. Requires the full name of the source type and the assembly-qualified name of the translator type.

Using Custom Enterprise Library Extensions

A common scenario when using Enterprise Library is to create and use your own custom extensions. For example, you might like to create a custom exception handler or a custom call handler. The Enterprise Library 5.0 Silverlight Integration Pack supports the usage of custom extensions, just like Enterprise Library 5.0.

However, as mentioned before, there are some limitations to which types you can select using the configuration console, due to the fact that the configuration console cannot load all Silverlight types. These limitations usually don’t allow you to select a custom extension that is only present in Silverlight in the configuration console.

If you need the ability to select custom extensions from the configuration console, then you can perform the steps described in the following paragraph to create .NET Framework version of the custom extension. That version can then be loaded into the configuration console normally.

Place Custom Extensions in a .NET Assembly

If you want to add design-time support for your custom Silverlight extensions in the configuration console, you can do so by creating a desktop version of the custom types you'd like to configure. The following diagram shows an example of how this can work:

This diagram shows how you can create a custom exception handler, with its exception handler data, but would work the same for custom logging handlers.

To create a custom exception handler for the Enterprise Library 5.0 Silverlight Integration Pack, you'll need to create both a custom exception handler and its exception handler data. If you want to select the custom exception handler from the configuration console, you will also need to create a .NET Framework assembly that contains the same classes. Here are the guidelines to follow when creating a desktop version of your classes:

• The name of the type in the desktop assembly should match the name of the type in the Silverlight assembly.
• The desktop version of the custom exception handler should reference the custom exception handler data using the Configuration Element Type Attribute.
• If the namespace or assembly name differs between the desktop and Silverlight assembly, then it is recommended you use XAML aliases. More information on XAML aliases can be found in the section on Adding XAML Aliases.
• If you don't want to use the XAML aliases, you can use the nameMappings property on the ExportToXAML MSBuild task and the ExportToXAML command-line tool. This property is not available in the wizard in the configuration console.

The desktop version of the custom exception handler and custom exception handler data don't need to have actual implementations if you are just using them to allow for selection of the type in the configuration console. However, the easiest way to create the desktop version of the custom handler would be to create a Visual Studio linked file in the desktop project that links to the file in the Silverlight project. This ensures that the Silverlight and desktop versions will always have the same type names and namespaces.

Adding a XAML Alias

Having your Silverlight and desktop versions of the custom extensions in differently named assemblies or different namespaces can cause issues for the XAML configuration generation process The XAML generator, which is a desktop application, can easily read the desktop assemblies with their namespaces, but has no idea what the assembly name or namespace in Silverlight is going to be. To solve this, you can use XAML namespace aliases.

Similar to namespaces in C#, XAML uses namespaces to define which assembly and namespace a particular class is located in. There are two ways you can do this in XAML: You can either add a namespace that directly targets a namespace from a particular assembly, or use a namespace alias in the form of a URI. The following code example shows both a namespace alias (the d namespace) and a namespace that points to a particular namespace in a particular assembly (the inf namespace).

xmlns:d="https://schemas.microsoft.com/expression/blend/2008"
xmlns:inf="clr-namespace:StockTraderRI.Infrastructure;assembly=StockTraderRI.Infrastructure"

The advantage of using aliases is that you can have several namespaces from several different assemblies that share the same alias. But you can also use this to have both the desktop and Silverlight assemblies and namespaces share the same XAML files.

You can add a XAML namespace in your AssemblyInfo.cs file like this:

[assembly: XmlnsDefinition("http://URI.Goes.Here", "Namespace.Goes.Here")]

You should add the Xmlns definition attribute and Xmlns prefix attribute to both your Silverlight and desktop assemblies where they point to the correct namespace.

Once you have created a XAML configuration file, you then have to get your Silverlight application to pick up and load the configuration file. This process is often referred to as bootstrapping your application.

XAML Translation Considerations

There are a couple of things you need to keep in mind when performing the XAML Generation.

Mapping Types between .NET Framework Types and Silverlight

When you are creating an application configuration file to be translated to XAML, it’s likely that your configuration file contains .NET Framework types. For example, if you are creating an exception handler to handle an InvalidOperationException, you’ll likely select the .NET Framework version of this exception. The XAML configuration file can only contain Silverlight types. So the .NET Framework type has to be mapped to a Silverlight type, and the mapping must include their assembly name, version, and public key token.

For types that originate in the following assemblies, this translation happens automatically:

• mscorlib
• System
• System.Core
• System.ServiceModel

However, if you are using types that originate from other assemblies, you will need to specify a type mapping. Only the command-line tool and the MSBuild task support this. If you can change assemblies, you can also use a XAML alias.

Silverlight 4 Types in Configuration Will Also Work in a Silverlight 5 Application

The current XAML generation tools will generate XAML configuration files that target Silverlight 4. If you are building a Silverlight 5 application, you can still use these XAML configuration files, because Silverlight will automatically use the highest version number available when instantiating a type. So if your configuration file references a Silverlight 4 file, and the client only uses a Silverlight 5 type, the type will still load normally.

Security Considerations for Using XAML Configuration Files

Do not store any sensitive information in your configuration files, such as user names or passwords. It is nearly impossible to store configuration information on the client in such a way that it cannot be accessed by the user or a system administrator.

Also, unless you transfer your configuration files over a secure connection, such as SSL, then the information in the configuration file is not protected against information disclosure. This also holds true if you embed your configuration file in the XAP, since the XAP file is essentially a zip file that will contain the configuration file as clear text.

If you like, you can implement a server-side authentication and authorization mechanism so that only authorized users are able to download your application and its configuration files. The ConfigureAsync method from the EnterpriseLibraryContainer class contains an overload that allows you to specify credentials to use when downloading a file. However, this does not prevent authorized users from reading the configuration information.

Next Topic | Previous Topic | Home

Last built: July 8, 2011