Audit.DynamicProxy 25.0.2

Audit.DynamicProxy

Dynamic Proxy Extension for Audit.NET library.

Generate Audit Logs by intercepting operations on virtually any class.

Audit.DynamicProxy provides the infrastructure to create audit logs for a class without changing its code. It relies on Castle DynamicProxy library to intercept and record the operation calls (methods and properties) including caller info and arguments.

Install

NuGet Package

To install the package run the following command on the Package Manager Console:

PM> Install-Package Audit.DynamicProxy

Usage

To enable the audit log for an instance of a class, create a proxy for the class by calling the AuditProxy.Create<>() method.

This will return a proxied audit-enabled instance that you should use instead of the real instance. Each operation on the proxy (access to a property or method call) will generate an Audit Event.

Suppose you have a MyRepository instance that you want to audit, like this:

public class MyDataAccess
{
    IMyRepository _repository = new MyRepository(); // <- Audit this object

    public async Task<int> InsertUserAsync(string userName)
    {
        return await _repository.InsertUserAsync(userName);
    }
    // ...
}

To enable the audit on the _repository object, intercept its assignation by calling AuditProxy.Create<>():

public class MyDataAccess
{
    IMyRepository _repository = AuditProxy.Create<IMyRepository>(new MyRepository()); // Audited!

    public async Task<int> InsertUserAsync(string userName)
    {
        return await _repository.InsertUserAsync(userName);
    }
    // ...
}

You can also intercept conditionally, for example to avoid auditing when a debugger is attached:

public class MyDataAccess
{
    IMyRepository _repository = new MyRepository();

    public MyDataAccess()
    {
        if (!Debugger.IsAttached)
        {
            // Audit only when no debugger is attached
            _repository = AuditProxy.Create<IMyRepository>(_repository);
        }
    }
}

Creating proxies

The AuditProxy.Create<>() method returns an auditable proxy object that inherits from the proxied class/implements proxied interface and forwards calls to the real object.

This is the method signature:

T AuditProxy.Create<T>(T instance, InterceptionSettings settings = null)

Give special attention to the generic type argument T, it can be:

• An interface: Will generate an interface proxy to log all the interface member calls. (Recommended)
• A class type: Will generate a class proxy to log virtual member calls. Non-virtual methods can't be automatically audited.

When using an interface proxy, the interception is limited to the members of the interface. And when using a class proxy, the interception is limited to its virtual members.

The instance argument is an instance of the object to be audited.

The settings argument allows you to change the default settings. See settings section for more information.

Settings

The InterceptionSettings class include the following settings:

• EventType: A string that identifies the event type. Default is "{class}.{method}". Can contain the following placeholders:
  • {class}: Replaced by the class name
  • {method}: Replaced by the method name
• IgnoreProperties: A boolean indicating whether the audit should ignore the property getters and setters. If true, the property accesses will not be logged. Default is false
• IgnoreEvents: A boolean indicating whether the audit should ignore the event attach and detach operations. If true, the event accesses will not be logged. Default is false
• MethodFilter: A function that takes a MethodInfo and returns a boolean indicating whether the method should be taken into account for the logging. Use this setting to have fine grained control over the methods that should be audited. By default all methods are included.
• AuditDataProvider: Allows to set a specific audit data provider for this instance. By default the globally configured data provider is used. See Audit.NET Data Providers section for more information.

AuditIgnore Attribute

You can exclude specific members, arguments or return values from the audit, by decorating them with the AuditIgnore attribute. For example:

public class MyRepository : IMyRepository
{
    //Ignore a method (no events will be generated for this method)
    [AuditIgnore] 
    public User GetUser(string userName)
    {
       ...
    }

    //Ignore an argument (argument value will not be included in the output)
    public User FindUser(int type, [AuditIgnore] Filter filter)
    {
        ...
    }

    //Exclude the return value (result will not be included in the output)
    [return:AuditIgnore] 
    public List<User> SearchUsers(string text)
    {
        ...
    }
}

Customization

You can access the current audit scope from an audited member by getting the static AuditProxy.CurrentScope property.

