Appendix F: patterns & practices Enterprise Library

For more details of the topics covered in this guide, see Contents of the Guide.

Contents

• Overview
• Goals of Enterprise Library
• What's Included in Enterprise Library
• Caching Application Block
• Cryptography Application Block
• Data Access Application Block
• Exception Handling Application Block
• Logging Application Block
• Policy Injection Application Block
• Security Application Block
• Unity Application Block
• Validation Application Block
• Additional Resources

Overview

This appendix describes the patterns & practice Enterprise Library, and explains how you can use it in your applications to quickly and simply implement crosscutting concerns such as logging, exception handling, and data access.

Goals of Enterprise Library

The goals of Enterprise Library are the following:

• Consistency. All Enterprise Library application blocks feature consistent design patterns and implementation approaches.
• Extensibility. All application blocks include defined extensibility points that allow developers to customize the behavior of the application blocks by adding their own code.
• Ease of use. Enterprise Library offers numerous useful features that include a graphical configuration tool, a simple installation procedure, and clear and complete documentation and samples.
• Integration. Enterprise Library application blocks are designed to work well together and are tested to make sure that they do. It is also possible to use the application blocks individually.

What's Included in Enterprise Library

Enterprise Library contains:

• Application blocks that consist of reusable code you can use to implement solutions for crosscutting concerns such as logging, exception handling, validation, and data access.
• Configuration tools that make it easy to add Enterprise Library blocks to an application and specify configuration information. The configuration tools include a stand-alone configuration editor and a configuration tool that integrates with Visual Studio.
• Common utility functions for tasks such as serialization, used in many places throughout the library and the application blocks and available for developers to use in their code.
• Instrumentation features that allow developers and administrators to monitor the behavior and performance of the application blocks at run time.
• Batch files that build the Enterprise Library source code and copy the assemblies to the appropriate locations.
• Utilities to install the events and performance counter instrumentation exposed by Enterprise Library.
• Utilities to create the sample databases used by the Enterprise Library examples and QuickStarts.
• A full set of QuickStart applications, one for each application block, which demonstrate how you can use the application blocks. They implement common scenarios from each application block and provide links to the relevant sections of the guidance documentation.
• Full source code for Enterprise Library, including Visual Studio projects and unit tests that developers can use to extend and modify the library and the application blocks. Developers make sure applications still meet the design requirements by running the unit tests and writing new tests.

Application Blocks

The following table lists and describes the application blocks designed to assist developers solve common enterprise development challenges.

Caching Application Block

The Caching Application Block lets you incorporate a local cache in your applications that uses an in-memory cache and, optionally, a database or isolated storage backing store. The block provides all the functionality needed to retrieve, add, and remove cached data, and supports configurable expiration and scavenging policies. You can also extend it by creating your own pluggable providers or using third party providers; for example to support distributed caching and other features. Caching can give considerable improvements in performance and efficiency in many application scenarios.

Key Scenarios

The Caching Application Block is suitable if you encounter any of the following situations:

• Repeatedly accessing static data or data that rarely changes.
• Performing data access that is expensive in terms of creation, access, or transportation.
• Working with data must always be available, even when the source, such as a server, is not available.

When to Use

The Caching Application Block is optimized for high performance and scalability. Furthermore, it is both thread safe and exception safe. You can extend it to include your own expiration policies and your own backing store. It is designed to work in the most common data caching situation, which is when the application and the cache exist on the same system. This means that the cache is local and should be used only by that application. When it operates within these guidelines, the application block is ideal for addressing the following requirements:

• You need a consistent and simple interface and implementation for cache functionality across different application environment, which does not change irrespective of the caching store being used. For example, developers can write similar code to implement caching in application components hosted in Internet Information Services (IIS), Enterprise Services, and smart client environments. Also, the same cache configuration options exist for all environments.
• You need a configurable and persistent backing store. The block supports both isolated storage and database backing stores. Developers can create additional backing store providers and add them to the block using its configuration settings. The application block can also symmetrically encrypt a cache item's data before it is persisted to a backing store.
• Changes to the cache configuration settings must not require application source code changes. Developers first write the code that uses one or more named caches. System operators and developers can then configure each of these named caches differently using the Enterprise Library configuration tools.
• Cache items require any of the following expiration settings: absolute time, sliding time, extended time format (for example, every evening at midnight), file dependency, or never expired.
• You want to modify the block source code for extensibility or customization.
• You need to use multiple types of cache store (through different cache managers) in a single application.

You can use the Caching Application Block with any of the following application types:

