Changes in This Release

Enterprise Library 5.0 is a new release of the Microsoft patterns & practices Enterprise Library. One of the major changes is the implementation of full dependency injection capabilities for instantiating and managing the lifetime of objects, which makes creation of Enterprise Library objects consistent across the entire library. Enterprise Library can now be used with different dependency injection containers. Unity is the default dependency injection container. For alternative DI container configuration plug-ins go to the patterns & practices: Enterprise Library Contrib Web site.

This release also includes additions in functionality to several of the existing application blocks. In addition, this release has been adapted to work with both Microsoft Visual Studio® 2008 and Microsoft Visual Studio 2010; and with the Microsoft .NET Framework versions 4.0 and 3.5 with Service Pack 1.

The following sections discuss these and other changes:

• Integration of Unity and Object Builder
• Breaking Changes
• Changes That Affect All Application Blocks
• Changes to the Configuration Tool
• Changes to the Caching Application Block
• Changes to the Cryptography Application Block
• Changes to the Data Access Application Block
• Changes to the Exception Handling Application Block
• Changes to the Logging Application Block
• Changes to the Policy Injection Application Block
• Changes to the Security Application Block
• Changes to the Validation Application Block

Go to CodePlex for information on Known Issues.

Integration of Unity and Object Builder

In this release of Enterprise Library, the underlying technique for creating objects uses a single dependency injection container; with Unity as the default container. It fully encompasses the move to using dependency injection techniques through Unity to instantiate objects. You can use the container to generate instances of Enterprise Library objects and inject them into other objects.

Enterprise Library provides a standard interface for obtaining instances of objects such as a SqlDatabase or a LogWriter, defined in the Enterprise Library configuration, from the Unity container (or from an alternative container providing that you have suitable configuration plug-ins for that container). In addition, injection-friendly instance facades are now available in addition to the Enterprise Library static facades, which cannot be used with injection, but are provided for backward compatibility with previous versions.

The example code in this guidance now uses the dependency injection-based approach. However, the previous techniques that used the static factory classes and the static facades are still supported in this release. For more information about the previous approach to instantiating objects, see the online documentation for Enterprise Library 4.1 available on the MSDN Web Site.

Object Builder, the low-level dependency injection mechanism, has also been subsumed into Unity in this release. You no longer need to reference the Object Builder assembly in your projects, or distribute it with your applications.

For more information about Unity, see Unity Dependency Injection and Interception.

For more information about interception, see Using Interception and Policy Injection.

For more information about the integration of Unity and Enterprise Library, see The Dependency Injection Model.

For more information about writing application code that takes advantage of Unity integration, see Using Enterprise Library in Applications.

Breaking Changes

This section lists the breaking changes in Enterprise Library 5.0.

• Enterprise Library now throws an ActivationException for configuration errors. Previously, the exception raised was System.Configuration.ConfigurationErrorsException. This includes errors such as trying to resolve an instance provider that does not have configuration information.
• Where Enterprise Library in previous versions threw a BuildFailedException upon failure to retrieve the default block instance, now an ActivationException is thrown for all application blocks.
• In previous versions of Enterprise Library, an ArgumentNullException was thrown if a null source was passed to the container in the call to the CreateDefaultContainer class. In this release, a NullReferenceException is thrown.
• ObjectBuilder2 is no longer a separate assembly. The code is now completely contained in the Unity assembly and there is no need to reference ObjectBuilder2.dll in your projects.
• WMI support has been removed from Enterprise Library except for the WMI Trace Listener in the Logging block. Enterprise Library no longer exposes its configuration through WMI, and the application blocks no longer raise WMI events. Only the WMI Trace Listener in the Logging block still raises WMI events.
• If you fail to close the DbDataReader, you can cause random and hard to find errors in your code—particularly when you are operating under an implicit transaction created within a TransactionScope context. You must always ensure that your application closes the DbDataReader in a timely fashion, either by explicitly closing the reader with the DbDataReader.Close method or by forcing the disposal of the DbDataReader, which results in the Close method being called. Code that forces closure of a DbDataReader by terminating an enclosing TransactionScope may leak a connection or fail unpredictably.
• If you used validator attributes in your code you must now reference the System.ComponentModel.DataAnnotations assembly.
• The signature for the FileConfigurationSource.Save method has changed. The method now has two parameters instead of three.
• The functionality of the Microsoft.Practices.EnterpriseLibrary.Configuration.Design.dll assembly and other design-time assemblies has been replaced by a new assembly named Microsoft.Practices.EnterpriseLibrary.Configuration.DesignTime.dll.
• The Policy Injection Application Block call handlers have been moved from the PolicyInjection assembly to the assemblies of the application blocks to which they apply; with the exception of the Performance Counter call handler, which was moved from the PolicyInjection.CallHandlers to the PolicyInjection assembly.
• The CachingCallHandler previously included in the Policy Injection Application Block has un-resolvable security vulnerabilities, and has been removed from the Policy Injection Application Block. If you still wish to use this call handler, you can obtain it from the patterns & practices: Enterprise Library Contrib Web site.

