R8.EntityFrameworkCore.AuditProvider 1.0.9

R8.EntityFrameworkCore.AuditProvider

A .NET package for Entity Framework, providing comprehensive change tracking with deep insights. Capture creation, updates, deletions, and restorations of entities, including property names, old and new values, stack traces, and user details, all neatly stored in an Audits column as JSON.

Seamless Entity Auditing: Easily integrate audit functionality into your Entity Framework applications, offering a complete audit trail enriched with stack traces and user information. Gain full visibility into entity lifecycle changes for compliance, debugging, and accountability.

Full Entity Lifecycle Visibility: Track and visualize the complete life cycle of your entities with detailed auditing. In addition to changes, this package records the stack trace of changes and user actions, enabling a deeper understanding of data evolution and robust audit trails.

Installation

// ... other services

// Add AuditProvider
services.AddEntityFrameworkAuditProvider(options =>
{
    options.JsonOptions.WriteIndented = false;
    
    options.AuditFlagSupport.Created = AuditFlagState.ActionDate | AuditFlagState.Storage;
    options.AuditFlagSupport.Changed = AuditFlagState.ActionDate | AuditFlagState.Storage;
    options.AuditFlagSupport.Deleted = AuditFlagState.ActionDate | AuditFlagState.Storage;
    options.AuditFlagSupport.UnDeleted = AuditFlagState.ActionDate | AuditFlagState.Storage;
    
    options.MaxStoredAudits = 10;
    
    options.UserProvider = serviceProvider =>
    {
        var httpContextAccessor = serviceProvider.GetRequiredService<IHttpContextAccessor>();
        var user = httpContextAccessor.HttpContext?.User;
        if (user?.Identity?.IsAuthenticated == true)
        {
            var userId = user.FindFirstValue(ClaimTypes.NameIdentifier);
            var username = user.FindFirstValue(ClaimTypes.Name);
            return new AuditProviderUser(userId, new Dictionary<string, object>
            {
                { "Username", username }
            });
        }
        return null;
    };
});

services.AddDbContext<YourDbContext>((serviceProvider, optionsBuilder) =>
{
    // Your DbContext connection configuration here
    // ...
    optionsBuilder.AddEntityFrameworkAuditProviderInterceptor(serviceProvider);
});

Options

• If the number of audits exceeds this number, the earliest audits (except Created) will be removed from the column. If null, all audits will be stored.

Implementation

• IAuditActivator interface: to start auditing entities.
• IAuditStorage interface: to store audits in a column.
• IAuditSoftDelete interface: to soft-delete entities.
• IAuditCreateDate interface: to store creation date in a column.
• IAuditUpdateDate interface: to store last update/restore date in a column.
• IAuditDeleteDate interface: to store deletion date in a column.
• [AuditIgnore] attribute: to ignore a property from audit.

Samples:

• PostgreSQL: AggregateAuditable.cs
• Microsoft Sql Server: AggregateAuditable.cs
• or as below (for PostgreSQL):

public record YourEntity : IAuditActivator, IAuditStorage, IAuditSoftDelete, IAuditCreateDate, IAuditUpdateDate, IAuditDeleteDate
{
    [Key]
    public int Id { get; set; }

    [Column(TypeName = "jsonb"), AuditIgnore]
    public JsonElement? Audits { get; set; }

    public bool IsDeleted { get; set; }
    
    [Column("CreatedAt", TypeName = "timestamp")]
    public DateTime? CreateDate { get; set; }
    
    [Column("UpdatedAt", TypeName = "timestamp")]
    public DateTime? UpdateDate { get; set; }
    
    [Column("DeletedAt", TypeName = "timestamp")]
    public DateTime? DeleteDate { get; set; }
    
    // ...
    // public string Name { get; set; }
    // public string Description { get; set; }
    // etc.
}

Migration

Highly recommended to test it on a test database first, to avoid any data loss.

Considerations

• Since Microsoft Sql Server does not support json type, Audits column will be stored as nvarchar(max) and JsonElement will be serialized/deserialized to/from string. (See AggregateAuditable.cs)
• The key to allow auditing entities is implementation of IAuditActivator to your entity.
  • the IAuditStorage, IAuditSoftDelete, IAuditCreateDate, IAuditUpdateDate, and IAuditDeleteDate interfaces takes effect only if IAuditActivator is implemented to entity. If not implemented, the entity will be updated with the proper SaveChanges/SaveChangesAsync functionality in Entity Framework Core.
• Deleted and UnDeleted flag cannot be stored simultaneously with Created and Changed flags.
• If IAuditStorage is implemented to your entity, Audits column will be stored in the specified table.
• If any of IAuditCreateDate, IAuditUpdateDate or IAuditDeleteDate is implemented to entity, the corresponding date will be stored among the Audits column (of IAuditStorage interface) update.
• Any support flag in AuditProviderOptions.AuditFlagSupport must be written as a flag: AuditFlagState.ActionDate | AuditFlagState.Storage
  • If any of AuditFlag enums are included/excluded from AuditFlagSupport, the corresponding flag will take action in Audits and/or {Action}Date column according to the its state in AuditFlagSupport. (For instance, if AuditFlagSupport.Created = AuditProviderFlagSupport.Excluded, IAuditCreateDate and IAuditStorage, also and Created flag will be ignored.)

Some useful methods

To take advantages of JsonElement Audits property, you can easily convert it to AuditCollection:

var audits = (AuditCollection)entity.Audits.Value; // Cast to AuditCollection
// or
// var audits = AuditCollection.Parse(entity.Audits.Value);

JsonElement jsonElement = audits.Element; // Get underlying JsonElement

Audit[] deserializedAudits = audits.Deserialize(); // Get deserialized audits
Audit creationAudit = audits.GetCreated(); // Get created audit
Audit lastUpdatedAudit = audits.GetLast(includedDeleted: false); // Get last audit

Output Example

Stored data in Audits column will be like this:

[
  {
    "f": "0",
    // Created
    "dt": "2023-09-25T12:00:00.0000000+03:30",
  },
  {
    "f": "1",
    // Updated
    "dt": "2023-09-25T12:00:00.0000000+03:30",
    "c": [
      {
        "n": "Name",
        // Name of the property
        "_v": "OldName",
        // Old value
        "v": "NewName"
        // New value
      }
    ],
    "u": {
      "id": "1",
      // The user id (if provided)
      "ad": {
        // The user additional info (if provided)
        "Username": "Foo"
      }
    }
  },
  {
    "f": "2",
    // Deleted
    "dt": "2023-09-25T12:00:00.0000000+03:30",
  },
  {
    "f": "3",
    // Restored/Undeleted
    "dt": "2023-09-25T12:00:00.0000000+03:30",
  }
]

🎆 Happy coding!