• Windows Forms.
• Console application.
• Windows service.
• COM+ server.
• ASP.NET Web application or Web service if you need features not included in the ASP.NET cache.

Considerations

The following considerations apply to using the Caching Application Block:

• You should deploy the block within a single application domain. Each application domain can have one or multiple cache stores, either with or without backing stores.
• Cache stores cannot be shared among different application domains.
• Although you can encrypt data cached in the backing stores, the block does not support encryption of data that is cached in memory.
• The block does not support tamper proofing (signing and verifying items in the cache).

Cryptography Application Block

The Cryptography Application Block makes it easy to incorporate cryptographic functionality such as encrypting information, creating a hash from data, and comparing hash values to verify that data has not been altered.

Key Scenarios

The Cryptography Application Block is suitable if you encounter any of the following situations:

• Quickly and easily encrypting and decrypting information.
• Quickly and easily creating a hash from data.
• Comparing hash values to verify that data has not been altered.

When to Use

The Cryptography Application Block is ideal for addressing the following requirements:

• You need to reduce the requirement to write boilerplate code to perform standard data encryption, decryption, and hashing tasks.
• You need to maintain consistent cryptography practices, both within an application and across the enterprise.
• You need to simplify learning for developers by using a consistent architectural security model across the various areas of functionality.
• You need to add or extend implementations of cryptography providers.
• You need a customizable Key Protection Model.

Considerations

The following considerations apply to using the Cryptography Application Block:

• The block supports only symmetric algorithms that use the same key for both encryption and decryption.
• The block does not automatically manage encryption keys and key storage.

Data Access Application Block

The Data Access Application Block simplifies many common data access tasks such as reading data for display, passing data through application layers, and submitting changed data back to the database system. It includes support for both stored procedures and in-line SQL, and provides access to the most often used features of ADO.NET in simple-to-use classes.

Key Scenarios

The Data Access Application Block is suitable if you encounter any of the following situations:

• Using a DataReader or DataSet to retrieve multiple rows of data.
• Executing a command and retrieve the output parameters or a single-value item.
• Performing multiple operations within a transaction.
• Retrieving XML data from a SQL Server.
• Updating a database with data contained in a DataSet object.
• Adding or extend implementations of database providers.

When to Use

The Data Access Application Block is ideal for addressing the following requirements:

• You need simplicity and convenience while helping developers use the functionality provided by ADO.NET with best practices.
• You need to reduce the requirement for boilerplate code to perform standard data access tasks.
• You need to maintain consistent data access practices, both within an application and across the enterprise.
• You need to make it easy to change the target database type through configuration, and reduce the amount of code that developers must write when they port applications to different types of databases.
• You need to relieve developers from learning different programming models for different types of databases.

Considerations

The following considerations apply to using the Data Access Application Block:

• The Data Access Application Block is a complement to ADO.NET; it is not a replacement. If your application must retrieve data in a specialized way, or take advantage of features specific to a particular database, consider using ADO.NET directly.

Exception Handling Application Block

The Exception Handling Application Block lets you quickly and easily design and implement a consistent strategy for processing exceptions that occur in all architectural layers of your application. It can log exception information, hide sensitive information by replacing the original exception with another exception, and maintain contextual information for an exception by wrapping the original exception inside another exception.

Key Scenarios

The Exception Handling Application Block allows developers to encapsulate the logic contained in catch statements in application components as reusable exception handlers. It is suitable if you encounter any of the following requirements:

• Wrapping an exception. Use the Wrap handler to wrap an exception with a new exception.
• Replacing an exception. Use the Replace handler to replace one exception with another.
• Logging an exception. Use the Logging handler to format exception information, such as the message and the stack trace, and pass it to the Enterprise Library Logging Application Block so that it can be published.
• Shielding an exception at a WCF service boundary. Use the Fault Contract Exception handler, which is designed for use at Windows Communication Foundation (WCF) service boundaries, to generate a new Fault Contract from the exception.
• Propagating an exception, displaying user friendly messages, notifying the user, and assisting support staff. Use a combination of handlers from the block to handle specific exception types and rethrow them if required.
• Localization of exception messages. Use the handlers and their configuration to specify localized message text for exceptions.

When to Use

The Exception Handling Application Block is ideal for addressing the following requirements:

• You must support exception handling in all architectural layers of an application, not just at service interface boundaries.
• You need exception handling policies to be defined and maintained at the administrative level through configuration, and the ability to maintain and modify the rules that govern exception handling without changing the application block code.
• You need to provide commonly used exception handling functions, such as the ability to log exception information, the ability to hide sensitive information by replacing the original exception with another exception, and the ability to maintain contextual information for an exception by wrapping the original exception inside another exception.
• You need to combine exception handlers to produce the desired response to an exception, such as logging exception information followed by replacing the original exception with another.
• You need to invoke exception handlers in a consistent manner so that you can handlers can use them in multiple places within and across applications.
• You need to add or extend implementations of exception handlers.
• You need to handle exceptions via policies as opposed to simply logging them.

