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.
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:
