The Rules Editor provides a common interface for creating inclusion and exclusion rules used by several Dotfuscator features.
The Rules Editor is used by:
| Feature | Rule Type |
|---|---|
| Renaming | Exclusion rules |
| Control Flow | Exclusion rules |
| String Encryption | Inclusion rules |
| Removal | Trigger Method selection rules |
| Removal | Conditional Include selection rules |
Rules can be created in two ways:
| Method | Description |
|---|---|
| Select Individual Elements | Select specific assemblies, namespaces, types, or members directly in the application tree. |
| Create Custom Rules | Create reusable rules using names, attributes, signatures, inheritance relationships, and custom attributes. |
The Rules Editor also allows you to preview the effect of a rule before building your protected application.
Selecting Individual Elements
The simplest way to create a rule is to select items directly in the application tree.
Assemblies
The top-level nodes in the application tree represent assemblies.
Selecting an assembly automatically selects all modules, namespaces, types, and members contained within that assembly.
Modules
Module nodes appear beneath assemblies.
Selecting a module automatically selects all namespaces, types, and members contained within that module.
Namespaces
Namespace nodes appear beneath modules.
Selecting a namespace automatically selects all types and members contained within that namespace.
Types
Type nodes appear beneath namespaces or modules. Nested types are displayed using the / character to separate parent and child types.
The behavior of a type selection depends on the feature being configured.
| Rule Type | Behavior |
|---|---|
| Renaming Exclusion | Selects only the type name. Members remain unaffected. |
| Other Rule Types | Selects the type and all members contained within the type. |
Members
Members include methods, fields, properties, and events.
Selecting a member creates a rule that applies only to that specific member.
Creating Custom Rules
Create custom rules by adding nodes to the rule editing view using the Add Namespace and Add Type options. Depending on the type of rule, you can attach regular expressions and other selection criteria to the rule. Once the rule is configured, you can preview its effects as follows:
- For a single rule, right-click on the rule's node and select Preview from the menu.
- For all rules, select the Preview option.
Items selected by the rule are shaded in the application tree view.
Selecting By Namespace
A namespace rule selects all types and their members in matching namespaces.
Namespace Name
You create a namespace rule by clicking the Add Namespace button, then typing a name in the Name field. The name is interpreted as a regular expression if the Regular Expression checkbox is checked; otherwise the name is interpreted literally (and thus matches at most one namespace).
Namespace Rule Node
The corresponding node displayed in the rule editing view has a child element that indicates whether the rule is a regular expression. You can preview the items selected by the rule by right clicking on the node and selecting the preview option from the menu.
Selecting By Type
A type rule selects differently depending on what type of rule you are creating.
If you are creating a renaming exclusion rule, the rule selects just the type name for exclusion (provided the ExcludeType checkbox is checked), leaving members alone.
If you are specifying any other kind of rule, the rule selects zero or more types and all their members. This reflects the fact that in these cases, selecting a type means that you are in fact selecting all members defined by that type.
Type Name
You create a type rule by clicking the Add Type button, then typing a name in the Name field. The name is interpreted as a regular expression if the Regular Expression checkbox is checked; otherwise the name is interpreted literally. The name must be a fully qualified type name that includes the namespace and parent class information if it is a nested type.
Type Attribute Specifier
In addition to type name, you can also select based on type attribute specifiers, using the values provided in the "Spec" list box. A '-' preceding an attribute specifier negates the attribute (i.e. it selects all types that do not have the specified attribute). You can select multiple attributes from the list; the criteria implied by multiple selections are logically AND-ed together. For example, you can select types that are both public and abstract by selecting +public and +abstract from the list.
The attribute specifications are logically AND-ed with the type name, so if you want to select all types with a specific set of attributes, you need to provide a regular expression for the type name that selects all types (i.e. ".*").
Exclude Type Checkbox
The Exclude Type checkbox is only active if you are working with renaming exclusion rules. If checked, the rule excludes the names of matching types from renaming and allow you to provide additional rules for selecting members of matching types. If left unchecked, the rule still selects matching types for the purposes of applying rules to members of the types, but it does not select the type name. In this manner, you can write renaming exclusion rules that exclude methods and fields, but allow type names to be obfuscated.
Apply to Derived Types Checkbox
The Apply to Derived Types checkbox is only active if you are working with renaming or removal rules. If checked, the rule additionally excludes the child classes of matching types from renaming or removal. In this manner, you can write renaming exclusion rules that exclude entire inheritance hierarchies.
Type Rule Node
The corresponding node displayed in the rule editing view has a child element that indicates whether the rule is a regular expression and whether the rule has attribute specifiers associated with it. You can preview the types selected by the rule by right clicking on the node and selecting the Preview option from the menu.
In the screen shot, a type rule is defined that selects the names of all concrete (not abstract) types for exclusion from renaming.
Selecting By Method
Method rules are qualified by type rules, so they appear in the rules view as children of type nodes. A method rule selects all methods (in all types matched by the parent type rule) that match your criteria. Supported matching criteria include method name, method attributes, and signature.
Method Name
You create a method rule by right clicking on the parent type rule's node and selecting Add Method, then typing a name in the Name field. The name is interpreted as a regular expression if the Regular Expression checkbox is checked; otherwise the name is interpreted literally.
Method Attribute Specifier
In addition to method name, you can also select based on method attribute specifiers, using the values provided in the Attribute Specifier list box. A '-' preceding an attribute specifier negates the attribute (i.e. it selects all methods that do not have the specified attribute). You can select multiple attributes from the list; the criteria implied by multiple selections are logically AND-ed together (that is, the set of selected methods is the intersection of all methods that match each attribute specifier.). For example, you can select methods that are both public and virtual by selecting +public and +virtual from the list.
The attribute specifications are logically AND-ed with the method name and signature list, so if you want to select all methods with a specific set of attributes, you need to provide a regular expression for the method name that selects all methods (i.e. "*.**").
Method Signature
You can also select methods by signature. A signature specifies both the return type and the parameter types of the method. The method signature reduces the scope of the method rule, so if you want to create a rule that selects methods regardless of signature, you need to provide a regular expression for the signature that selects all signatures (i.e. ".*"). This is the default value.
Method Rule Node
The corresponding method node displayed in the rule editing view has a child element that indicates whether the rule is a regular expression and whether the rule has attribute specifiers, and/or a signature associated with it. You can preview the items selected by the rule by right clicking on the node and selecting the Preview option from the menu.
In the screen shot, a method rule is defined that selects the names of all public methods (in all types) whose names start with "S".
Selecting By Field
Field rules are qualified by type rules, so they appear in the rules view as children of type nodes. A field rule selects all fields (in all types matched by the parent type rule) that match your criteria. Supported matching criteria include field name and field attributes.
Field Name
You create a field rule by right clicking on the parent type rule's node and selecting Add Field, then typing a name in the Name field. The name is interpreted as a regular expression if the Regular Expression checkbox is checked; otherwise the name is interpreted literally.
Field Attribute Specifier
In addition to field name, you can also select based on field attribute specifiers, using the values provided in the Attribute Specifier list box. A '-' preceding an attribute specifier negates the attribute (i.e. it selects all fields that do not have the specified attribute). You can select multiple attributes from the list; the criteria implied by multiple selections are logically AND-ed together (that is, the set of selected fields is the intersection of all fields that match each attribute specifier.). For example, you can select fields that are both public and static by selecting +public and +static from the list.
The attribute specifications are logically AND-ed with the field name, so if you want to select all fields with a specific set of attributes, you need to provide a regular expression for the field name that selects all fields (i.e. "*.**").
Field Signature
You can also select fields by signature. A signature specifies the type of the field. The field signature reduces the scope of the field rule, so if you want to create a rule that selects fields regardless of type, you need to provide a regular expression for the signature that selects all signatures (i.e. ".*"). This is the default value.
Field Rule Node
The corresponding field node displayed in the rule editing view has a child element that indicates whether the rule is a regular expression and whether the rule has attribute specifiers, and/or a signature associated with it. You can preview the fields selected by the rule by right clicking on the node and selecting the Preview option from the menu.
In the screen shot, a field rule is defined that selects the names of all fields (in all types) with names that start with "my".
Selecting By Property
Property rules are qualified by type rules, so they appear in the rules view as children of type nodes. A property rule selects all properties (in all types matched by the parent type rule) that match your criteria. Supported matching criteria include property name and property attributes.
Property Name
You create a property rule by right clicking on the parent type rule's node and selecting Add Property, then typing a name in the Name field. The name is interpreted as a regular expression if the Regular Expression checkbox is checked; otherwise the name is interpreted literally.
Property Attribute Specifier
In addition to property name, you can also select based on property attribute specifiers, using the values provided in the Attribute Specifier list box. A '-' preceding an attribute specifier negates the attribute (i.e. it selects all properties that do not have the specified attribute). You can select multiple attributes from the list; the criteria implied by multiple selections are logically AND-ed together (that is, the set of selected properties is the intersection of all methods that match each attribute specifier.). For example, you can select properties that are both public and virtual by selecting +public and +virtual from the list.
The attribute specifications are logically AND-ed with the property's name and signature list, so if you want to select all properties with a specific set of attributes, you need to provide a regular expression for the property name that selects all properties (i.e. "*.**").
Property Rule Node
The corresponding property node displayed in the rule editing view has a child element that indicates whether the rule is a regular expression and whether the rule has attribute specifiers. You can preview the items selected by the rule by right clicking on the node and selecting the Preview option from the menu.
In the screen shot, a property rule is defined that selects the names of all public properties (in all types) whose names start with "C".
Selecting By Event
Event rules are qualified by type rules, so they appear in the rules view as children of type nodes. An event rule selects all events (in all types matched by the parent type rule) that match your criteria. Supported matching criteria include event name and event attributes.
Event Name
You create a event rule by right clicking on the parent type rule's node and selecting Add Event, then typing a name in the Name field. The name is interpreted as a regular expression if the Regular Expression checkbox is checked; otherwise the name is interpreted literally.
Event Attribute Specifier
In addition to event name, you can also select based on event attribute specifiers, using the values provided in the Attribute Specifier list box. A '-' preceding an attribute specifier negates the attribute (i.e. it selects all events that do not have the specified attribute). You can select multiple attributes from the list; the criteria implied by multiple selections are logically AND-ed together (that is, the set of selected events is the intersection of all events that match each attribute specifier.). For example, you can select events that are both public and static by selecting +public and +static from the list.
The attribute specifications are logically AND-ed with the event name, so if you want to select all events with a specific set of attributes, you need to provide a regular expression for the event name that selects all events (i.e. "*.**").
Event Rule Node
The corresponding event node displayed in the rule editing view has a child element that indicates whether the rule is a regular expression and whether the rule has attribute specifiers. You can preview the events selected by the rule by right clicking on the node and selecting the Preview option from the menu.
In the screen shot, an event rule is defined that selects the names of all events (in all types) with names that start with "G".
Selecting By Custom Attribute
Custom attribute rules are qualified by type, method, field, property, or event rules, so they appear in the rules view as children of type, method, field, property, or event nodes. A custom attribute rule selects all items selected by the parent node that are also annotated with a matching custom attribute.
Custom Attribute Name
You create a custom attribute rule by right clicking on the parent type, method, field, property, or event rule's node and selecting Add Custom Attribute, then typing a name in the Name field. The name is interpreted as a regular expression if the Regular Expression checkbox is checked; otherwise the name is interpreted literally.
Allow Inheritance Checkbox
The Allow Inheritance checkbox controls how the custom attribute rule is applied to inheritance hierarchies. If checked, the rule additionally excludes overriding methods, properties, events, and sub types.
Custom Attribute Rule Node
The corresponding custom attribute node displayed in the rule editing view has a child element that indicates whether the rule is a regular expression. You can preview the types, methods, fields, properties, or events selected by the rule by right clicking on the node and selecting the Preview option from the menu.
In the screen shot, a custom attribute rule is defined that selects all methods that are annotated with a custom attribute named AttributeExample.MyAttribute.
Selecting By Supertype
Supertype rules are qualified by type rules, so they appear in the rules view as children of type nodes. A supertype rule narrows the scope of a type rule so that only types matched by the parent type rule that also derive from the specified supertype are selected.
Supertype Name
You create a supertype rule by right clicking on the parent type rule's node and selecting Add Supertype, then typing a name in the Name field. The name is interpreted as a regular expression if the Regular Expression checkbox is checked; otherwise the name is interpreted literally.
Supertype Rule Node
The corresponding supertype node displayed in the rule editing view has a child element that indicates whether the rule is a regular expression. You can preview the types selected by the rule by right clicking on the node and selecting the Preview option from the menu.
In the screen shot, a supertype rule is defined that selects all types that are supertypes of System.Attribute.
Editing and Deleting Rules
Edit a Rule
- Select the rule in the Rules Editor.
- Modify the rule settings in the editor pane.
Delete a Rule
- Select the rule.
- Click Delete.
Working with Attributes
The Rules Editor displays items selected through declarative obfuscation attributes.
Elements selected through ObfuscationAttribute or ObfuscateAssemblyAttribute are displayed in blue within the application tree.
This allows you to see how attribute-based configuration affects the current rule set.
In the screenshot below, the methods of Class1 and Class2 are marked as removal triggers using ObfuscationAttributes. Each attribute's properties and values are expanded in the view.
For more information, see Advanced Protection Scenarios.