Logging Application Block

The Logging Application Block simplifies the implementation of common logging functions such as writing information to the Windows Event Log, an email message, a database, Windows Message Queuing, a text file, a WMI event, or a custom location.

Key Scenarios

The Logging Application Block is suitable if you encounter any of the following situations:

• Populating and logging event information to Windows Event log, an e-mail message, a database, a message queue, a text file, a Windows Management Instrumentation (WMI) event, or a custom location.
• Modifying and formatting context information within the event using templates.
• Tracing application activities and providing identities that can be used to combine event information.
• Preventing unauthorized access to sensitive information using access control lists (ACLs) to restrict access to flat files, or creating a custom formatter that encrypts log information.

When to Use

The Logging Application Block is ideal for addressing the following requirements:

• You must maintain consistent logging practices, both within an application and across the enterprise.
• You need to ease the learning curve for developers by using a consistent architectural model.
• You need to provide implementations that you can use to solve common application logging tasks without repeatedly writing custom or boilerplate code.
• You need to add or extend logging implementations and targets.

Considerations

The following considerations apply to using the Logging Application Block:

• The block logging formatters do not encrypt logging information.
• Trace listener destinations receive logging information as cleartext.
• Some of the Logging Application Block listeners fail while running under partial trust.

Policy Injection Application Block

The Policy Injection Application Block provides a mechanism for automatically applying policies to object instances; this helps developers to better manage crosscutting concerns, maximize separation of concerns, and encapsulate behavior. Developers define the set of policies for the target classes and their members through configuration of the Policy Injection Application Block or by applying attributes to individual members of the target class.

Key Scenarios

The Policy Injection Application Block is suitable if you encounter any of the following situations:

• Building applications from objects that require encapsulation and separation to provide the most benefit from independence in operation, and provide the maximum capability for reuse.
• Allowing developers, operators, and administrators to create, modify, remove, and fine tune interception policies though configuration, generally without requiring any changes to the code or recompilation of the application. This reduces the chance of introducing errors into the code, simplifies versioning, and reduces downtime.
• Reusing existing object instances. This reduces the requirement for code to generate new object instances and prepare them by setting properties or calling methods, while still allowing handler pipelines to be used for specific members or all members of that class.
• Minimizing the work required and the code that the developer must write to perform common tasks within an application, such as logging, validation, authorization, and instrumentation.

When to Use

The Policy Injection Application Block is ideal for addressing the following requirements:

• You need a ready-built solution that is easy to implement in new and existing applications, particularly in applications that already take advantage of the features of the Enterprise Library.
• You need to manage crosscutting concerns that may otherwise affect the independence of objects that require access to common features (such as logging or validation).
• You need to allow the developer and administrator to configure the behavior of objects in an application through configuration, by adding or removing handlers that execute common tasks or add custom features.
• You need to make it easy for developers to take advantage of features within the Enterprise Library Core and individual application blocks that implement tasks commonly required in enterprise applications.
• You need to reduce development time and cost, and minimize bugs in complex applications that use common and shared tasks and services.

Considerations

The following considerations apply to using the Policy Injection Application Block:

• It uses interception to enable only preprocessing handlers and post-processing handlers, rather than inserting code directly into methods.
• It does not provide interception for class constructors.
• Like all interception technologies, it imposes some extra processing requirements on applications—although the design of the block minimizes these as much as possible.
• Call handlers only have access to the information within the call message, and cannot maintain internal state.
• Policy injection can only take place for public members of the target class.

Security Application Block

The Security Application Block lets you easily implement common authorization-related functionality, such as caching user's authorization and authentication data and integrating with the Microsoft .NET Framework security features.

Key Scenarios

The Security Application Block is suitable if you encounter any of the following situations:

• Caching security-related credentials that you use to perform authorization.
• Obtaining a temporary token for an authenticated user, and authenticating a user using a token.
• Terminating a user session (expire the token).
• Determining whether a user is authorized to perform a task.

When to Use

The Security Application Block is ideal for addressing the following requirements:

• You must reduce the requirement for boilerplate code to perform standard security-related tasks such as caching credentials, and checking authentication.
• You must maintain consistent security practices, both within an application and across the enterprise.
• You want to ease the learning curve for developers by using a consistent architectural model across the various areas of functionality provided.
• You need to use custom implementations of security providers.