Changes That Affect All Application Blocks

The following changes to Enterprise Library affect all the application blocks:

• Major architectural revisions in Enterprise Library to use the dependency injection mechanism. All of the application blocks and the core system in Enterprise Library now use the dependency injection mechanism, with Unity as the default dependency injection mechanism, to create and manage the lifetime of individual Enterprise Library objects such as Database, LogWriter, and others. The static facades and static classes that were previously provided by Enterprise Library in previous versions have a new implementation that uses the new Dependency Injection infrastructure. However, these facades and classes are still included in Enterprise Library for backwards compatibility with existing application code, and you can continue to use the previous approach to creating Enterprise Library objects. For more information, see Using Enterprise Library in Applications.
• Container independence is accomplished through the container's implementation of IServiceLocator interface provided by the Common Service Locator project. For more information see the section "Initializing and Setting the Current Container" in the topic Creating and Referencing Enterprise Library Objects.
• Improved and more useful error messages during Resolve failures due to incorrect configuration.
• The configuration system now exposes a fluent interface that you can use to create and populate configuration sources for individual objects and for entire applications. The fluent API makes it easier to generate configuration sources for a variety of scenarios, including environment-specific configuration that can ease deployment. For more information, see Using the Fluent Configuration API.
• The ConfigurationView classes have been removed from Enterprise Library.
• Some configuration elements now have default values for their settings, which may differ from previous implicit defaults.
• Enterprise Library now enables you to create a composite configuration for Enterprise Library by merging settings from another configuration file.
• Enterprise Library now enables you to read the configuration information for specific Enterprise Library sections from different files. For more information, see Advanced Configuration Scenarios.
• Enterprise Library does not support XAML Browser Applications (XBAP).
• The WmiEnabled flag for instrumentation remains in the configuration for backward compatibility, but it is ignored in Enterprise Library 5.0 and will be removed in future releases.
• An Improved Installer allows you to choose the individual blocks and configuration tools to install. It also includes a merge module that you can integrate in your own MSIs to use to deploy Enterprise Library. Any libraries not installed initially can be installed later.
• When using Unity integration, in previous versions, you had to add the core Enterprise Library container extension and an extension per block. Now only the core extension is required, and only if you need to directly access the container. The individual blocks are automatically supported. The old extensions remain in the code solely for backwards compatibility. They now have no function.
• The signature for the FileConfigurationSource.Save method has changed. The method now has two parameters instead of three.
• The QuickStart examples are no longer included in the main installation. Instead, you can download an improved and extended set of examples and Hands-On Labs for Enterprise Library 5.0 from the Enterprise Library community Web site.

Changes to the Configuration Tools

The following changes have been made to this version of the Configuration tools:

