1. Introducing the Policy Injection Application Block
MGB 2003
Introducing the Policy Injection Application Block
© 2003 Microsoft Corporation. All rights reserved.
This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.

2. Agenda Enterprise Library 3.0 Introduction
MGB 2003
Agenda
Enterprise Library 3.0 Introduction
Policy Injection Motivation and Goals
Policy Injection Application Block Architecture
Call Handlers and Matching Rules
Extending the PIAB
Summary
© 2003 Microsoft Corporation. All rights reserved.
This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.

3. Enterprise Library 3.0: New Features At a Glance
New application blocks
Validation Application Block
Policy Injection Application Block
Improvements to existing application blocks
Data Access Application Block
Logging Application Block
.NET Framework 3.0 integration
Logging, Exception Handling and Validation Application Blocks
Configuration improvements
Visual Studio-integrated configuration tool
Environmental Overrides
Manageable Configuration Source
Automation
Application Block Software Factory
Strong Naming Guidance Package

4. Enterprise Library 3.0 Application Blocks
Caching
Security
Data
Access
Logging
Exception
Handling
Config
Helpers
& Design
Instrumen- tation
Object Builder
Cryptography
Core
Policy Injection
Validation
First up is the configuration application block and configuration tool.

5. Agenda Enterprise Library 3.0 Introduction
MGB 2003
Agenda
Enterprise Library 3.0 Introduction
Policy Injection Motivations and Goals
Policy Injection Application Block Architecture
Matching Rules and Call Handlers
Extending the PIAB
Summary
© 2003 Microsoft Corporation. All rights reserved.
This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.

6. Context
Applications include a mix of business logic and cross cutting concerns
Cross cutting concerns include security, state management and operational
Authorization, logging, caching, transaction management, etc.
Both types of logic are necessary, but each have unique characteristics
Business logic is highly contextual and often not reusable
Cross cutting concerns are often applied consistently across layers and applications

7. Mixing Business and Cross-Cutting Concerns
Traditionally, business logic and cross-cutting concerns are mixed together in code
Even if a shared component or application block is used, it is still generally called from code
This can lead to
Code that is hard to read and maintain
Duplicated code
Inconsistent behavior

8. Sample Method Customer GetCustomerById(int id) {
if (id < 0) throw new ArgumentException("Invalid Customer Id");
Customer customer = HttpContext.Current.Cache.Get(id.ToString()) as Customer;
if (customer != null)
return customer;
try
Database db = DatabaseFactory.CreateDatabase("CRM");
using (IDataReader reader = db.ExecuteReader("spGetCustomerById", id))
if (reader.Read())
customer = new Customer(id, reader.GetString(0), reader.GetString(1));
HttpContext.Current.Cache.Add(id.ToString(), customer, null, DateTime.Now.AddMinutes(1), Cache.NoSlidingExpiration, CacheItemPriority.Normal, null); }
return null;
catch (Exception ex)
if (ExceptionPolicy.HandleException(ex, "Data Policy")) throw;

9. Policy Injection Application Block Goals
Separate cross-cutting concerns from business logic
Use interception and injection to apply policies at runtime
Allow policies to be defined declaratively, using configuration or attributes
At a coarse- or fine-grained level
Make it easy to integrate Enterprise Library application blocks into policies
Validation, Logging, Authorization, Exception Handling, Caching, Performance Counters
Design for loose-coupling and extensibility

10. Sample Method with Policy Injection
[ValidationCallHandler]
[CachingCallHandler(0, 1, 0)]
[Tag("Data Access")]
Customer GetCustomerById(
[RangeValidator(0, RangeBoundaryType.Inclusive, 0, RangeBoundaryType.Ignore)] int id) {
Database db = DatabaseFactory.CreateDatabase("CRM");
using (IDataReader reader = db.ExecuteReader("spGetCustomerById", id))
if (reader.Read())
return new Customer(id, reader.GetString(0), reader.GetString(1)); }

11. Agenda Enterprise Library 3.0 Introduction
MGB 2003
Agenda
Enterprise Library 3.0 Introduction
Policy Injection Motivation and Goals
Policy Injection Application Block Architecture
Call Handlers and Matching Rules
Extending the PIAB
Summary
© 2003 Microsoft Corporation. All rights reserved.
This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.

12. Policy Injection Application Block Basics
Policy Injection Application Block provides a factory for creating or wrapping policy-enabled objects
If policies are defined in attributes or configuration, a proxy is returned in lieu of the real object
When calling policy-enabled members, a handler pipeline is executed before and after the real member is called
Each handler can access the data going in and out of the call

