Using the Policy Injection Application Block
The Policy Injection Application Block includes:
- A set of handlers for common Enterprise Library-related tasks
- A set of attributes that apply these handlers to classes and class members
- A set of matching rules thatwhen defined within a configuration policyselect the target classes and class members to which the block will apply the handlers
To use the configuration system to specify handlers for classes and class members, you define one or more policies using the Enterprise Library configuration tools. Each policy consists of a series of matching rules and a series of handlers. The matching rules select target classes and members; the block ANDs
together the results within each policy. This provides a comprehensive range of options for selecting the target classes and members to which you want to apply handlers. For each class or member selected by the matching rules, the block then generates a handler pipeline containing the configured set of handlers for the selected classes and members.
The block performs the selection and generates the pipelines at start-up and caches them to reduce processing overheads. Subsequently, it injects pipelines only into the selected membersnot into all the members of selected classes. Together with several other internal optimizations, this helps to minimize the extra overheads that most AOP and policy injection technologies incur.
Creating and Wrapping Target Objects
To allow the Policy Injection Application Block to inject handler pipelines into method and property calls, developers must use a specific technique when creating object instances. The block exposes two methods that generate a suitable proxy between the application and the target object. The PolicyInjection factory class provides the Create method to create new object instances from classes, and the Wrap method to apply policies to existing object instances.
Both of these are intelligent, in that they create a proxy to the target object only if there is at least one policy or handler to apply (at least one set of policy matching rules selects the target object, or a member carries a policy injection attribute). If there are no policies for the object, and no attributes on its members, the methods simply return the target object. The only overhead is the check through the cached configuration data and a scan for attributes on the members of the target class.
As long as the application creates instances of target objects using the Create method, or obtains references to existing instances using the Wrap method, the Policy Injection Application Block can apply the specified handlers. In particular, this approach allows administrators and operators to add new policies to existing objects simply by configuring suitable matching rules and handlers within these policies, without requiring any additional intervention from the developer or requiring recompilation and redeployment of the target objects, which avoids testing, versioning, and management issues.
There are some limitations with the Policy Injection Application Block, however, and it is important to consider these when planning to use it:
The Built-in Matching Rules and Handlers
- Target objects must either inherit from the MarshalByRefObject base class, or implement a known interface. The interface can be a custom interface created especially for the target object, as long as it declares all the methods and properties for which policy injection is required.
- Policy injection can only take place for public members of the target class.
- Matching rules can only select objects based on static information, because the selection process takes place only at application start-up.
- Call handlers only have access to the information within the call message, and cannot maintain internal state.
Before looking at how you can use the Policy Injection Application Block in ASP.NET applications, this section provides a brief overview of the default matching rules and handlers available within the block.
The Policy Injection Application Block provides the following set of built-in matching rules for selecting classes, and members within these classes, to which it will apply a handler pipeline:
- The AssemblyMatchingRule, which selects all the classes in a specified assembly.
- The CustomAttributeMatchingRule, which selects classes or members decorated with an arbitrary custom attribute.
- The MemberNameMatchingRule, which selects class members with one of a set of specified names.
- The MethodSignatureMatchingRule, which selects class methods that have a specified signature.
- The NamespaceMatchingRule, which selects classes in one of the specified namespaces.
- The ParameterTypeMatchingRule, which selects class methods with a parameter name and type, or return value, that matches one of the specified types.
- The PropertyMatchingRule, which selects class properties based on a set of specified names and containing the specified combination of Get and Set accessors.
- The ReturnTypeMatchingRule, which selects class members that return an object of the specified type.
- The TagAttributeMatchingRule, which selects class members decorated with a Tag attribute with a specified string.
- The TypeMatchingRule, which selects classes of a specified type.
The Policy Injection Application Block provides the following set of built-in handlers that you can add to a handler pipeline, using both the application configuration or directly applied attributes within the target class:
Policy Configuration Tools
- The Authorization Handler, which checks that the current thread identity (user) has permission to access the target class member based on a set of rules defined within configuration for the Security Application Block.
- The Caching Handler, which uses the built-in ASP.NET caching mechanism to cache the return values from properties and methods of the target object.
- The Exception Handling Handler, which uses an exception handling policy defined within the configuration of the Exception Handling Application Block to wrap or replace exceptions generated by code in the target object.
- The Logging Handler, which filters, formats, and writes details of calls to target class members to the configured output (such as Windows Event Log, log files, and message queue systems).
- The Performance Counters Handler, which updates a series of Windows performance counters each time the application makes a call to the members of the target object.
- The Validation Handler, which validates values passed as parameters to target objects, based on either configuration of the Validation Application Block or validation attributes applied directly to parameters of the target members.
If you apply policies using configuration, rather than through directly applied attributes, you can use one of the two configuration tools provided with Enterprise Library 3.0. The stand-alone Configuration Console allows you to create new configuration files and open existing ones, and then edit the contents before saving the file into the required location. The Enterprise Library section of your Start menu contains a link to open the Configuration Console.
|Figure 1. The Enterprise Library Configuration Editors: The stand-alone Configuration Console (top) and the Visual Studio Configuration Editor (bottom) provide identical hierarchical views of configuration settings.|
Alternatively, if you are using Visual Studio 2005 to create your application, you can use the Configuration Editor that Enterprise Library installs automatically. Simply right-click your existing application configuration file in Visual Studio's Solution Explorer window and click "Edit Enterprise Library Configuration."
Both editors work the same way, and provide an identical hierarchical view of the configuration settings. In the stand-alone Configuration Console, you edit the values for each node using the list of properties displayed in the right-hand window as you select each node. In the Visual Studio Configuration Editor, you edit the properties in the normal Visual Studio Properties window (see Figure 1).
Configuring an Application to use Policy Injection
To use Policy Injection, you must add the Policy Injection Application Block to your application configuration, even if you intend to directly apply attributes to configure handler pipelines for your target objects. In addition, if your attributes specify exception handling, logging, authorization, or a configured validation scheme, you must add the appropriate application blocks to the configuration as well as configuring the required settings in these blocks.
Also, bear in mind that, if you intend to run your ASP.NET application in partial trust mode, you must set the RequirePermission property for each block to False (the default is True). This prevents the blocks from demanding all the permissions they may use when they first load. If you subsequently use a feature of a block that requires permissions not available in your chosen partial trust mode (such as access to the file system or Windows Event Log), you can configure the relevant permissions for just the required features.
|Author's Note: For more details of running ASP.NET applications that use Enterprise Library in partial trust mode, see this article.