Naccatech.EntityFramework.Historian.Data 7.0.2026011.2

Introduction

EF Historian is built on EntityFramework and enables automatic auditing/history of any EF controlled tables. Setup your models in normal EF fashion and register them for history tracking. EF Historian will assign a runtime type matching the model identified and use it to track the changes.

Getting Started

To get started with EF Historian:

1. Download both the Naccatech.EntityFramework.Historian.Data and Naccatech.EntityFramework.Historian.Entities nuget packages.

2. Create a DbContext by adding a using statement for Naccatech.EntityFramework.Historian.Data and inheriting from the HistorianDbContext.

3. Perform the normal EF setup in your inherited DbContext: ConnectionStrings, DbSets, Entity Configurations...

4. Register the entities that you want tracked in the OnModelCreating override:

   1. Get your DbContext HistoryTracker instance by overriding OnModelCreating(...):

      protected override void OnModelCreating(ModelBuilder modelBuilder, HistoryTracker historyTracker)
      {
          // regular EF model configurations
      }
      

   2. Track an entity by calling historyTracker.Register<...>(schema):

      protected override void OnModelCreating(ModelBuilder modelBuilder, HistoryTracker historyTracker)
      {
          ...
          historyTracker.Register<MyFirstEntity>(null);
          historyTracker.Register<MySecondEntity>(null);
      }
      

   3. If certain properties should not be tracked, excluded them when registering the entity:

      protected override void OnModelCreating(ModelBuilder modelBuilder, HistoryTracker historyTracker)
      {
          ...
          historyTracker.Register<MyThirdEntity>(null, nameof(MyThirdEntity.FirstUntrackedProperty));
          historyTracker.Register<MyFourthEntity>(null, nameof(MyFourthEntity.FirstUntrackedProperty), nameof(MyFourthEntity.SecondUntrackedProperty));
      }
      

   4. All changes to any registered entities will be added to a history table for that entity in the desired schema (or default schema if null):

      protected override void OnModelCreating(ModelBuilder modelBuilder, HistoryTracker historyTracker)
      {
          ...
          var historySchema = "dbo.audit";
          historyTracker.Register<MyFifthEntity>(historySchema);
      }
      

5. Historical records are accessible from the DbContext by calling the generic method this.HistoricalSet<T>() with the registered model type:

   // IQueryable sets are returned with untracked entities (readonly)
   var oneDayAgo = DateTime.Now.Subtract(TimeSpan.FromHours(24));
   var recentChanges = context
       .HistoricalSet<MyFirstEntity>()
       .Where(x => x.__ChangedOn > oneDayAgo);
   

6. Historical records have the following properties in addition to all the tracked entity properties:

   public Guid __Id;               // unique key to each entry
   public string __ChangeType;     // the EntityFramework change type: Added, Modified, Deleted
   public string __ChangedFields;  // the field names that changed (null for Added and Deleted)
   public DateTime __ChangedOn;    // the UTC timestamp of the change