Audit.EntityFramework 27.3.2

Audit.EntityFramework

Entity Framework Audit Extension for Audit.NET library.

Automatically generates Audit Logs for EntityFramework's operations. Supporting EntityFramework and EntityFramework Core

This library provides the infrastructure to log interactions with the EF DbContext. It can record detailed information about CRUD operations in your database.

Install

NuGet Package

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

PM> Install-Package Audit.EntityFramework

Or, if you use EntityFramework core:

PM> Install-Package Audit.EntityFramework.Core

Or, if you want to audit ASP.NET Identity entities, you must also install the Audit.EntityFramework.Identity library:

PM> Install-Package Audit.EntityFramework.Identity

EF library version

The following table shows the entity framework package version used for each .NET framework and audit library:

<sub>Target</sub> \ <sup>Library</sup>	Audit.EntityFramework / Audit.EntityFramework.Identity	Audit.EntityFramework.Core / Audit.EntityFramework.Identity.Core
.NET 4.6.2	EntityFramework 6.5.0	N/C
.NET 4.7.2	EntityFramework 6.5.0	N/C
.NET Standard 2.1	EntityFramework 6.5.0	Microsoft.EntityFrameworkCore 5.0.17
.NET 6.0	EntityFramework 6.5.0	Microsoft.EntityFrameworkCore 6.0.36
.NET 7.0	EntityFramework 6.5.0	Microsoft.EntityFrameworkCore 7.0.20
.NET 8.0	EntityFramework 6.5.0	Microsoft.EntityFrameworkCore 8.0.11
.NET 9.0	EntityFramework 6.5.0	Microsoft.EntityFrameworkCore 9.0.0

N/C: Not Compatible

Usage

High-Level SaveChanges Interception

In order to audit Insert, Delete and Update operations, you can use any of the three SaveChanges interception mechanisms provided:

1. Inheriting from AuditDbContext

Change your EF context class to inherit from Audit.EntityFramework.AuditDbContext instead of DbContext.

For example, if you have a context like this:

public class MyContext : DbContext
{
    public DbSet<Blog> Blogs { get; set; }
    public DbSet<Post> Posts { get; set; }
}

In order to enable the audit log, you should change it to inherit from AuditDbContext:

public class MyContext : AuditDbContext // <-- inherit from Audit.EntityFramework.AuditDbContext
{
    public DbSet<Blog> Blogs { get; set; }
    public DbSet<Post> Posts { get; set; }
}

Note

If you're using IdentityDbContext instead of DbContext, you can install the package Audit.EntityFramework.Identity or Audit.EntityFramework.Identity.Core and inherit from the class AuditIdentityDbContext instead of AuditDbContext.

2. Without inheritance, overriding SaveChanges

You can use the library without changing the inheritance of your DbContext. In order to to that, you can define your DbContext in the following way, overriding SaveChanges and SaveChangesAsync:

public class MyContext : DbContext
{
    private readonly DbContextHelper _helper = new DbContextHelper();
    private readonly IAuditDbContext _auditContext;

    public MyContext(DbContextOptions<MyContext> options) : base(options)
    {
        _auditContext = new DefaultAuditContext(this);
        _helper.SetConfig(_auditContext);
    }

    public override int SaveChanges(bool acceptAllChangesOnSuccess)
    {
        return _helper.SaveChanges(_auditContext, () => base.SaveChanges(acceptAllChangesOnSuccess));
    }

    public override async Task<int> SaveChangesAsync(bool acceptAllChangesOnSuccess, CancellationToken cancellationToken = default(CancellationToken))
    {
        return await _helper.SaveChangesAsync(_auditContext, () => base.SaveChangesAsync(acceptAllChangesOnSuccess, cancellationToken));
    }
}

Note

No other SaveChanges override is needed, since all the other overloads will call one of these two.

3. With the provided save changes interceptor

Save Changes Interceptors were introduced in EF Core 5.0.

If you can't change the inheritance of your DbContext, and/or can't override the SaveChanges, you can attach an instance of AuditSaveChangesInterceptor to your DbContext configuration.

For example:

public class MyContext : DbContext
{
    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        optionsBuilder.AddInterceptors(new AuditSaveChangesInterceptor());
    }
    // ...
}

Or alternatively, when creating your DbContext:

var options = new DbContextOptionsBuilder()
    .AddInterceptors(new AuditSaveChangesInterceptor())
    .Options;
using (var ctx = new MyContext(options))
{
    // ...
}

Or using DI, such as with ASP.NET Core:

builder.Services.AddDbContext<MyContext>(c => c
    .UseSqlServer(CONNECTION_STRING)
    .AddInterceptors(new AuditSaveChangesInterceptor())

Note

Notice that a new instance of the interceptor is registered for each DbContext instance. This is because the auditing interceptor contains state linked to the current context instance.

Considerations

• All the Save Changes interception methods produces the same output. You should use only one of these methods, otherwise you could get duplicated audit logs.

Low-Level Command Interception

A low-level command interceptor is also provided for Entity Framework Core.

In order to audit low-level operations like reads, stored procedure calls and non-query commands, you can attach the provided AuditCommandInterceptor to your DbContext configuration.

For example:

var options = new DbContextOptionsBuilder()
    .AddInterceptors(new AuditCommandInterceptor())
    .Options;
using (var ctx = new MyContext(options))
{
    // ...
}

Or inside DbContext configuration:

public class MyDbContext : DbContext
{
    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        optionsBuilder.AddInterceptors(new AuditCommandInterceptor());
    }

    // ...
}

Or using DI, such as with ASP.NET Core:

builder.Services.AddDbContext<MyContext>(c => c
    .UseSqlServer(CONNECTION_STRING)
    .AddInterceptors(new AuditCommandInterceptor())

Note

The Command Interceptor generates a different type of audit output than the Save Changes Interceptor. Nevertheless, you can combine the Command Interceptor with any of the Save Changes interception mechanisms.

Configuration

Output

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

The Audit Data Provider can be configured in several ways:

• Per DbContext instance by explicitly setting the AuditDataProvider property. For example:

  public class MyContext : AuditDbContext
  {
    public MyContext()
    {
        AuditDataProvider = new SqlDataProvider(config => config...);
    }
  }
  

• By registering an AuditDataProvider instance in the dependency injection container.

  For example:

  public class Program
  {
    public static void Main(string[] args)
    {
      var builder = WebApplication.CreateBuilder(args);
  
      builder.Services.AddSingleton<AuditDataProvider>(new SqlDataProvider(config => config...));
    }
  }
  

• Globally, by setting the AuditDataProvider instance through the Audit.Core.Configuration.DataProvider static property or the Audit.Core.Configuration.Use() methods.

  For example:

  public class Program
  {
    public static void Main(string[] args)
    {
      Audit.Core.Configuration.Setup().UseSqlServer(config => config...);
    }
  }
  

If you intend to store audit logs with EF, consider using the Entity Framework Data Provider.

Settings (low-Level interceptor)

The low-level command interceptor can be configured by setting the AuditCommandInterceptor properties, for example:

optionsBuilder.AddInterceptors(new AuditCommandInterceptor()
{
    ExcludeNonQueryEvents = true,
    AuditEventType = "{database}",
    IncludeReaderResults = true
});

• LogParameterValues: Boolean value to indicate whether to log the command parameter values. By default (when null) it will depend on EnableSensitiveDataLogging setting on the DbContext.
• ExcludeReaderEvents: Boolean value to indicate whether to exclude the events handled by ReaderExecuting. Default is false to include the ReaderExecuting events.
• IncludeReaderEventsPredicate: Predicate to include the ReaderExecuting events based on the event data. By default, all the ReaderExecuting events are included. This predicate is ignored if ExcludeReaderEvents is set to true.
• ExcludeNonQueryEvents: Boolean value to indicate whether to exclude the events handled by NonQueryExecuting. Default is false to include the NonQueryExecuting events.
• ExcludeScalarEvents: Boolean value to indicate whether to exclude the events handled by ScalarExecuting. Default is false to include the ScalarExecuting events.
• AuditEventType: To indicate the event type to use on the audit event. (Default is the execute method name). Can contain the following placeholders:
  • {context}: replaced with the Db Context type name.
  • {database}: Replaced with the database name
  • {method}: Replaced with the execute method name (ExecuteReader, ExecuteNonQuery or ExecuteScalar)
• IncludeReaderResults: Boolean value to indicate whether to include the query results to the audit output. Default is false.

Settings (High-Level interceptor)

The following settings for the high-level interceptor can be configured per DbContext or globally:

• Mode: To indicate the audit operation mode
  • Opt-Out: All the entities are tracked by default, except those explicitly ignored. (Default)
  • Opt-In: No entity is tracked by default, except those explicitly included.
• IncludeEntityObjects: To indicate if the output should contain the complete entity object graphs. (Default is false)
• AuditEventType: To indicate the event type to use on the audit event. (Default is the context name). Can contain the following placeholders:
  • {context}: replaced with the Db Context type name.
  • {database}: replaced with the database name.
• IncludeIndependantAssociations: Value to indicate if the Independant Associations should be included. Default is false. (Only for EF ⇐ 6.2)

Note

Note: EF Core ⇐ 3 does not support many-to-many relations without a join entity, and for EF Core 5 the many-to-many relations are normally included on the audit event entries.

• ExcludeTransactionId: Value to indicate if the Transaction IDs should be excluded from the output and not be retrieved (default is false to include the Transaction IDs).
• ExcludeValidationResults: Value to indicate if the entity validations should be avoided and excluded from the audit output. (Default is false)
• EarlySavingAudit: Value to indicate if the audit event should be saved before the entity saving operation takes place. (Default is false to save the audit event after the entity saving operation completes or fails)
• ReloadDatabaseValues: Value to indicate if the original values of the audited entities should be queried from database before saving the audit event.

The ReloadDatabaseValues configuration is beneficial for making modifications without explicitly retrieving the entity first. It can be enabled when using DbSet.Update or DbSet.Remove with an object that wasn't retrieved from the database. When enabled, it queries the database prior to any entity modification to record the original values in the audit event.

The following settings can be configured per entity type:

• IgnoredProperties: To indicate the entity's properties (columns) to be ignored on the audit logs.
• OverrideProperties: To override property values on the audit logs.
• FormatProperties: To indicate replacement functions for the property's values on the audit logs.

The Ignore, Override and Format settings are only applied to the Changes and ColumnValues collections on the EventEntry. The Entity object (if included) will not be affected by these settings.

Change the settings for a DbContext by decorating it with the AuditDbContext attribute, for example:

[AuditDbContext(Mode = AuditOptionMode.OptOut, IncludeEntityObjects = false, AuditEventType = "{database}_{context}" )]
public class MyEntitites : Audit.EntityFramework.AuditDbContext
{
...

You can also use the Fluent API to configure the high-level interceptor settings globally.

Include/Ignore entities (tables)

To ignore specific entities on the audit (when using OptOut Mode), you can decorate your entity classes with the AuditIgnore attribute, for example:

[AuditIgnore]
public class Blog
{
    public int Id { get; set; }
    ...
}

Instead, to include specific entities to the audit (when using OptIn Mode), you can use the AuditInclude attribute:

[AuditInclude]
public class Post
{
    public int Id { get; set; }
    ...
}

Exclude properties (columns)

The AuditIgnore attribute can be used on the entity's properties to indicate that its value should not be included on the audit logs. For example to prevent storing passwords on the logs:

public class User
{
    public int Id { get; set; }
    [AuditIgnore]
    public string Password { get; set; }
    ...
}

Override properties (columns)

The AuditOverride attribute can be used to override a column value with a constant value. For example to override the password values with a NULL value:

public class User
{
    [AuditOverride(null)]
    public string Password { get; set; }
    ...
}

Note you can also provide a replacement function of the value, please see next section.

Fluent API

You can configure the settings via a convenient Fluent API provided by the method Audit.EntityFramework.Configuration.Setup(), this is the most straightforward way to configure the library.

For example, to configure a context called MyContext, that should include the objects on the output, using the OptOut mode, excluding from the audit the entities whose name ends with History:

Audit.EntityFramework.Configuration.Setup()
    .ForContext<MyContext>(config => config
        .IncludeEntityObjects()
        .AuditEventType("{context}:{database}"))
    .UseOptOut()
        .IgnoreAny(t => t.Name.EndsWith("History"));

Another example configuring ignored, overriden and formatted column values. In this example, the Photo column is ignored, the OldPassword will be always null and the Password will be set to a number of stars equal to the number of password characters.

Audit.EntityFramework.Configuration.Setup()
    .ForContext<MyContext>(config => config
        .ForEntity<User>(_ => _
            .Ignore(user => user.Photo)
            .Override(user => user.OldPassword, null)
            .Format(user => user.Password, pass => new String('*', pass.Length))));

In summary, you have three ways to configure the audit for the contexts:

• By accessing the properties on the AuditDbContext base class.
• By decorating your context classes with AuditDbContext attribute and your entity classes with AuditIgnore/AuditInclude attributes.
• By using the fluent API provided by the method Audit.EntityFramework.Configuration.Setup()

All three can be used at the same time, and the precedence order is the order exposed in the above list.

Event Output

To configure the output persistence mechanism please see Configuration and Data Providers sections.

Overrides

The AuditDbContext has the following virtual methods that can be overriden to provide your custom logic:

• OnScopeCreated: Called before the EF operation execution and after the AuditScope creation.
• OnScopeSaving: Called after the EF operation execution and before the AuditScope saving.
• OnScopeSaved: Called after the AuditScope saving.

This is useful to, for example, save the audit logs in the same transaction as the operation being audited, so when the audit logging fails the audited operation is rolled back.

public class MyDbContext : AuditDbContext
{
    public MyDbContext()
    {
        // Set a NULL data provider, since log saving is done in this class 
        AuditDataProvider = new NullDataProvider();
    }
    
    public override void OnScopeCreated(IAuditScope auditScope)
    {
        Database.BeginTransaction();
    }

    public override void OnScopeSaving(IAuditScope auditScope)
    {
        try 
        {
            // ... custom log saving ...
        }
        catch
        {
            // Rollback call is not mandatory. If exception thrown, the transaction won't get commited
            Database.CurrentTransaction.Rollback(); 
            throw;
        }
        Database.CurrentTransaction.Commit();
    }
}

Note

In this example we want the event saving to be done on the OnScopeSaving method, so we must bypass the Data Provider and this can be done by setting a NullDataProvider.

Output

Audit.EntityFramework output includes:

• Execution time and duration
• Environment information such as user, machine, domain and locale.
• Affected SQL database and table names
• Affected column data including primary key, original and new values
• Model validation results
• Exception details
• Transaction identifiers (to group logs that are part of the same SQL or ambient transaction)
• Entity object graphs (optional with IncludeEntityObjects configuration)

With this information, you can measure performance, observe exceptions thrown or get statistics about usage of your database.

Output details

SaveChanges audit output

The following tables describes the output fields for the SaveChanges interception:

• EntityFrameworkEvent

Field Name	Type	Description
Database	string	Name of the database affected
ConnectionId	Guid	A unique identifier for the database connection.
ContextId	string	A unique identifier for the context instance and pool lease.
TransactionId	string	Unique identifier for the DB transaction used on the audited operation (if any). To group events that are part of the same transaction.
AmbientTransactionId	string	Unique identifier for the ambient transaction used on the audited operation (if any). To group events that are part of the same ambient transaction.
Entries	Array of EventEntry	Array with information about the entities affected by the audited operation
Associations	Array of AssociationEntry	Independant associations changes, many-to-many relations without a join table with changes (only for EF ⇐6.2, not available on EF Core)
Result	integer	Result of the SaveChanges call. Is the number of objects affected by the operation.
Success	boolean	Boolean to indicate if the operation was successful
ErrorMessage	string	The exception thrown details (if any)

• EventEntry

Field Name	Type	Description
Table	string	Name of the affected table
Name	string	The entity friendly name (only for EF Core ≥ 3)
Action	string	Action type (Insert, Update or Delete)
PrimaryKey	Object	Object with the affected entity's primary key value(s)
ColumnValues	Object	Object with the affected entity's column values
Changes	Array of ChangeObject	An array containing the modified columns with the original and new values (only available for Update operations)
Entity	Object	The object representation of the .NET entity affected (optional)
Valid	boolean	Boolean indicating if the entity passes the validations
ValidationResults	Array of string	The validation messages when the entity validation fails

• ChangeObject

Field Name	Type	Description
ColumnName	string	The column name that was updated
OriginalValue	string	The original value before the update
NewValue	string	The new value after the update

Command Interceptor audit output

The following table describes the output fields for the low-level command interception:

• CommandEvent

Field Name	Type	Description
Database	string	Name of the database affected
ConnectionId	Guid	A unique identifier for the database connection.
ContextId	string	A unique identifier for the context instance and pool lease.
Method	string	The command method executed (NonQuery, Scalar, Reader)
CommandType	CommandType	The command type (Text, StoredProcedure, etc)
CommandSource	CommandSource	The command source type (SaveChanges, LinqQuery, etc)
CommandText	string	The command text
Parameters	Dictionary	The parameter values, if any, when EnableSensitiveDataLogging is enabled
IsAsync	boolean	Indicates whether the call was asynchronous
Result	object	Result of the operation. Query results are only included when IncludeReaderResults is set to true.
Success	boolean	Boolean to indicate if the operation was successful
ErrorMessage	string	The exception thrown details (if any)

Customization

Custom fields

You can add extra information to the events by calling the method AddAuditCustomField on the DbContext. For example:

using(var context = new MyEntitites())
{
	...
	context.AddAuditCustomField("UserName", userName);
	...
	context.SaveChanges();
	
}

Another way to customize the output is by using global custom actions, please see custom actions for more information.

Getting the entity framework event

The AuditDbContext provides an alternative Save Changes operation (SaveChangesGetAudit() method) to save the changes and get the generated EntityFrameworkEvent object. This is useful when you want to get the audit event information generated by a particular Save Changes operation.

For example:

// Save the changes and get the generated audit event
var efEvent = await _dbContext.SaveChangesGetAuditAsync();
	
// Log all the operations to the tables affected
foreach(var entry in efEvent.Entries)
{
	Console.WriteLine($"{entry.Action} {entry.Table}");
}

Entity Framework Data Provider

If you plan to store the audit logs via EntityFramework, you can use the provided EntityFrameworkDataProvider. Use this to store the logs on audit tables handled by EntityFramework.

Note

Only the high-level audit events are processed by this data provider. Any other audit event, including the low-level events generated by the command interceptor, are ignored by the entity framework data provider.

For example, you want to audit Order and OrderItem tables into Audit_Order and Audit_OrderItem tables respectively, and the structure of the Audit_* tables mimic the audited table plus some fields like the event date, an action and the username:

Note

By default, the library uses the same DbContext instance audited to store the audit logs. This is not mandatory and the recommendation is to provide a different DbContext instance per audit event by using the UseDbcontext() fluent API.

EF Provider configuration

To set the EntityFramework data provider globally, set the static Audit.Core.Configuration.DataProvider property to a new EntityFrameworkDataProvider:

Audit.Core.Configuration.DataProvider = new EntityFrameworkDataProvider()
{
    DbContextBuilder = ev => new OrderDbContext(),
    AuditTypeMapper = (t, ee) => t == typeof(Order) ? typeof(OrderAudit) : t == typeof(Orderline) ? typeof(OrderlineAudit) : null,
    AuditEntityAction = (evt, entry, auditEntity) =>
    {
        var a = (dynamic)auditEntity;
        a.AuditDate = DateTime.UtcNow;
        a.UserName = evt.Environment.UserName;
        a.AuditAction = entry.Action; // Insert, Update, Delete
        return Task.FromResult(true); // return false to ignore the audit
    }
};

Or use the fluent API UseEntityFramework method, this is the recommended approach:

Audit.Core.Configuration.Setup()
    .UseEntityFramework(ef => ef
        .UseDbContext<OrderDbContext>()
        .AuditTypeExplicitMapper(m => m
            .Map<Order, OrderAudit>()
            .Map<Orderline, OrderlineAudit>()
            .AuditEntityAction<IAudit>((evt, entry, auditEntity) =>
            {
                auditEntity.AuditDate = DateTime.UtcNow;
                auditEntity.UserName = evt.Environment.UserName;
                auditEntity.AuditAction = entry.Action; // Insert, Update, Delete
            })
        )
    );

EF Provider Options

Mandatory:

• UseDbContext: A function that returns the DbContext to use for storing the audit events, by default it will use the same context being audited.
• DisposeDbContext: A boolean value to indicate if the audit DbContext should be disposed after saving the audit. Default is false.
• AuditTypeMapper: A function that maps an entity type to its audited type (i.e. Order → Audit_Order, etc).
• ExplicitMapper: An alternative mapper, as a function that excplicitly maps an entry to its audited type, useful to configure mapping when no entity type is associated with a table, or to setup complex mapping rules.
• AuditEntityCreator: An alternative to the mapper, as a function that creates the audit entity instance from the Event Entry and the Audit DbContext. Useful to control the Audit Entity object creation for example when using change-tracking proxies.
• AuditEntityAction: An action to perform on the audit entity before saving it, for example to update specific audit properties like user name or the audit date. It can also be used to filter out audit entities. Make this function return a boolean value to indicate whether to include the entity on the output log.
• IgnoreMatchedProperties: Set to true to avoid the property values copy from the entity to the audited entity (default is false).
• IgnoreMatchedPropertiesFunc: Allows to selectively ignore property matching on certain types. It's a function that receives the audit entity type and returns a boolean to indicate if the property matching must be ignored for that type.

EF Provider configuration examples

The UseEntityFramework method provides several ways to indicate the Type Mapper and the Audit Action.

Map by type name:

You can map the audited entity to its audit log entity by the entity name using the AuditTypeNameMapper method, for example to prepend Audit_ to the entity name. This assumes both entity types are defined on the same assembly and namespace:

Audit.Core.Configuration.Setup()
    .UseEntityFramework(x => x
        .AuditTypeNameMapper(typeName => "Audit_" + typeName)
        .AuditEntityAction((ev, ent, auditEntity) =>
        {
            // auditEntity is object
	    ((dynamic)auditEntity).AuditDate = DateTime.UtcNow;
        }));

the AuditEvent (shown here as ev) in an instance of AuditEventEntityFramework. As such, it can be casted to that type or by using the helper method ev.GetEntityFrameworkEvent().

Audit.Core.Configuration.Setup()
    .UseEntityFramework(x => x
        .AuditTypeNameMapper(typeName => "Audit_" + typeName)
        .AuditEntityAction<IAudit>((ev, ent, auditEntity) =>
        {
	    var entityFrameworkEvent = ev.GetEntityFrameworkEvent();
	    auditEntity.TransactionId = entityFrameworkEvent.TransactionId;
        }));

Common action:

If your audit log entities implements a common interface or base class, you can use the generic version of the AuditEntityAction method to configure the action to be performed to each audit trail entity before saving. Also this action can be asynchronous, for example:

Audit.Core.Configuration.Setup()
    .UseEntityFramework(x => x
        .AuditTypeNameMapper(typeName => "Audit_" + typeName)
        .AuditEntityAction<IAudit>(async (ev, ent, auditEntity) =>
        {
            // auditEntity is of IAudit type
            auditEntity.AuditDate = DateTime.UtcNow;
            auditEntity.SomeValue = await GetValueAsync();
        }));

Use the explicit mapper to provide granular configuration per audit type:

Audit.Core.Configuration.Setup()
    .UseEntityFramework(x => x
        .AuditTypeExplicitMapper(m => m
            .Map<Order, Audit_Order>((order, auditOrder) => 
            { 
                // This action is executed only for Audit_Order entities
                auditOrder.Status = "Order-" + order.Status; 
            })
            .Map<OrderItem, Audit_OrderItem>()
            .AuditEntityAction<IAudit>((ev, ent, auditEntity) =>
            {
                // This common action executes for every audited entity
                auditEntity.AuditDate = DateTime.UtcNow;
            })));

Ignore certain entities on the audit log:

Audit.Core.Configuration.Setup()
    .UseEntityFramework(x => x
        .AuditTypeExplicitMapper(m => m
            .Map<Order, Audit_Order>((order, auditOrder) =>
            {
                if (auditOrder.Status == "Expired")
                {
                    return false; // don't want to audit orders in "expired" status
                }
                auditOrder.AuditDate = DateTime.UtcNow;
                return true;
            })));

Custom DbContext instance:

To set a custom DbContext instance for storing the audit events, for example when your Audit_* entities are defined in a different database and context (i.e. AuditDatabaseDbContext):

Audit.Core.Configuration.Setup()
    .UseEntityFramework(x => x
        .UseDbContext<AuditDatabaseDbContext>()
        .DisposeDbContext()
        .AuditTypeExplicitMapper(m => m
            .Map<Order, Audit_Order>()
            .AuditEntityAction<IAudit>((ev, ent, auditEntity) =>
            {
                auditEntity.AuditDate = DateTime.UtcNow;
            })));

Map multiple entity types to the same audit type with independent actions:

When you want to store the audit logs of different entities in the same audit table, for example:

Audit.Core.Configuration.Setup()
    .UseEntityFramework(ef => ef
        .AuditTypeExplicitMapper(m => m
            .Map<Blog, AuditLog>((blog, audit) =>
            {
                // Action for Blog -> AuditLog
                audit.TableName = "Blog";
                audit.TablePK = blog.Id;
                audit.Title = blog.Title;
            })
            .Map<Post, AuditLog>((post, audit) =>
            {
                // Action for Post -> AuditLog
                audit.TableName = "Post";
                audit.TablePK = post.Id;
                audit.Title = post.Title;
            })
            .AuditEntityAction<AuditLog>((evt, entry, audit) =>
            {
                // Common action on AuditLog
                audit.AuditDate = DateTime.UtcNow;
                audit.AuditAction = entry.Action;
                audit.AuditUsername = Environment.UserName;
            }))
	.IgnoreMatchedProperties(true));

Another example for all entities mapping to a single audit log table that stores the changes in a JSON column:

Audit.Core.Configuration.Setup()
    .UseEntityFramework(_ => _
        .AuditTypeMapper(t => typeof(AuditLog))  
        .AuditEntityAction<AuditLog>((ev, entry, entity) =>
        {
            entity.AuditData = entry.ToJson();
            entity.EntityType = entry.EntityType.Name;
            entity.AuditDate = DateTime.Now;
            entity.AuditUser = Environment.UserName;
	    entity.TablePk = entry.PrimaryKey.First().Value.ToString();
        })
	.IgnoreMatchedProperties(true));

Note

Notice the use of .IgnoreMatchedProperties(true) to avoid the library trying to set properties automatically by matching names between the audited entities and the type AuditLog.

Map an entity type to multiple audit types, depending on the modified entry:

When you want to save audit logs to different tables for the same entity, for example, if you have different audit tables per operation:

Audit.Core.Configuration.Setup() 
    .UseEntityFramework(ef => ef.AuditTypeExplicitMapper(m => m
        .Map<Blog>(
            mapper: entry => entry.Action == "Update" ? typeof(Audit_Updates_Blog) : typeof(Audit_Blog), 
            entityAction: (ev, entry, entity) =>
            {
                if (entity is Audit_Updates_Blog upd)
                {
                    // action for updates
                }
                else if (entity is Audit_Blog etc)
                {
                    // action for insert/delete
                }
            })
        .AuditEntityAction<IAuditLog>((evt, entry, auditEntity) =>
        {
            // common action...
        })));

• Updates to Blog table → Audit to Audit_Updates_Blog table
• Any other operation on Blog table → Audit to Audit_Blog table

Map Many to Many relations without join entity:

When you want to audit many to many relations which are not mapped to an entity type, i.e. implicitly created join tables. You have to use the AuditTypeExplicitMapper and set up the mapping of the relation table by using MapTable or MapExplicit methods.

For example, consider the following model:

There are two entities, Post and Tag with a Many to Many relation between them (note there is no relation entity). Also you want to audit the Post and Tag tables to the Audit_Post and Audit_Tag tables respectively, and you want to audit the PostTag relation table to an Audit_PostTag table.

Audit.Core.Configuration.Setup()
    .UseEntityFramework(_ => _
        .UseDbContext<YourAuditDbContext>()
        .DisposeDbContext()
        .AuditTypeExplicitMapper(map => map
            .Map<Post, Audit_Post>()
            .Map<Tag, Audit_Tag>()
            .MapTable<Audit_PostTag>("PostTag", (EventEntry ent, Audit_PostTag auditPostTag) =>
            {
                auditPostTag.PostId = ent.ColumnValues["PostsId"];
                auditPostTag.TagId = ent.ColumnValues["TagsId"];
            })
            .AuditEntityAction((ev, entry, auditEntity) =>
            {
                ((dynamic)auditEntity).AuditAction = entry.Action;
                ((dynamic)auditEntity).AuditDate = DateTime.UtcNow;
            })));

The first parameter of MapTable is the table name to which the mapping will apply. The generic parameter is the target audit type. You can optionally pass an action to execute on the audit entity as the second parameter. If property matching is enabled for the target type, the framework will map the Column values to the entity Property values.

Map via Factory:

When you need to control the Audit Entity creation, for example when using change-tracking proxies, you can use the AuditEntityCreator to specify a factory that creates the Audit Entity for a given entry.

Audit.Core.Configuration.Setup()
    .UseEntityFramework(ef => ef
        .UseDbContext<YourAuditDbContext>()
        .DisposeDbContext()
        .AuditEntityCreator(auditDbContext => auditDbContext.CreateProxy<AuditLog>())
        .AuditEntityAction<AuditLog>((ev, ent, auditEntity) =>
        {
            auditEntity.DateTime = DateTime.Now;
            auditEntity.Action = ent.Action;
            auditEntity.Table = ent.Table;
        })
        .IgnoreMatchedProperties());

Another example of an audit Entity factory, but mapping to different entity types depending on the audited table:

Audit.Core.Configuration.Setup()
    .UseEntityFramework(ef => ef
        .UseDbContext<YourAuditDbContext>()
        .DisposeDbContext()
        .AuditEntityCreator((auditDbContext, entry) => entry.Table switch
        {
            "Customer" => auditDbContext.CreateProxy<AuditCustomer>(),
            "User" => auditDbContext.CreateProxy<AuditUser>(),
            _ => auditDbContext.CreateProxy<AuditLog>()
        })
        .AuditEntityAction<IAuditLog>((ev, ent, auditEntity) =>
        {
            auditEntity.DateTime = DateTime.Now;
            auditEntity.Action = ent.Action;
            auditEntity.Table = ent.Table;
        })
        .IgnoreMatchedProperties());

);

Generic DbContext Data Provider

Overview

The DbContextDataProvider<TDbContext, TEntity> class is a generic audit data provider that uses Entity Framework Core to write and read audit events. It is designed to be flexible and configurable, allowing to map any kind of audit events to a specific entity in a DbContext.

Note

The DbContextDataProvider differs from the EntityFrameworkDataProvider in that it is a generic provider that can be used to store any kind of audit event, not just the high-level events generated by the Entity Framework Core SaveChanges interceptor.

DbContext Provider Options

• DbContextBuilder / UseDbContext(): A function that returns the DbContext to use for storing the audit events. If not specified, it will use the parameterless constructor to create the DbContext instance.
• DbContextOptions / UseDbContextOptions(): The DbContextOptions to use for creating the DbContext instance. Alternative to the DbContextBuilder.
• Mapper: A function that maps the audit event to the entity. The function receives the audit event and the audit entity instance (existing or new) and must hydrate the audit entity instance.
• DisposeDbContext: A boolean value to indicate if the audit DbContext should be disposed after saving the audit. Default is false.

DbContext Provider configuration examples

Basic configuration

The following example shows how to configure the DbContextDataProvider to store the audit events in a custom DbContext:

Audit.Core.Configuration.Setup()
    .UseDbContext<MyDbContext, AuditLog>(x => x
        .DbContextBuilder(_ => new MyDbContext())
        .Mapper((auditEvent, auditEntity) =>
        {
            auditEntity.AuditDate = auditEvent.StartDate;
            auditEntity.UserName = auditEvent.Environment.UserName;
            auditEntity.JsonData = auditEvent.ToJson();
        }));


public class MyDbContext : DbContext
{
    public DbSet<AuditLog> AuditLogs { get; set; }
}

Contribute

If you like this project please contribute in any of the following ways:

• Star this project on GitHub.
• Request a new feature or expose any bug you found by creating a new issue.
• Ask any questions about the library on StackOverflow.
• Subscribe to and use the Gitter Audit.NET channel.
• Support the project by becoming a Backer:    
• Spread the word by blogging about it, or sharing it on social networks: <p class="share-buttons"> <a href="https://www.facebook.com/sharer/sharer.php?u=https://nuget.org/packages/Audit.NET/&t=Check+out+Audit.NET" target="_blank"> <img width="24" height="24" alt="Share this package on Facebook" src="https://nuget.org/Content/gallery/img/facebook.svg" / > </a> <a href="https://twitter.com/intent/tweet?url=https://nuget.org/packages/Audit.NET/&text=Check+out+Audit.NET" target="_blank"> <img width="24" height="24" alt="Tweet this package" src="https://nuget.org/Content/gallery/img/twitter.svg" /> </a> </p>
• Make a donation via PayPal