From a264ad2f17d7373cdc5b2e854aafc969400fdfce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Halil=20=C4=B0brahim=20Kalkan?= <hi_kalkan@yahoo.com>
Date: Thu, 16 Jan 2020 16:25:09 +0300
Subject: [PATCH] Add IAuditLogScope & IAuditingManager section.

---
 docs/en/Ambient-Context-Pattern.md |  3 ++
 docs/en/Audit-Logging.md           | 78 ++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+)
 create mode 100644 docs/en/Ambient-Context-Pattern.md

diff --git a/docs/en/Ambient-Context-Pattern.md b/docs/en/Ambient-Context-Pattern.md
new file mode 100644
index 0000000000..d00a721ce2
--- /dev/null
+++ b/docs/en/Ambient-Context-Pattern.md
@@ -0,0 +1,3 @@
+## Ambient Context Pattern
+
+TODO
\ No newline at end of file
diff --git a/docs/en/Audit-Logging.md b/docs/en/Audit-Logging.md
index 7e0f358a16..642d118983 100644
--- a/docs/en/Audit-Logging.md
+++ b/docs/en/Audit-Logging.md
@@ -287,6 +287,84 @@ Configure<AbpAuditingOptions>(options =>
 });
 ````
 
+## IAuditLogScope & IAuditingManager
+
+This section explains the `IAuditLogScope` & `IAuditingManager` services for advanced use cases.
+
+An **audit log scope** is an [ambient scope](Ambient-Context-Pattern.md) that **builds** and **saves** an audit log object (explained before). By default, an audit log scope is created for a web request by the Audit Log Middleware (see `UseAuditing()` section above).
+
+### Access to the Current Audit Log Scope
+
+Audit log contributors, was explained above, is a global way of manipulating the audit log object. It is good if you can get a value from a service.
+
+If you need to manipulate the audit log object in an arbitrary point of your application, you can access to the current audit log scope and get the current audit log object (independent of how the scope is managed). Example:
+
+````csharp
+public class MyService : ITransientDependency
+{
+    private readonly IAuditingManager _auditingManager;
+
+    public MyService(IAuditingManager auditingManager)
+    {
+        _auditingManager = auditingManager;
+    }
+
+    public async Task DoItAsync()
+    {
+        var currentAuditLogScope = _auditingManager.Current;
+        if (currentAuditLogScope != null)
+        {
+            currentAuditLogScope.Log.Comments.Add(
+                "Executed the MyService.DoItAsync method :)"
+            );
+            
+            currentAuditLogScope.Log.SetProperty("MyCustomProperty", 42);
+        }
+    }
+}
+````
+
+Always check if `_auditingManager.Current` is null or not, because it is controlled in an outer scope and you can't know if an audit log scope was created before calling your method.
+
+### Manually Create an Audit Log Scope
+
+You rarely need to create a manual audit log scope, but if you need, you can create an audit log scope using the `IAuditingManager` as like in the following example:
+
+````csharp
+public class MyService : ITransientDependency
+{
+    private readonly IAuditingManager _auditingManager;
+
+    public MyService(IAuditingManager auditingManager)
+    {
+        _auditingManager = auditingManager;
+    }
+
+    public async Task DoItAsync()
+    {
+        using (var auditingScope = _auditingManager.BeginScope())
+        {
+            try
+            {
+                //Call other services...
+            }
+            catch (Exception ex)
+            {
+                //Add exceptions
+                _auditingManager.Current.Log.Exceptions.Add(ex);
+            }
+            finally
+            {
+                //Always save the log
+                await auditingScope.SaveAsync();
+            }
+        }
+    }
+}
+````
+
+You can call other services, they may call others, they may change entities and so on. All these interactions are saved as a single audit log object in the finally block.
+
 ## The Audit Logging Module
 
 The Audit Logging Module basically implements the `IAuditingStore` to save the audit log objects to a database. It supports multiple database providers. This module is added to the startup templates by default.