• New Enterprise Library configuration tool with a new GUI and a metadata-driven extensibility model. See Using the Configuration Tools.
• Support for wizards in the Enterprise Library configuration tool.
• New type selector.****See Using the Configuration Tools.
• The Enterprise Library installer automatically detects the version of Visual Studio installed, enabling you to choose to integrate the configuration tool into the installation of Visual Studio 2008 or Visual Studio 2010. Side-by-side installation of the integrated configuration tool with Enterprise Library 4.1 is supported.
• The Enterprise Library 5.0 Configuration tool does not support Environmental Overrides for the Policy Injection Application Block logging handler Categories. You cannot use the configuration tool at design time to customize the run-time settings of your Policy Injection Application Block configuration for logging handler Categories based on the environment.
• The mechanism that supports integration of custom providers with full design-time configuration support has changed. For more information, see Creating Custom Providers for Enterprise Library.
• In Enterprise Library 5.0, assembly resolution is performed only if the Enterprise Library 5.0 editor is opened in Visual Studio. This improves assembly load handler performance.

Changes to the Caching Application Block

The following changes have been made to this version of the Caching Application Block:

• Cache scavenging has been completely rewritten for performance optimization.

Changes to the Cryptography Application Block

There are no changes in this version of the Cryptography Application Block.

Changes to the Data Access Application Block

The following changes have been made to this version of the Data Access Application Block:

• The block now contains asynchronous versions of the ExecuteReader, ExecuteXmlReader, ExecuteScalar, and ExecuteNonQuery methods. These use the familiar asynchronous approach of a Begin and End method for each one. For more details, see Using the Asynchronous Data Access Methods.
• The block contains a series of new methods and classes that allow you to extract data as sequences of objects, in a format suitable for client-side querying using techniques such as Language Integrated Query (LINQ). For more details, see Returning Data as Objects for Client Side Querying.
• The existing ExecuteReader method and the new BeginExecuteReader method do not accept a CommandBehavior parameter. By default, the methods will automatically set the CommandBehavior property on the underlying reader to CloseConnection unless you specify a transaction when you call the method. If you do specify a transaction, the methods do not set the CommandBehavior property.

Changes to the Exception Handling Application Block

The following changes have been made to this version of the Exception Handling Application Block:

• The Logging Exception Handler reuses the Log Writer and Trace Listeners from the Logging application block. This was not the default behavior in previous versions, though it could be achieved by setting the UseDefaultLogger property of the LoggingExceptionHandlerData class. This property still exists but is now obsolete.
• Added the capability to accept a default value and return a value from the ExceptionManager.Process method.

Changes to the Logging Application Block

The following changes have been made to this version of the Logging Application Block:

• The Rolling Flat File Trace Listener now has an additional property that enables you to specify the number of log files to keep, and can automatically purge older files based on this setting. For more details, see Trace Listener Properties.
• The TextFormatter class now supports additional template formatting tokens that provide improved performance when accessing local environment variables such as the machine and process names, and when formatting dates and times. The default template now uses the new local versions of the tokens. This offers additional performance improvements of the Logging Application Block. If, however, you require the previous behavior (such as when using the log distributor), you must update the default template for any new formatters that you add to the block. For more details, see Configuring Formatters.
• In previous releases, the XML Trace Listener did not generate any instrumentation information. In this release, the XML trace listener generates the same events and performance counter updates as the other trace listeners. For more details, see Deployment and Operations.
• Authentication has been added to EmailTraceListener class. For more details see the "Trace Listeners" section in the Design of the Logging Application Block topic.
• The primary interface for creating log entries in this release is the LogWriter class, which can be injected into your own objects using dependency injection. However, you can still use the Logger approach and the previous static facade, if required.
• The LogWriter class is now abstract. If your code previously created LogWriter objects directly, you must now either go through the container or use the LogWriterImpl class instead.
• The parameters of the constructor of the DistributorEventLogger class now define an EventSource object, which better illustrates how the class is used. The EventLogName property has been removed.

Changes to the Policy Injection Application Block

The following changes have been made to this version of the Policy Injection Application Block:

