Audit.NET

Audit.NET

USAGE | OUTPUT | CUSTOMIZATION | DATA PROVIDERS | CREATION POLICY | CONFIGURATION | EXTENSIONS

Issues	Build status	Quality gate	Donations	Docs

An extensible framework to audit executing operations in .NET and .NET Core.

Generate audit logs with evidence for reconstruction and examination of activities that have affected specific operations or procedures.

With Audit.NET, you can generate detailed tracking information for executed operations. It captures environmental data such as the caller's user ID, machine name, method name, exceptions, and execution time. The framework also provides an extensible mechanism to enrich logs and manage audit outputs.

• Interaction extensions to audit different systems are provided, such as Entity Framework, MVC, WebAPI, WCF, WCF Client, File System, SignalR, MongoClient, gRPC Client, gRPC Server, MediatR, Hangfire, Azure Functions, and HttpClient.

• Output extensions are provided to log to JSON Files, Event Log, Open Telemetry Spans, SQL, MySQL, PostgreSQL, RavenDB, MongoDB, AzureBlob, AzureTables, AzureCosmos, AzureEventHubs, Redis, Elasticsearch, OpenSearch, DynamoDB, ImmuDB, UDP datagrams, Channels and more.

• Output wrappers are included to facilitate the encapsulation of other Data Providers for diverse purposes, like resilience or lazy instantiation, such as Polly, Lazy, Deferred and Conditional.

NuGet

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

PM> Install-Package Audit.NET

Changelog

Check the CHANGELOG.md file.

ZZZ Projects - Sponsorship

Entity Framework Extensions and Dapper Plus are major sponsors and are proud to contribute to the development of Audit.NET

Combine the power of auditing with the speed of Bulk Operations to get the best of both worlds — audit and performance.

Introduction

The Audit Scope and Audit Event are the central objects of this framework.

Audit Scope

The AuditScope serves as the central object in this framework, representing the scope of an audited operation or event. It acts as a context for auditing, capturing pertinent details like the start time, involved entities, and any additional custom information. Essentially, the AuditScope encapsulates an AuditEvent, controlling its life cycle.

The AuditScope is a disposable object, commonly utilized within a using statement to ensure proper finalization and recording of audit information upon exiting the scope.

See the audit scope statechart.

Audit Event

The AuditEvent functions as an extensible information container that captures the details of the audited operation, is the representation of the audited information within an Audit Scope. It includes details about the audited operation, such as the event type, timestamp, execution duration, and any custom fields or properties.

The AuditEvent is typically serialized into a format suitable for storage or transmission, such as JSON.

The audit events are stored using a Data Provider. You can use one of the available data providers or implement your own.

Audit Scope Factory

The preferred method for creating audit scopes is by using an IAuditScopeFactory instance. This approach ensures a centralized and consistent configuration for all audit scopes.

var factory = new AuditScopeFactory();
using var scope = factory.Create(new AuditScopeOptions(...));
...

If you're using a DI container, you can register the IAuditScopeFactory as a service and inject it into your classes. The default implementation of IAuditScopeFactory is provided by the AuditScopeFactory class.

services.AddScoped<IAuditScopeFactory, AuditScopeFactory>();

Then you can inject the IAuditScopeFactory into your classes to create audit scopes:

public class MyService
{
  private readonly IAuditScopeFactory _auditScopeFactory;

  public MyService(IAuditScopeFactory auditScopeFactory)
  {
    _auditScopeFactory = auditScopeFactory;
  }

  public void MyMethod()
  {
    using var scope = _auditScopeFactory.Create(new AuditScopeOptions(...));
    ...
  }
}

You can also implement your own IAuditScopeFactory to customize the creation of audit scopes. The recommended approach is to inherit from the AuditScopeFactory class. By overriding the OnConfiguring and OnScopeCreated methods, you can configure the audit scope options before creation and customize the audit scope after creation respectively.

For example:

public class MyAuditScopeFactory : AuditScopeFactory
{
  private readonly IMyService _myService;
  public MyAuditScopeFactory(IMyService myService)
  {
    _myService = myService;
  }

  public override void OnConfiguring(AuditScopeOptions options)
  {
    // Set the data provider to use
    options.DataProvider = new SqlDataProvider(...);
  }

  public override void OnScopeCreated(AuditScope auditScope)
  {
    // Add a custom field to the audit scope
    auditScope.SetCustomField("CustomId", _myService.GetId());
  }
}

Several extensions for generating audit events, such as Audit.EntityFramework.Core, Audit.WebApi.Core, Audit.Mvc.Core, and Audit.SignalR, will automatically attempt to resolve the IAuditScopeFactory and AuditDataProvider instances from the service provider.

Support for older .NET frameworks

Beginning with version 23.0.0, this library and its extensions have discontinued support for older .NET Framework and Entity Framework (versions that lost Microsoft support before 2023).

For reference, please consult the following links:

• .NET Core Support Policy
• Entity Framework Core releases

This library and its extensions will maintain support for the following minimum .NET framework versions:

• .NET Framework 4.6.2 (net462)
• .NET Standard 2.0 (netstandard2.0)
• .NET 6 (net6.0)

Usage

The Audit Scope is the central object of this framework. It encapsulates an audit event, controlling its life cycle. The Audit Event is an extensible information container of an audited operation.

There are several ways to create an Audit Scope:

• Calling the Create() / CreateAsync() methods of an AuditScopeFactory instance. This is the recommended approach. For example:

  var scope = auditScopeFactory.Create(new AuditScopeOptions(...));
  

• Using the overloads of the static methods Create() / CreateAsync() on AuditScope, for example:

  var scope = AuditScope.Create(new AuditScopeOptions()
  {
    EventType = "Order:Update",
    TargetGetter = () => order,
    ExtraFields = new { MyProperty = "value" }
  });
  

• Using the provided fluent API, for example:

  var scope = AuditScope.Create(_ => _
      .EventType("Order:Update")
      .ExtraFields(new { MyProperty = "value" })
      .Target(() => order));
  

AuditScope options

Option	Type	Description
EventType	string	A string representing the type of the event
TargetGetter	Func<object>	Target object getter (a func that returns the object to track)
ExtraFields	object	Anonymous object that contains additional fields to be merged into the audit event
DataProvider	AuditDataProvider	The [data provider](#dat