Defining and Configuring Matching Rules
| 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 Policy Injection Application Block uses a set of matching rules within each policy to select the class, and the members of that class, to which the handler pipeline for that policy will apply. A matching rule is essentially a predicate that the application block checks each time it intercepts object creation or wrapping. If all the specified matching rules evaluate to True for any particular invocation, the application block will create and add the handler pipeline for that policy.
Note
For a given policy to match, all rules must match.
The following table shows the full list of matching rule types available in the Policy Injection Application Block.
Note
Matching rule types in the Policy Application Block are placeholders to enable configuration by reading the configuration file. When you specify the Policy Injection Application Block matching rule, it is actually the matching rule from the Unity Application Block that executes.
Matching rule type |
Predicate description |
Matching rule parameters |
|---|---|---|
AssemblyMatchingRule |
Class is in the specified assembly. |
Assembly name (String), exact match only on the assembly name; the name and version; the name, version and culture; or the full assembly name. |
CustomAttributeMatchingRule |
Class or member has an arbitrary attribute applied. |
Custom attribute type (Type), whether to search the entire inheritance chain (Boolean), exact match only. |
MemberNameMatchingRule |
Class member has one of the specified names. |
Target method/property names (String collection), ignore case (Boolean), exact or wildcard character match. |
MethodSignatureMatchingRule |
Class method has the specified signature. |
Target method name (String), type names of target method parameters (String collection), ignore case (Boolean), uses the same type matching rules as the TypeMatchingRule. |
NamespaceMatchingRule |
Class is in one of the specified namespaces. |
Namespace names (String collection), ignore case (Boolean), exact match on root namespace, and exact or wildcard character match on child namespaces. |
ParameterTypeMatchingRule |
Class member has a parameter or return value that matches one of the specified types. |
Target type names (String collection), parameter type (Input | Output | InputOrOutput | ReturnValue), ignore case (Boolean), uses the same type matching rules as the TypeMatchingRule. |
PropertyMatchingRule |
Class property has one of the specified names and contains the specified combination of accessors. |
Property names (String collection), accessor options (Get | Set | GetOrSet), ignore case (Boolean), exact or wildcard character match. |
ReturnTypeMatchingRule |
Class member accepts or returns an object of the specified type. |
Type name of target method return type (String), ignore case (Boolean), exact or wildcard character match. |
TagAttributeMatchingRule |
Class member carries a Tag attribute with the specified string. |
Tag attribute name (String), ignore case (Boolean), exact match only. |
TypeMatchingRule |
Class is of one of the specified types. |
Target type names (String collection), ignore case (Boolean), exact match only on the namespace-qualified type name, or just the type name. |
Developers can also create custom matching rules if required. For more details, see Extending and Modifying the Policy Injection Application Block.
Configuring Matching Rules
The following procedure describes how to add one of the built-in matching rules to an application using the configuration tools.
To configure a new built-in matching rule
- Right-click the Matching Rules node in the Enterprise Library Configuration Console or Visual Studio Configuration Editor, point to New, and then click the type of matching rule you want to add.
- 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 matching rule.
- 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 matching rule you selected. Edit the properties to suit the requirements of your application. For details about the properties for each type of matching rule, see Configuring and Using Matching Rules.
- Repeat this procedure to add additional matching rules as required.
The next procedure describes how to add a custom matching rule type to an application using the configuration tools.
To configure a custom matching rule
- Right-click the Matching Rules node in the Enterprise Library Configuration Console or Visual Studio Configuration Editor, point to New, and then click Custom Matching Rule.
- 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 matching rule.
- 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, you have the option of typing 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 matching rule, and then click OK.
- If the list does not show the assembly containing the custom matching rule, click Load from File or Load from GAC, navigate to the assembly that contains the matching rule, select the assembly, and then click Open. Back in the Type Selector dialog box, select the required custom matching rule class, and then click OK.
- 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.
- 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 an attribute the custom matching rule requires.
- 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 Matching Rule configuration item allows you to configure any custom matching rule 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 matching rule at run time through a NameValueCollection passed to the custom class.
Only classes that implement the IMatchingRule interface and carry the attribute [ConfigurationElementType(typeof(CustomMatchingRuleData))] 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 matching rules, see Creating a New Matching Rule.