The static property AuditProxy.CurrentScope returns the scope for the current running thread and should be accessed from the same thread as the executing audited operation. Calling this from a different thread will lead to an unexpected result. On async methods, you should only access this propery before any await ocurrence.

For example:

public class MyRepository : IMyRepository
{
    public async Task<int> InsertUserAsync(string userName)
    {
        var auditScope = AuditProxy.CurrentScope;   // Get the current scope
        auditScope.SetCustomField("TestField", Guid.NewGuid()); // Set a custom field
        
        //... existing code to insert user ...

        if (pleaseDoNotLog)
        {
            auditScope.Discard(); // Discard the event
        }

        return await _repository.InsertUserAsync(userName);
    }
}

Output

Audit.DynamicProxy output includes:

• Execution time and duration (async-aware)
• Environment information such as user, machine, domain and locale.
• Method parameters (input and output)
• Return object
• Exception details
• Comments and Custom Fields provided

With this information you can know who did the operation, and also measure performance, observe exceptions thrown and get statistics about usage of your classes.

Async calls are logged when the asynchronous call ends; as a continuation task, so the Audit Event includes the actual duration and result.

Output Details

The following table describes the Audit.DynamicProxy output fields:

AuditInterceptEvent

Describes an operation call event

AuditInterceptArgument

Describes an operation argument

Output Samples

Successful async method call:

{
  "EventType": "MyRepository.InsertUserAsync",
  "Environment": {
    "UserName": "Federico",
    "MachineName": "HP",
    "DomainName": "HP",
    "CallingMethodName": "Audit.DynamicProxy.AuditInterceptor.Intercept()",
    "AssemblyName": "Audit.DynamicProxy, Version=4.5.2.0, Culture=neutral, PublicKeyToken=null",
    "Culture": "en-GB"
  },
  "StartDate": "2016-09-30T12:00:35.7073819-05:00",
  "EndDate": "2016-09-30T12:00:36.7168197-05:00",
  "Duration": 1009,
  "InterceptEvent": {
    "ClassName": "MyRepository",
    "MethodName": "InsertUserAsync",
    "IsAsync": true,
    "AsyncStatus": "RanToCompletion",
    "InstanceQualifiedName": "Audit.DynamicProxy.UnitTest.MyRepository, Audit.DynamicProxy.UnitTest, Version=3.0.0.0, Culture=neutral, PublicKeyToken=null",
    "MethodSignature": "System.Threading.Tasks.Task`1[System.Int32] InsertUserAsync(System.String)",
    "Arguments": [
      {
        "Index": 0,
        "Name": "userName",
        "Type": "String",
        "Value": "thepirat000"
      }
    ],
    "Success": true,
    "Result": {
      "Type": "Task<Int32>",
      "Value": 142857
    }
  }
}

Failed async method call:

{
  "EventType": "MyRepository.InsertUserAsync",
  "Environment": {
    "UserName": "Federico",
    "MachineName": "HP",
    "DomainName": "HP",
    "CallingMethodName": "Audit.DynamicProxy.AuditInterceptor.Intercept()",
    "AssemblyName": "Audit.DynamicProxy, Version=4.5.2.0, Culture=neutral, PublicKeyToken=null",
    "Exception": "COMException: Exception from HRESULT: 0xE0434352",
    "Culture": "en-GB"
  },
  "StartDate": "2016-09-30T12:18:34.5093824-05:00",
  "EndDate": "2016-09-30T12:18:35.5388113-05:00",
  "Duration": 1029,
  "InterceptEvent": {
    "ClassName": "MyRepository",
    "MethodName": "InsertUserAsync",
    "IsAsync": true,
    "AsyncStatus": "Faulted",
    "InstanceQualifiedName": "Audit.DynamicProxy.UnitTest.MyRepository, Audit.DynamicProxy.UnitTest, Version=3.0.0.0, Culture=neutral, PublicKeyToken=null",
    "MethodSignature": "System.Threading.Tasks.Task`1[System.Int32] InsertUserAsync(System.String)",
    "Arguments": [
      {
        "Index": 0,
        "Name": "userName",
        "Type": "String",
        "Value": null
      }
    ],
    "Success": false,
    "Exception": "(ArgumentNullException) UserName cannot be null",
    "Result": null
  }
}