Announcing the Policy Injection Application Block

  • Article

Just when you thought you knew everything there was to know about Enterprise Library 3.0, we have one last surprise in store: a new application block! The Policy Injection Application Block got off to a late start, but we're making good progress now and we'll ship the first public drop in the February 2007 CTP. The final release of Enterprise Library 3.0 (scheduled for late March) will of course contain the final release.

But first things first: what the hell is this thing? The short(ish) answer is that the Policy Injection Application Block will simplify the separation of business logic from cross cutting concerns, by letting you define policies and the objects/methods they apply to in a declarative way. Each policy contains a pipeline of "handlers" that are executed before and after a policy-enabled method is called. The handlers can do whatever you want, but the most common scenario will be to implement cross-cutting concerns such as logging, validation, exception handling and authorization. By amazing coincidence, Enterprise Library already includes blocks that implement these kinds of capabilities, so our out-of-the-box handlers will be simple wrappers over existing application blocks.

For a detailed description of the design and the rationale behind it, check out Ed Jezierski's post - but to get you started, here are a few more details on how this will work. The Policy Injection Application Block will provide a special Factory class that you can use to create instances of objects that may potentially have policies defined on them. I say potentially as one of the big benefits of this block is that you can define and change the policies through configuration, so you won't actually know at compile time which objects will have policies defined. The factory will inspect the configuration and determine if a policy exists. If no such policy exists, the factory will create an instance of the requested object and return it. If a policy does exist, the factory will create a proxy (technically a transparent proxy / real proxy pair) for the object, and wire this up to the chain of handlers and ultimately the real object. To the client, the proxy looks and smells exactly like the real object, but it will have the policies injected between the proxy and the real object.

The configuration for the block will look something like this:

  • Policy Injection Application Block
    • MyPolicy1
      • Matching Rules
        • MyMatchingRule1
        • MyMatchingRule2
        • ...
      • Handlers
        • MyHandler1
        • MyHandler2
        • ...
    • MyPolicy2
      • ...
    • ...

As you can see, each policy consists of a collection of matching rules and a collection of handlers. A matching rule is basically a predicate that defines which types and members the policy should apply to. If you specify more than one matching rule, all must apply for a policy to take effect. Out of the box we will ship matching rules that check for a specific assembly, namespace, type, method signature, or specific attributes on type or member definitions. Of course you'll also be able to write your own matching rules, should you want a policy to apply only when the moon is full or something similarly obscure. In the event that a particular class/method matches more than one policy, all of the matching policies will be executed in the order that they are defined.

Handlers are the classes that do the interesting work before and/or after a method is called. A handler is able to inspect the payload of the method call or return value, act on it, and even change it. In normal situations each handler will do its preprocessing work, invoke the next handler, wait for the call to return, do postprocessing work, and return control to the previous handler. However in certain situations a handler may decide not to call the next handler at all. One good example is an Authorization Handler. Its job is to check whether the current user is authorized to call the method. If the check shows the user is good to go, the handler will invoke the next handler in the chain. However if the user is not authorized, the handler will create an exception, package it up and send it back to the previous handler in the chain as shown below:

From the client's perspective, the result will appear identical to what would happen if the target object threw the exception itself, although in this case the exception was generated without ever calling the real object.

As I mentioned before, the handlers we will supply out of the box will be thin wrappers around existing application blocks, although again you can easily create your own. While the number of handlers and the details on how they will work are not entirely set in concrete, here is what we are hoping to include:

  • Validation Handler. This will look for validation rules applied on the method parameters or within types in the message signature, and call the Validation Application Block to check the supplied parameters against the validation rules. If validation succeeds the method will be called. If not, the handler chain will be aborted and an exception will be returned to the client.
  • Logging Handler. This will call the Logging Application Block to write a log message either before the method is called, after the method is called, or both. Optionally the handler will be able to log details such as supplied parameter values and call execution time.
  • Exception Handling Handler. This handler will do nothing before the method is called, and do nothing after the method is called unless an exception was thrown. If an exception was thrown, the handler will pass it to the Exception Handling Application Block using a specified exception policy, and any resulting exceptions will be returned to the client. In effect this will eliminate the need for boilerplate exception blocks when using the Exception Handling Application Block.
  • Performance Counter Handler. This will create a number of performance counter instances measuring things like number of calls, calls per second, average call execution time and number and rate of exceptions thrown by the target method.
  • Authorization Handler. This handler will use a specified authorization provider configured with the Security Application Block to check if the current user (obtained from the thread principal) is authorized to perform the current task (specified in the handler configuration). If so, the target object is called. If not, an exception will be returned to the client.
  • Caching Handler. This handler will generate a cache key based on the target method signature and values, and use the Caching Application Block to see if the method has already been called with these values within the configured cache threshold. If a value was found in the cache, it will be returned to the client and the handler chain will be aborted (i.e. the object will not actually be called). If a value was not found in the cache, the method will be called, and the return value will be added to the cache on the return path.

We're very excited by the potential for this block to help simplify your code and provide increased flexibility to change cross-cutting concerns at different stages of the application lifecycle. Keep in mind that the first drop of the Policy Injection Application Block (in the February 2007 CTP) will still be incomplete, but we'd love to hear your feedback to help us make the final release as valuable as possible.

By the way, if you're not the kind of person who likes surprises, apologies for springing this on you so late. It wasn't our intention to be secretive, however until very recently we were still not sure if we were going to be able to include this functionality in this release of Enterprise Library, so we didn't want to set expectations too early. Hopefully it was worth the wait, and that you can file it under "good surprises" :-)

Thanks to Alex Homer for the great graphics, which were taken from the draft documentation.