• The interception mechanism has been moved into the Unity Application Block, and all except one of the call handlers has been moved to the associated application block. As a result, the current Policy Injection Application Block is now comprised mainly of legacy components for backwards compatibility. The five call handlers you can use, and their assemblies and namespaces are:
  • Authorization handler
    • Assembly: Microsoft.Practices.EnterpriseLibrary.Security.dll
    • Namespace: Microsoft.Practices.EnterpriseLibrary.Security.PolicyInjection
  • Exception Handling handler
    • Assembly: Microsoft.Practices.EnterpriseLibrary.ExceptionHandling.dll
    • Namespace: Microsoft.Practices.EnterpriseLibrary.ExceptionHandling.PolicyInjection
  • Logging handler
    • Assembly: Microsoft.Practices.EnterpriseLibrary.Logging.dll
    • Namespace: Microsoft.Practices.EnterpriseLibrary.Logging.PolicyInjection
  • Validation handler
    • Assembly: Microsoft.Practices.EnterpriseLibrary.Validation.dll
    • Namespace: Microsoft.Practices.EnterpriseLibrary.Validation.PolicyInjection
  • Performance Counter handler
    • Assembly: Microsoft.Practices.EnterpriseLibrary.PolicyInjection.dll
    • Namespace: Microsoft.Practices.EnterpriseLibrary.PolicyInjection.CallHandlers
  • For more details, see The Policy Injection Application Block and Using Interception and Policy Injection.
• If you use the legacy static PolicyInjection facade, you can no longer specify the configuration source when you call the Create or Wrap methods. You can create, and later dispose, a PolicyInjector object by invoking its constructor with the desired configuration source. However, resolving such an injector from a Unity container will fail since it has two one-argument constructors.
• Providers are resolved from the same container from which the handlers themselves are resolved. This means that you cannot store configuration for the block in a separate file when using the default configuration for Enterprise Library.
• Call handlers are now created per object. They are no longer shared across all methods that use it. Handlers can now safely store the local state.
• Policy injection is now just one implementation of many possible interception implementations.

Changes to the Security Application Block

There are no changes in this version of the Security Application Block.

Changes to the Validation Application Block

The following changes have been made to this version of the Validation Application Block:

• Support for .NET Framework System.ComponentModel.DataAnnotations data annotation attributes has been added to the block, and the validators can be used anywhere you would use a Data Annotation attribute. For more information see Using Data Annotation Attributes.

• A validation-specific Unity extension allows you to use Unity to resolve validators. In addition, you can now configure the validation target and rule sets in a Unity configuration file.

• You can now use the Validation Application Block in Windows® Presentation Foundation (WPF) applications using the new integration features.

• You can now apply validation attributes to LINQ objects.

• The ValidatorWrapper class has been removed. This was an internal class used mainly to add instrumentation to validators. It is replaced by the GenericValidatorWrapper<T> class, which can wrap any type of validator.

• DataErrorInfoHelper class is added for implementing the System.ComponentModel.IDataErrorInfo interface using the Validation Application Block.

• The existing validators and facades have been updated to support inheritance. The changes include the following:

  • Updated the static validation facade to validate based on the validation target's type.

  • Updated the IValidatorDescriptor to get a ValidatorFactory when building the represented validator.

  • Updated the ObjectValidator and ObjectCollectionValidator to have an inheritance-aware flag, with false as the default value, and to be configured with ValidatorFactory. Should the validator be inheritance aware, the nested objects would be validated with a freshly built validator for the nested object's type; otherwise, a validator for the static type would be used. Nested object's validators are built with the ValidatorFactory so rules for the outer and the inner validators are retrieved from the same sources.

    Note

    When specifying the object collection validator (either through attributes or configuration), you would either set the target type or the "validate actual type" to true.

• You must use ValueValidatorAttribute as the base class for custom validators instead of ValidatorAttribute. If you derive a custom validator from ValidatorAttribute instead of ValueValidatorAttribute it may fail when used for validation of Data Annotations.