Defining and Configuring Handler Pipelines

  • Article
Retired Content

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
The latest Enterprise Library information can be found at the Enterprise Library site.

The Handlers section of a policy defines the series of handlers that the Policy Injection Application Block will execute when client code calls a method or sets a property of the target class that corresponds to the matching rules defined for that policy.

The Policy Injection Application Block executes the pre-processing task of each handler in the order that they occur in the configuration or the order you specify using the Order property of each handler (unless a handler aborts the process). The application block then calls the specified method or sets the specified property of the target object. After the target object method or property accessor completes, the Policy Injection Application Block executes the post-processing task of each handler (unless a handler aborts the process), in the reverse order.

Note

The term "handler," when used in the Policy Injection Application Block, defines an object that resides in a policy pipeline, and which can—if required—handle both pre-processing tasks and post-processing tasks. However, the more common scenario is for the handler to execute at only one of these stages, as either a pre-processing task or a post-processing task.

The following procedure describes how to add one of the built-in handlers to an application using the configuration tools.

To configure a built-in handler

  1. Right-click the Handlers node in the Enterprise Library Configuration Console or Visual Studio Configuration Editor, point to New, and then click the type of handler you want to add.
  2. In the right pane of the Enterprise Library Configuration Console, or in the Visual Studio Properties window, select the Name property, and then change the default name to the name you want to use for the new handler.
  3. The remaining properties shown in the right pane of the Enterprise Library Configuration Console, or in the Visual Studio Properties window, depend on the type of handler you selected. Edit the properties to suit the requirements of your application. For details about the settings for each type of handler, see Configuring and Using Pipeline Handlers.
  4. Repeat this procedure to add additional handlers as required.

The next procedure describes how to add a custom handler to an application using the configuration tools.

To configure a custom handler

  1. Right-click the Handlers node in the Enterprise Library Configuration Console or Visual Studio Configuration Editor, point to New, and then click Custom Handler.
  2. In the right pane of the Enterprise Library Configuration Console, or in the Visual Studio Properties window, select the Name property, and then change the default name to the name you want to use for the new handler.
  3. In the right pane of the Enterprise Library Configuration Console, or in the Visual Studio Properties window, select the Type property, and then click the ellipsis button (...) to open the Type Selector dialog box. In the Filter edit box, type the string to use to filter the list; for example, type string to filter for all classes containing the word "string." Select the class that implements the custom handler, and then click OK.
  4. If the list does not show the assembly that contains the custom handler, click Load from File or Load from GAC, navigate to the assembly that contains the handler, select the assembly, and then click Open. Back in the Type Selector dialog box, select the required custom handler class, and then click OK.
  5. In the right pane of the Enterprise Library Configuration Console, or in the Visual Studio Properties window, select the Attributes property, and then click the ellipsis button (...) to open the EditableKeyValue Collection Editor dialog box.
  6. Click Add, and then, in the right pane of the dialog box, enter the name of the attribute (the key) and the corresponding value for the attributes the custom handler requires.
  7. Repeat the previous step to add all the required attributes, and then click OK to close the EditableKeyValue Collection Editor dialog box.

Note

The Custom Call Handler entry allows you to configure any custom handler class you create. The configuration editor creates an entry in the configuration that contains the name and the class type, plus all the attributes you enter in the EditableKeyValue Collection Editor dialog box. These values are all available to the custom handler at run time through a NameValueCollection passed to the custom class.

Only classes that implement the ICallHandler interface and carry the attribute [ConfigurationElementType(typeof(CustomCallHandlerData))] will be visible in the Type Selector dialog box and available for configuration with Enterprise Library Configuration Console or Visual Studio Configuration Editor. For details about how you can create custom handlers, see Creating a New Handler.

Reordering Pipeline Handlers

It is important for the configuration of each policy to define the handlers for its pipeline in the correct and appropriate order. For example, when using the Exception Handling Handler or the Logging Handler to detect and record the activities of the target object, it is usual to place these at the start of the pipeline. If the same pipeline contains a Validation Handler or an Authorization Handler, these should normally reside after the Exception Handling Handler and the Logging Handler.

This ordering means that if validation or authorization fails, the Exception Handling Handler, the Logging Handler, or both, can detect and record the failure during their post-processing stages.

You can specify the order using the Order property of each handler, including handlers added to an object using attributes. If you do not specify the order, they will be added to the handler pipeline in the order they occur in the configuration. The next procedure describes how to reorder the handlers defined for the Policy Injection Application Block using the configuration tools.

To reorder the handlers in a pipeline

  1. Expand the Handlers node in the Enterprise Library Configuration Console or Visual Studio Configuration Editor to show the handler nodes it contains.
  2. Right-click the handler node you want to move, and then click either Move Up or Move Down. If the selected handler is the first in the list, the Move Up option is not available. If the selected handler is the last in the list, the Move Down option is not available.
  3. Alternatively, set the Order property of all handlers to consecutive values starting from 1 to specify the required order.