PreEmptive Protection - Dotfuscator
Community Edition User Guide

Attributes

.NET attributes are declarative metadata items that are attached to assemblies and code elements such as methods. Dotfuscator uses attributes in two ways:

Specifying Injection Points with Attributes

Dotfuscator's Check and Analytics features both inject code into your application. The code is injected into locations specified by attributes. For a full listing of these attributes, see:

There are two ways to mark your code with Check or Analytics attributes:

  1. By adding the attributes to your code directly
  2. By configuring your Dotfuscator project to act as if attributes are present on specific assemblies and methods

You can also apply both techniques in the same project.

In all cases, you can also specify project-level options. This includes disabling injection entirely.

Adding Attributes to Code

You can add injection attributes to your source code directly. This allows you to see, while you are editing code, what assemblies and methods will be affected by Dotfuscator's code injection.

To add such attributes to your code:

  1. Reference the PreEmptive.Attributes.dll assembly, located in the Dotfuscator CE install directory.

  2. Add attributes from the PreEmptive.Attributes namespace to your code as appropriate, including providing necessary values to the attribute's properties.

  3. Build your application as you usually would to produce compiled assemblies.

  4. When Dotfuscator processes your assemblies, it will inject the specified Checks and Analytics code into the annotated code elements.

  5. Dotfuscator will also remove the attribute usages, as well as the references to PreEmptive.Attributes.dll, from your assemblies, as they are not needed at runtime by your code or the injected code.

For example, session tracking can be configured by using a BusinessAttribute and an ApplicationAttribute on the assembly, as well as a SetupAttribute and a TeardownAttribute on the program's entry point:

AssemblyInfo.cs excerpt

using PreEmptive.Attributes;

// ... other Assembly-level attributes ...

[assembly: Business("7d2b02e0-064d-49a0-bc1b-4be4381c62d3", "PreEmptive Community Workbench Key")]
[assembly: Application("2cb9969e-d76b-4846-8524-4e76750bafc5", "Dotfuscator Community Edition Sample")]

Program.cs excerpt

using PreEmptive.Attributes;

namespace ConsoleApp
{
    public class Program
    {
        [Setup]
        [Teardown]
        public static void Main(string[] args)
        {
            // ... application logic ...
        }
    }
}

If this assembly is used as an input for a Dotfuscator project, provided injection is not disabled for the project, Dotfuscator will produce a modified assembly with session-tracking code injected into the Main method.

Using Extended Attributes

You can also choose to specify attributes directly from the Dotfuscator CE GUI, without modifying your source code. Attributes specified this way are referred to as extended attributes.

For more information, see the Adding Attributes from the GUI section of the Analytics Configuration page.

Using Both Techniques

You can use both in-code attributes and extended attributes in the same Dotfuscator project. Dotfuscator treats these attributes equivalently.

For more information, see the Working with In-Code Attributes section of the Analytics Configuration page.

Interacting with Application Code

There are several scenarios where the injected code can interact with existing application code. Application code that provides information to the injected code is known as a source; application code that receives information from the injected code is known as a sink.

For instance, the application can inform the injected Analytics Setup code of the user's opt-in preference via its OptInSource. This is configured via the SetupAttribute's OptInSourceElement, OptInSourceName, and OptInSourceOwner properties.

Each source or sink is configured via three properties on the relevant attribute:

  • An element property, which specifies the kind of code item that the source or sink is:

    • None: No source or sink.

    • Method: A method defined in a type.

    • Field: A field defined in a type.

    • Property: A property defined in a type.

    • MethodArgument: An argument to the method that is annotated.

    • Delegate: A delegate defined in a type.

    • DefaultAction: Other injected code, specific to the type of attribute.

  • A name property, which specifies the name of the code item.

    • This property is ignored when the element is set to None or DefaultAction.
  • An owner property, which specifies the type that defines the code item (if applicable).

    • This property is ignored when the element is set to None, MethodArgument, or DefaultAction.

    • If blank, defaults to the type that defines the annotated method.

The signature of the source or sink, and the meaning of DefaultAction, depend on the attribute in question.

When specifying a Method, Field, Property, or Delegate source or sink, the code item can be either a static member of a type or an instance member defined on the same type as the annotated method.

Static Members

If the source or sink is a static member, it must simply be accessible from the annotated method. The code element will be used as a static member (i.e., without being tied to a particular object instance).

Instance Members

If the source or sink is an instance member, it must be defined on the same type as the annotated method, and the annotated method must also be an instance member. The code element will be used as a member of same instance that runs the annotated method.

Obfuscation Attributes

Obfuscation Attributes are used to declare which code elements should be excluded from obfuscation. This process is known as Declarative Obfuscation.



Dotfuscator Version 5.27.0.4713. Copyright © 2017 PreEmptive Solutions, LLC