Considerations

The following considerations apply to using the Security Application Block:

• The default store for cached security-related information is the Caching Application Block. Although the Caching Application Block can be configured to encrypt cache data in backing stores, the application block does not support encryption of cache data stored in memory. If this threat is significant for your application, you can use an alternate custom caching store provider that supports in-memory encryption.
• The authorization manager is not supported under partial trust.

Unity Application Block

Unity is a lightweight, extensible dependency injection container that supports object interception, constructor injection, property injection, and method call injection. You can also use it with Enterprise Library to generate both Enterprise Library objects and your own custom business objects.

Key Scenarios

The Unity Application Block is suitable if you encounter any of the following situations:

• Performing dependency injection through a container that supports constructor, property, and method call injection, and can manage the lifetime of object instances.
• Performing dependency injection for classes that have dependencies on other objects or classes, and these dependencies are complex or require abstraction.
• Configuring and changing the dependencies at run time.
• Caching or persisting the container across post backs in a Web application.

When to Use

The Unity Application Block is ideal for addressing the following requirements:

• You need simplified object creation, especially for hierarchical object structures and dependencies, which simplifies application code.
• You need to abstract requirements by specifying dependencies at run time or in configuration to simplify management of crosscutting concerns.
• You need to increase flexibility by deferring component configuration to the container.
• You need a service location capability where clients can store or cache the container. This is especially useful in ASP.NET Web applications where the developers can persist the container in the ASP.NET session or application.

You should not use the Unity Application Block in the following situations:

• Your objects and classes have no dependencies on other objects or classes, or your dependencies are very simple and do not require abstraction.

Considerations

The following considerations apply to using the Unity Application Block:

• Dependency injection may have a minor impact on performance.
• Dependency injection can increase complexity where only simple dependencies exist.

Validation Application Block

The Validation Application Block provides a range of features for implementing structured and easy-to-maintain validation mechanisms using attributes and rule sets, and integrating with most types of application interface technologies.

Key Scenarios

The Validation Application Block is suitable if you encounter any of the following situations:

• Implementing structured and easy to maintain validation code to validate fields, properties, and nested objects, and prevent the injection of malicious data into your application.
• Enforcing business rules and to providing responses to user input.
• Validating data several times within the same application using the same rules.
• Combining the wide range of prebuilt validators to support complex scenarios and a wide range of capabilities.

When to Use

The Validation Application Block is ideal for addressing the following requirements:

• You need to maintain consistent validation practices for almost all standard .NET data types in ASP.NET, Windows Forms, and WCF applications.
• You need to create validation rules using configuration, attributes, and code.
• You need to associate multiple rule sets with the same class and with members of that class.
• You need to apply one or more rule sets when you validate an object, and reuse business validation logic.

Considerations

The following considerations apply to using the Validation Application Block:

• Some technologies such as ASP.NET and Windows Forms provide built-in validation features. Therefore, if your validation logic only needs to be applied within these technologies you may not need to use the application block unless you need to reuse the validation logic.
• WCF and other applications that use XML data can use XML Schemas to validate messages at the XML level. If your validation logic only needs to be applied within these technologies you may not need to use the application block unless you need to reuse the validation logic.
• In very simple cases, when you only need to validate a few objects, you may not want to incur the overhead of adding the application block.

Additional Resources

For more information, see the following resources:

• "Enterprise Library" at https://msdn.microsoft.com/en-us/library/cc467894.aspx.
• "The Caching Application Block" at https://msdn.microsoft.com/en-us/library/cc511588.aspx.
• "The Cryptography Application Block" at https://msdn.microsoft.com/en-us/library/cc511721.aspx.
• "The Data Access Application Block" at https://msdn.microsoft.com/en-us/library/cc511547.aspx.
• "The Exception Handling Application Block" at https://msdn.microsoft.com/en-us/library/aa480461.aspx.
• "The Logging Application Block" at https://msdn.microsoft.com/en-us/library/cc511708.aspx.
• "The Policy Injection Application Block" at https://msdn.microsoft.com/en-us/library/cc511729.aspx.
• "The Security Application Block" at https://msdn.microsoft.com/en-us/library/cc511928.aspx.

• "The Unity Application Block" at https://msdn.microsoft.com/en-us/library/cc511654.aspx.

• "The Validation Application Block" at https://msdn.microsoft.com/en-us/library/cc511802.aspx.
• "Enterprise Library Frequently Asked Questions" at https://www.codeplex.com/entlib/Wiki/View.aspx?title=EntLib%20FAQ.