13. Policy Injection Application Block Basics
Normally, each handler will implement a cross-cutting concern before passing control to the next handler (or the target)
A handler may also choose to abort the pipeline if deemed appropriate

14. Policies
The definition of which handlers should execute for which objects and methods is called a policy
There are two types of polices:
Configuration-based policies
Attribute-based policies

15. Configuration-based Policies
A configuration-based policy consists of
A set of matching rules
A pipeline of handlers
Matching rules are predicates that specify which members the policy should apply to
For example, everything in the GlobalBank.BusinessLogic namespace, or all members returning a BankAccount
Multiple matching rules are ANDed together
The handler pipeline specifies the ordered list of handlers that will execute if the matching rules pass
More than one policy may apply to any given member
They will be applied in the order specified in configuration

16. Attribute-based Policies
An attribute-based policy consists of a set of call handlers applied directly to objects and members using custom attributes
Matching rules are not used
Attributes are discovered first on types, then on members, and applied in order of discovery
Order of discovery of multiple attributes applied on the same element cannot be guaranteed
Attribute-based policies are always applied before configuration-based policies
[CachingCallHandler(0, 1, 0)]
[LogCallHandler(LogBeforeCall = true, LogAfterCall = false,
BeforeMessage = "About to call the method")]
public int DoSomething(string input) {
/// }

17. Disabling Policies
Both configuration- and attribute-based policies can be disabled for a given type or member
Use the [ApplyNoPolicies] attribute to prevent policies being applied
Useful for methods that are performance critical, need no cross-cutting concerns or implement concerns differently

18. Interception and Injection
In order for policies to execute when a method is called:
Configuration- or attribute-based policies must apply to the member
The instance must be created or wrapped using the PolicyInjection factory
The target object must be interceptable
Requirements depend on the chosen injection mechanism
Method must be called via the proxy returned from the PolicyInjection.Create/Wrap methods, not directly on the object

19. Creating or wrapping objects
Objects must be created or wrapped with the PolicyInjection class for policies to apply
Even if no policies apply now, you may want to create objects this way to allow policies to be added in the future
Performance impact is very low if no policies apply
MyClass1 object1 = PolicyInjection.Create<MyClass>();
MyClass2 object2 = PolicyInjection.Create<MyClass>(param1, param2);
IMyInterface object3 = PolicyInjection.Create<MyClass3, IMyInterface>();
MyClass1 object4 = new MyClass();
MyClass1 object4proxy = PolicyInjection.Wrap<MyClass1>(object4);
IMyInterface object5 = new MyClass3();
IMyInterface object5proxy = PolicyInjection.Wrap<IMyInterface>(object5);

20. Interception Requirements
The requirements for intercepting objects and members depends on the chosen injection strategy
The PIAB ships with a Remoting Proxy injection strategy
Can be replaced by alternative methods
The Remoting Proxy Injection requires:
The class derive from MarshalByRefObject, or
The class implement any interface, with intercepted calls made through that interface

21. Calling Policy Injected Members
Calling policy injected members is no different to calling any other member
The caller can’t even tell if policies exist or not
Policies do not alter the method signature
Although they may alter the behavior
Caller just calls a method and gets a return result or exception
Caller doesn’t know if result came from the method or a handler
BankAccount account = PolicyInjection.Create<BankAccount>(accountId);
try {
account.Withdraw(amount); }
catch (Exception ex)
// do something

22. Agenda Enterprise Library 3.0 Introduction
MGB 2003
Agenda
Enterprise Library 3.0 Introduction
Policy Injection Motivations and Goals
Policy Injection Application Block Architecture
Call Handlers and Matching Rules
Extending the PIAB
Summary
© 2003 Microsoft Corporation. All rights reserved.
This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.

23. Supplied Handlers PIAB ships with six handlers
Validation Handler
Logging Handler
Authorization Handler
Exception Handling Handler
Caching Handler
Performance Counter Handler
Most are shims over other Enterprise Library application blocks

24. Validation Handler
Validates parameters to a method, using the Validation Application Block
Validation rules can be defined
As rule sets defined on parameter types, using either attributes or configuration
By applying validation attributes directly on the method parameters
If validation fails, an ArgumentValidationException is thrown, and the method is not called
Exception contains the ValidationResults from the validation call

25. Logging Handler
Writes a log entry before and/or after the method is called, using the Logging Application Block
Uses a TraceLogEntry which contains additional properties related to the method call
Handler may be configured to log additional data, including:
Call Stack
Parameter Values
Return Value or Exception
Call execution time
Log Categories are configurable and may include tokens such as {method} and {type}

26. Authorization Handler
Uses a Security Application Block Authorization Provider to determine if the current user is authorized to perform an operation
Current user is determined from the thread principal
Handler is configured with
The name of the Authorization Provider instance to use
The name of the Operation, which can include tokens such as {type} and {method}
If authorization fails, an UnauthorizedAccessException is thrown, and the method is not called

27. Exception Handling Handler
Executes after a method is called
Processes any exceptions thrown by the method using the Exception Handling Application Block
Handler is configured with the name of the Exception Policy to use
After processing, the handler will throw either the original or the new exception back to the caller, based on the exception policy definition
Exceptions may only be swallowed for void methods

28. Caching Handler
Uses the System.Web.Cache to cache method return values, keyed off the method signature and input parameters
Keys are generated using GetHashCode
Handler is configured with a TimeSpan indicating how long return values should be cached
Before the method is called, the handler checks if a value is in the cache for the set of inputs
If so, the cached return value is returned, instead of calling the method.
If not, the method is called and the return value is cached for future use

29. Performance Counter Handler
Increments a number of performance counters that provide useful metrics around use and performance
Handler can be configured to specify which counters and instances to use
Available counters include
Total number of times the method is called
Rate of calls (per second)
Average call duration
Number of exceptions thrown
Rate of exceptions thrown (per second)

30. Supplied Matching Rules
PIAB includes a number of matching rules that test members against static metadata:
Assembly Matching Rule
Custom Attribute Matching Rule
Member Name Matching Rule
Method Signature Matching Rule
Namespace Matching Rule
Parameter Type Matching Rule
Property Matching Rule
Return Type Matching Rule
Tag Attribute Matching Rule
Type Matching Rule

31. Effective Policy Viewer
While the PIAB offers many benefits, separating business code from cross cutting concerns can also create confusion
Complete behavior cannot be determined only by looking at code
To take away the mystery, p&p provides the Effective Policy Viewer
This application shows which policies and handlers (configuration and attribute-based) will apply to which members in which order
Tool can be downloaded from

32. Agenda Enterprise Library 3.0 Introduction Policy Injection Goals
MGB 2003
Agenda
Enterprise Library 3.0 Introduction
Policy Injection Goals
Policy Injection Application Block Architecture
Call Handlers and Matching Rules
Extending the PIAB
Summary
© 2003 Microsoft Corporation. All rights reserved.
This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.

33. Extensibility points
The Policy Injection Application Block is designed to be extended
Defined extensibility points are:
Matching Rules
Handlers
Injectors
Other changes are possible by modifying source code

34. Building Custom Matching Rules
Build a new class implementing IMatchingRule
Create necessary constructors and fields for configurable properties
Implement Matches
bool Matches(MethodBase member)
Build a runtime configuration class, if you want strongly-typed configuration, or use CustomMatchingRuleData
Add the ConfigurationElementType attribute to the class, pointing to the runtime configuration class

35. Building Custom Handlers
Build a new class implementing ICallHandler
Create necessary constructors and fields for configurable properties
Implement Invoke
IMethodReturn Invoke(IMethodInvocation input, GetNextHandlerDelegate getNext)
Perform any pre-processing
Call the next handler using getNext().Invoke(input, getNext);
Perform any post-processing
Return the desired return value or exception
Build a runtime configuration class, if you want strongly-typed configuration, or use CustomCallHandlerData
Add the ConfigurationElementType attribute to the class, pointing to the runtime configuration class

36. Agenda Enterprise Library 3.0 Introduction
MGB 2003
Agenda
Enterprise Library 3.0 Introduction
Policy Injection Motivations and Goals
Policy Injection Application Block Architecture
Call Handlers and Matching Rules
Extending the PIAB
Summary
© 2003 Microsoft Corporation. All rights reserved.
This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.

37. Summary
The Policy Injection Application Block is about separating business logic from cross cutting concerns
Cross cutting concerns are applied using policies, comprising of matching rules and a handler pipeline
Each handler can perform logic before or after a method call
Policy-enabled objects are created with a factory that returns a proxy wired up to the handler pipeline
Used wisely, this application block can improve clarity, maintainability and consistency of applications

38. Resources Download Enterprise Library and related resources from:
Join the Enterprise Library Community at:
Share community extensions at:
Read blogs from the Enterprise Library team at:

39. MGB 2003 © 2003 Microsoft Corporation. All rights reserved.
This presentation is for informational purposes only. Microsoft makes no warranties, express or implied, in this summary.