Merge pull request #519 from waqasm78/master

Added Async example

Author: JonathanMagnan

docs2/pages/documentations/audit.md

@@ -65,6 +65,7 @@ var task = ctx.Countries.Where(x => x.IsActive).FromCacheAsync();
 var task = ctx.States.Where(x => x.IsActive).FromCacheAsync(DateTime.Now.AddHours(2));
 
 ```
+[Try it in EF6](https://dotnetfiddle.net/Uh9miZ) | [Try it in EF Core](https://dotnetfiddle.net/U9pU1a)
 
 ## EF+ Query Cache Query Deferred
 

docs2/pages/documentations/query-cache.md

@@ -111,6 +111,7 @@ var countDeferred = ctx.Customers.DeferredCount();
 var taskCount = countDeferred.ExecuteAsync();
 
 ```
+[Try it in EF6](https://dotnetfiddle.net/0BpVn1) | [Try it in EF Core](https://dotnetfiddle.net/1pttmj)
 
 ## Real Life Scenarios
 
@@ -121,7 +122,6 @@ EF Query Deferred brings advantages to other third party features:
  - Allows to use Immediate Method with YOUR own features.
 
 ## Behind the code
-
 When a deferred method is used, the query expression is created exactly like a non-deferred method but instead of invoking the execute method from the query provider, a new instance of a class QueryDeferred<TResult> is created using the query and the expression.
 
 The QueryDeferred instance has methods to either execute the expression from the query provider or let a third party library use the object query.

docs2/pages/documentations/query-deferred.md

@@ -0,0 +1,76 @@
+# Audit
+
+## Introduction
+
+Entity Framework Core saves entities in a database but doesn't let you easily track changes, for example, a history of all modifications and their author in an audit table.
+
+**EF+ Audit** easily tracks changes, exclude/include entity or property and auto save audit entries in the database.
+
+
+{% include template-example.html %} 
+```csharp
+
+// using Z.EntityFramework.Plus; // Don't forget to include this.
+
+var ctx = new EntityContext();
+// ... ctx changes ...
+
+var audit = new Audit();
+audit.CreatedBy = "ZZZ Projects"; // Optional
+ctx.SaveChanges(audit);
+
+// Access to all auditing information
+var entries = audit.Entries;
+foreach(var entry in entries)
+{
+    foreach(var property in entry.Properties)
+    {
+    }
+}
+
+```
+[Try it](https://dotnetfiddle.net/dc7v3W)
+
+## Scenarios
+
+ - [AutoSave](scenarios/ef-core-audit-autosave.md)
+ - [Data Annotations](scenarios/ef-core-audit-data-annotations.md)
+ - [Exclude & Include Entity](scenarios/ef-core-audit-exclude-include-entity.md)
+ - [Exclude & Include Property](scenarios/ef-core-audit-exclude-include-property.md)
+ - [Format Value](scenarios/ef-core-audit-format-value.md)
+ - [Ignore Events](scenarios/ef-core-audit-ignore-events.md)
+ - [Property Unchanged](scenarios/ef-core-audit-property-unchanged.md)
+ - [Soft Add & Soft Delete](scenarios/ef-core-audit-soft-add-soft-delete.md)
+ - [Retrieve AuditEntries for specific item](scenarios/ef-core-audit-retrieve-audit-entries-for-specific-item.md)
+ - [Audit Customization](scenarios/ef-core-audit-customization.md)
+ - [Audit + Entity Framework Extensions](scenarios/ef-core-audit-ef-extensions.md)
+ 
+## Limitations
+
+  - **DO NOT** support relationship
+  - **DO NOT** populate EntitySetName value
+
+## Requirements
+
+ - **EF+ Audit:** Full version or Standalone version
+ - **Database Provider:** All supported
+ - **Entity Framework Core Version:** EFCore 1.0+
+ - **Minimum Framework Version:** .NET Core 1.0
+
+## Troubleshooting
+
+Why only my key is added when updating my entity?
+
+This issue often happens for MVC user. They create a new entity through HttpPost values and force the state to "Modified", the context is not aware of the original value and use the current value instead. So, every property has the original value == current value and our auditing only log the key since all other values are equals.
+
+We recommend setting the **IgnorePropertyUnchanged **to false to log every property.
+
+Here is an example of this issue: [Issues #8](https://github.com/zzzprojects/EntityFramework-Plus/issues/8)
+
+## Conclusion
+
+**Auditing** in Entity Framework Core could not be simpler, there are always some entities in an application where an audit table can be crucial to keep track of what's happening, and you now have access to an easy to use library for these situations.
+
+Need help getting started? [[email protected]](mailto:[email protected])
+
+We welcome all comments, ideas and suggestions to improve our library.

docs2/pages/ef-core-docs/documentations/ef-core-audit.md

@@ -0,0 +1,224 @@
+# AutoSave Audit
+
+## Problem
+
+You need to automatically save audit entries in the database to keep a history in an audit table.
+
+## Solution
+
+If an action for the property **AutoSavePreAction** is set, audit entries will automatically be saved in the database when **SaveChanges** or **SaveChangesAsync** methods are called.
+
+***By using EF+ Audit entity***
+
+{% include template-example.html %} 
+```csharp
+
+public class EntityContext : DbContext
+{
+   // ... context code ...
+   public DbSet<AuditEntry> AuditEntries { get; set; }
+   public DbSet<AuditEntryProperty> AuditEntryProperties { get; set; }
+
+   static EntityContext()
+   {
+      AuditManager.DefaultConfiguration.AutoSavePreAction = (context, audit) =>
+         // ADD "Where(x => x.AuditEntryID == 0)" to allow multiple SaveChanges with same Audit
+         (context as EntityContext).AuditEntries.AddRange(audit.Entries);
+   }
+}
+
+var audit = new Audit();
+audit.CreatedBy = "ZZZ Projects"; // Optional
+ctx.SaveChanges(audit);
+
+```
+[Try it](https://dotnetfiddle.net/wi8men)
+
+***By using a different context***
+
+{% include template-example.html %} 
+```csharp
+
+public class OracleContext : DbContext
+{
+   // ... context code ...
+}
+
+public class SqlServerContext : DbContext
+{
+   // ... context code ...
+   public DbSet<AuditEntry> AuditEntries { get; set; }
+   public DbSet<AuditEntryProperty> AuditEntryProperties { get; set; }
+}
+
+AuditManager.DefaultConfiguration.AutoSavePreAction = (context, audit) =>
+{
+	var sqlServerContext = new SqlServerContext();
+	sqlServerContext.AuditEntries.AddRange(audit.Entries);
+	sqlServerContext.SaveChanges();
+};
+
+var audit = new Audit();
+audit.CreatedBy = "ZZZ Projects"; // Optional
+oracleContext.SaveChanges(audit);
+
+```
+[Try it](https://dotnetfiddle.net/RZeTZq)
+
+***Custom AuditEntry & Database First Approach***
+
+{% include template-example.html %} 
+```csharp
+
+AuditManager.DefaultConfiguration.AutoSavePreAction = (context, audit) =>
+{
+    // ADD "Where(x => x.AuditEntryID == 0)" to allow multiple SaveChanges with same Audit
+	var customAuditEntries = audit.Entries.Select(x => Import(x));
+	(context as Entities).AuditEntries.AddRange(customAuditEntries);
+};
+
+using (var ctx = new Entities())
+{
+    Audit audit = new Audit();
+    audit.CreatedBy = "ZZZ Projects"; // Optional
+
+    ctx.Entity_Basic.Add(new Entity_Basic() {ColumnInt = 2});
+    ctx.SaveChanges(audit);
+}
+
+public Static AuditEntry Import(Z.EntityFramework.Plus.AuditEntry entry)
+{
+    var customAuditEntry = new AuditEntry
+    {
+        EntitySetName = entry.EntitySetName,
+        EntityTypeName = entry.EntityTypeName,
+        State = (int)entry.State,
+        StateName = entry.StateName,
+        CreatedBy = entry.CreatedBy,
+        CreatedDate = entry.CreatedDate
+    };
+
+    customAuditEntry.AuditEntryProperties = entry.Properties.Select(x => Import(x)).ToList();
+
+    return customAuditEntry;
+}
+
+public Static AuditEntryProperty Import(Z.EntityFramework.Plus.AuditEntryProperty property)
+{
+    var customAuditEntry = new AuditEntryProperty
+    {
+        RelationName = property.RelationName,
+        PropertyName = property.PropertyName,
+        OldValue = property.OldValueFormatted,
+        NewValue = property.NewValueFormatted
+    };
+
+    return customAuditEntry;
+}
+
+```
+[Try it](https://dotnetfiddle.net/JRiebw)
+
+***Saving automatically by overriding SaveChanges & SaveChangesAsync***
+
+{% include template-example.html %} 
+```csharp
+
+AuditManager.DefaultConfiguration.AutoSavePreAction = (context, audit) =>
+    // ADD "Where(x => x.AuditEntryID == 0)" to allow multiple SaveChanges with same Audit
+   (context as TestContext).AuditEntries.AddRange(audit.Entries);
+	
+public class EntityContext : DbContext
+{
+	// ... context code ...
+	
+	public override int SaveChanges()
+	{
+		var audit = new Audit();
+		audit.PreSaveChanges(this);
+		var rowAffecteds = base.SaveChanges();
+		audit.PostSaveChanges();
+
+		if (audit.Configuration.AutoSavePreAction != null)
+		{
+			audit.Configuration.AutoSavePreAction(this, audit);
+			base.SaveChanges();
+		}
+
+		return rowAffecteds;
+	}
+
+	public override Task<int> SaveChangesAsync()
+	{
+		return SaveChangesAsync(CancellationToken.None);
+	}
+
+	public override async Task<int> SaveChangesAsync(CancellationToken cancellationToken)
+	{
+		var audit = new Audit();
+		audit.PreSaveChanges(this);
+		var rowAffecteds = await base.SaveChangesAsync(cancellationToken).ConfigureAwait(false);
+		audit.PostSaveChanges();
+
+		if (audit.Configuration.AutoSavePreAction != null)
+		{
+			audit.Configuration.AutoSavePreAction(this, audit);
+			await base.SaveChangesAsync(cancellationToken).ConfigureAwait(false);
+		}
+
+		return rowAffecteds;
+	}
+}
+
+using(var ctx = new EntityContext())
+{
+	// ... code ...
+	ctx.SaveChanges();
+}
+
+```
+[Try it](https://dotnetfiddle.net/FtG10X)
+
+***SQL Script (for Database First)***
+
+{% include template-example.html %} 
+```csharp
+
+CREATE TABLE [dbo].[AuditEntries] (
+    [AuditEntryID] [int] NOT NULL IDENTITY,
+    [EntitySetName] [nvarchar](255),
+    [EntityTypeName] [nvarchar](255),
+    [State] [int] NOT NULL,
+    [StateName] [nvarchar](255),
+    [CreatedBy] [nvarchar](255),
+    [CreatedDate] [datetime] NOT NULL,
+    CONSTRAINT [PK_dbo.AuditEntries] PRIMARY KEY ([AuditEntryID])
+)
+
+GO
+
+CREATE TABLE [dbo].[AuditEntryProperties] (
+    [AuditEntryPropertyID] [int] NOT NULL IDENTITY,
+    [AuditEntryID] [int] NOT NULL,
+    [RelationName] [nvarchar](255),
+    [PropertyName] [nvarchar](255),
+    [OldValue] [nvarchar](max),
+    [NewValue] [nvarchar](max),
+    CONSTRAINT [PK_dbo.AuditEntryProperties] PRIMARY KEY ([AuditEntryPropertyID])
+)
+
+GO
+
+CREATE INDEX [IX_AuditEntryID] ON [dbo].[AuditEntryProperties]([AuditEntryID])
+
+GO
+
+ALTER TABLE [dbo].[AuditEntryProperties] 
+ADD CONSTRAINT [FK_dbo.AuditEntryProperties_dbo.AuditEntries_AuditEntryID] 
+FOREIGN KEY ([AuditEntryID])
+REFERENCES [dbo].[AuditEntries] ([AuditEntryID])
+ON DELETE CASCADE
+
+GO
+
+```