Merge pull request #1934 from Danielle9897/RDoc-3607-overridingAsyncD…

…ocumentIdGenerator RDoc-3066 (GenerateDocumentIdAsync) + RDoc-3067 (AsyncDocumentIdGenerator)
ravendb · Oct 29, 2024 · b40acc0 · b40acc0
2 parents 5b7e8dc + b56cdec
commit b40acc0
Show file tree

Hide file tree

Showing 18 changed files with 663 additions and 163 deletions.
diff --git a/Documentation/3.0/Raven.Documentation.Pages/client-api/document-identifiers/.docs.json b/Documentation/3.0/Raven.Documentation.Pages/client-api/document-identifiers/.docs.json
@@ -1,31 +1,31 @@
 [
-  {
-    "Path": "working-with-document-ids.markdown",
-    "Name": "Working with document ids",
-    "DiscussionId": "691ee493-f813-42eb-90d1-c5634efabd48",
-    "Mappings": [
-      {
-        "Version": 1.0,
-        "Key": "client-api/basic-operations/saving-new-document#document-ids"
-      }
-    ]
-  },
-  {
-    "Path": "hilo-algorithm.markdown",
-    "Name": "HiLo algorithm",
-    "DiscussionId": "96f4b9ea-12d1-4744-95e0-8b88da38543c",
-    "Mappings": []
-  },
-  {
-    "Path": "beware-of.markdown",
-    "Name": "Beware of ...",
-    "DiscussionId": "b62dc188-4d1f-4745-9acd-72983c036c90",
-    "Mappings": []
-  },
-  {
-    "Path": "handling-case-sensitive-document-ids.markdown",
-    "Name": "Handling case sensitive document IDs",
-    "DiscussionId": "bef2ca24-1003-45ce-848d-093beff6b3aa",
-    "Mappings": []
-  }
-]
+    {
+        "Path": "working-with-document-ids.markdown",
+        "Name": "Working with document ids",
+        "DiscussionId": "691ee493-f813-42eb-90d1-c5634efabd48",
+        "Mappings": [
+            {
+                "Version": 1.0,
+                "Key": "client-api/basic-operations/saving-new-document#document-ids"
+            }
+        ]
+    },
+    {
+        "Path": "hilo-algorithm.markdown",
+        "Name": "HiLo algorithm",
+        "DiscussionId": "c6aab86a-cdd8-42b5-8eb0-68afea4d875e",
+        "Mappings": []
+    },
+    {
+        "Path": "beware-of.markdown",
+        "Name": "Beware of ...",
+        "DiscussionId": "b62dc188-4d1f-4745-9acd-72983c036c90",
+        "Mappings": []
+    },
+    {
+        "Path": "handling-case-sensitive-document-ids.markdown",
+        "Name": "Handling case sensitive document IDs",
+        "DiscussionId": "bef2ca24-1003-45ce-848d-093beff6b3aa",
+        "Mappings": []
+    }
+]
diff --git a/Documentation/3.5/Raven.Documentation.Pages/client-api/document-identifiers/.docs.json b/Documentation/3.5/Raven.Documentation.Pages/client-api/document-identifiers/.docs.json
@@ -1,31 +1,31 @@
 [
-  {
-    "Path": "working-with-document-ids.markdown",
-    "Name": "Working with document ids",
-    "DiscussionId": "805abab3-a9ae-4e0d-914e-596b708aeb34",
-    "Mappings": [
-      {
-        "Version": 1.0,
-        "Key": "client-api/basic-operations/saving-new-document#document-ids"
-      }
-    ]
-  },
-  {
-    "Path": "hilo-algorithm.markdown",
-    "Name": "HiLo algorithm",
-    "DiscussionId": "c377ddda-37b8-4dac-8336-f6583dbbf837",
-    "Mappings": []
-  },
-  {
-    "Path": "beware-of.markdown",
-    "Name": "Beware of ...",
-    "DiscussionId": "68972493-e44e-4cc2-ae10-72ee3a530cf7",
-    "Mappings": []
-  },
-  {
-    "Path": "handling-case-sensitive-document-ids.markdown",
-    "Name": "Handling case sensitive document IDs",
-    "DiscussionId": "d7fd6e9d-8d70-4c56-83e5-4c4190a89195",
-    "Mappings": []
-  }
-]
+    {
+        "Path": "working-with-document-ids.markdown",
+        "Name": "Working with document ids",
+        "DiscussionId": "805abab3-a9ae-4e0d-914e-596b708aeb34",
+        "Mappings": [
+            {
+                "Version": 1.0,
+                "Key": "client-api/basic-operations/saving-new-document#document-ids"
+            }
+        ]
+    },
+    {
+        "Path": "hilo-algorithm.markdown",
+        "Name": "HiLo algorithm",
+        "DiscussionId": "32648b27-5059-4e40-9ab5-c2e5780df89e",
+        "Mappings": []
+    },
+    {
+        "Path": "beware-of.markdown",
+        "Name": "Beware of ...",
+        "DiscussionId": "68972493-e44e-4cc2-ae10-72ee3a530cf7",
+        "Mappings": []
+    },
+    {
+        "Path": "handling-case-sensitive-document-ids.markdown",
+        "Name": "Handling case sensitive document IDs",
+        "DiscussionId": "d7fd6e9d-8d70-4c56-83e5-4c4190a89195",
+        "Mappings": []
+    }
+]
diff --git a/Documentation/4.0/Raven.Documentation.Pages/client-api/document-identifiers/.docs.json b/Documentation/4.0/Raven.Documentation.Pages/client-api/document-identifiers/.docs.json
@@ -1,19 +1,19 @@
 [
-  {
-    "Path": "working-with-document-identifiers.markdown",
-    "Name": "Working with Document Identifiers",
-    "DiscussionId": "9f992cac-82ee-4395-8f63-62e6938ec031",
-    "Mappings": [
-      {
-        "Version": 3.5,
-        "Key": "client-api/document-identifiers/working-with-document-ids"
-      }
-    ]
-  },
-  {
-    "Path": "hilo-algorithm.markdown",
-    "Name": "HiLo Algorithm",
-    "DiscussionId": "cc329253-5159-4a41-a95a-fe156eefd76e",
-    "Mappings": []
-  }
-]
+    {
+        "Path": "working-with-document-identifiers.markdown",
+        "Name": "Working with Document Identifiers",
+        "DiscussionId": "9f992cac-82ee-4395-8f63-62e6938ec031",
+        "Mappings": [
+            {
+                "Version": 3.5,
+                "Key": "client-api/document-identifiers/working-with-document-ids"
+            }
+        ]
+    },
+    {
+        "Path": "hilo-algorithm.markdown",
+        "Name": "HiLo Algorithm",
+        "DiscussionId": "c8e7a51c-ec9b-49cd-a464-2e85f3b3d760",
+        "Mappings": []
+    }
+]
diff --git a/Documentation/4.1/Raven.Documentation.Pages/client-api/document-identifiers/.docs.json b/Documentation/4.1/Raven.Documentation.Pages/client-api/document-identifiers/.docs.json
@@ -0,0 +1,14 @@
+[
+    {
+        "Path": "working-with-document-identifiers.markdown",
+        "Name": "Working with Document Identifiers",
+        "DiscussionId": "f3115d3f-7faa-4cd5-9581-1c56153f51a9",
+        "Mappings": []
+    },
+    {
+        "Path": "hilo-algorithm.markdown",
+        "Name": "HiLo algorithm",
+        "DiscussionId": "c8e7a51c-ec9b-49cd-a464-2e85f3b3d760",
+        "Mappings": []
+    }
+]
diff --git a/Documentation/4.2/Raven.Documentation.Pages/client-api/document-identifiers/.docs.json b/Documentation/4.2/Raven.Documentation.Pages/client-api/document-identifiers/.docs.json
@@ -1,8 +1,14 @@
 [
-  {
-    "Path": "working-with-document-identifiers.markdown",
-    "Name": "Working with Document Identifiers",
-    "DiscussionId": "f3115d3f-7faa-4cd5-9581-1c56153f51a9",
-    "Mappings": []
-  }
-]
+    {
+        "Path": "working-with-document-identifiers.markdown",
+        "Name": "Working with Document Identifiers",
+        "DiscussionId": "f3115d3f-7faa-4cd5-9581-1c56153f51a9",
+        "Mappings": []
+    },
+    {
+        "Path": "hilo-algorithm.markdown",
+        "Name": "HiLo algorithm",
+        "DiscussionId": "c8e7a51c-ec9b-49cd-a464-2e85f3b3d760",
+        "Mappings": []
+    }
+]
diff --git a/Documentation/5.0/Raven.Documentation.Pages/client-api/document-identifiers/.docs.json b/Documentation/5.0/Raven.Documentation.Pages/client-api/document-identifiers/.docs.json
@@ -1,14 +1,14 @@
 [
-  {
-    "Path": "working-with-document-identifiers.markdown",
-    "Name": "Working with Document Identifiers",
-    "DiscussionId": "f3115d3f-7faa-4cd5-9581-1c56153f51a9",
-    "Mappings": []
-  },
-  {
-    "Path": "hilo-algorithm.markdown",
-    "Name": "HiLo Algorithm",
-    "DiscussionId": "cc329253-5159-4a41-a95a-fe156eefd76e",
-    "Mappings": []
-  }
+    {
+        "Path": "working-with-document-identifiers.markdown",
+        "Name": "Working with Document Identifiers",
+        "DiscussionId": "f3115d3f-7faa-4cd5-9581-1c56153f51a9",
+        "Mappings": []
+    },
+    {
+        "Path": "hilo-algorithm.markdown",
+        "Name": "HiLo algorithm",
+        "DiscussionId": "73f50d9f-6720-412b-8ac5-0c9e87462f01",
+        "Mappings": []
+    }
 ]
diff --git a/Documentation/5.1/Raven.Documentation.Pages/client-api/document-identifiers/.docs.json b/Documentation/5.1/Raven.Documentation.Pages/client-api/document-identifiers/.docs.json
@@ -1,8 +1,14 @@
 [
-  {
-    "Path": "working-with-document-identifiers.markdown",
-    "Name": "Working with Document Identifiers",
-    "DiscussionId": "f3115d3f-7faa-4cd5-9581-1c56153f51a9",
-    "Mappings": []
-  }
-]
+    {
+        "Path": "working-with-document-identifiers.markdown",
+        "Name": "Working with Document Identifiers",
+        "DiscussionId": "f3115d3f-7faa-4cd5-9581-1c56153f51a9",
+        "Mappings": []
+    },
+    {
+        "Path": "hilo-algorithm.markdown",
+        "Name": "HiLo algorithm",
+        "DiscussionId": "73f50d9f-6720-412b-8ac5-0c9e87462f01",
+        "Mappings": []
+    }
+]
diff --git a/Documentation/5.2/Raven.Documentation.Pages/client-api/document-identifiers/.docs.json b/Documentation/5.2/Raven.Documentation.Pages/client-api/document-identifiers/.docs.json
@@ -1,14 +1,14 @@
 [
-  {
-    "Path": "working-with-document-identifiers.markdown",
-    "Name": "Working with Document Identifiers",
-    "DiscussionId": "f3115d3f-7faa-4cd5-9581-1c56153f51a9",
-    "Mappings": []
-  },
-  {
-    "Path": "hilo-algorithm.markdown",
-    "Name": "HiLo Algorithm",
-    "DiscussionId": "cc329253-5159-4a41-a95a-fe156eefd76e",
-    "Mappings": []
-  }
+    {
+        "Path": "working-with-document-identifiers.markdown",
+        "Name": "Working with Document Identifiers",
+        "DiscussionId": "f3115d3f-7faa-4cd5-9581-1c56153f51a9",
+        "Mappings": []
+    },
+    {
+        "Path": "hilo-algorithm.markdown",
+        "Name": "HiLo Algorithm",
+        "DiscussionId": "34ff3367-c155-4af9-8fa5-4ed517efc5e5",
+        "Mappings": []
+    }
 ]
diff --git a/Documentation/5.3/Raven.Documentation.Pages/client-api/document-identifiers/.docs.json b/Documentation/5.3/Raven.Documentation.Pages/client-api/document-identifiers/.docs.json
@@ -1,8 +1,14 @@
 [
-  {
-    "Path": "working-with-document-identifiers.markdown",
-    "Name": "Working with Document Identifiers",
-    "DiscussionId": "f3115d3f-7faa-4cd5-9581-1c56153f51a9",
-    "Mappings": []
-  }
-]
+    {
+        "Path": "working-with-document-identifiers.markdown",
+        "Name": "Working with Document Identifiers",
+        "DiscussionId": "f3115d3f-7faa-4cd5-9581-1c56153f51a9",
+        "Mappings": []
+    },
+    {
+        "Path": "hilo-algorithm.markdown",
+        "Name": "HiLo algorithm",
+        "DiscussionId": "34ff3367-c155-4af9-8fa5-4ed517efc5e5",
+        "Mappings": []
+    }
+]
diff --git a/.../Raven.Documentation.Pages/client-api/configuration/conventions.dotnet.markdown b/.../Raven.Documentation.Pages/client-api/configuration/conventions.dotnet.markdown
@@ -2,14 +2,15 @@
 
 {NOTE: }
 
-* __Conventions__ in RavenDB are customizable settings that users can configure to tailor client behaviors according to their preferences.
+* **Conventions** in RavenDB are customizable settings that users can configure to tailor client behaviors according to their preferences.
 
 * In this page:  
   * [How to set conventions](../../client-api/configuration/conventions#how-to-set-conventions)  
   * [Conventions:](../../client-api/configuration/conventions#conventions:)  
       [AddIdFieldToDynamicObjects](../../client-api/configuration/conventions#addidfieldtodynamicobjects)  
       [AggressiveCache.Duration](../../client-api/configuration/conventions#aggressivecache.duration)  
       [AggressiveCache.Mode](../../client-api/configuration/conventions#aggressivecache.mode)  
+      [AsyncDocumentIdGenerator](../../client-api/configuration/conventions#asyncdocumentidgenerator)  
       [CreateHttpClient](../../client-api/configuration/conventions#createhttpclient)  
       [DisableAtomicDocumentWritesInClusterWideTransaction](../../client-api/configuration/conventions#disableatomicdocumentwritesinclusterwidetransaction)  
       [DisableTcpCompression](../../client-api/configuration/conventions#disabletcpcompression)  
@@ -115,6 +116,24 @@
 {NOTE/}
 {NOTE: }
 
+#### AsyncDocumentIdGenerator
+
+---
+
+* Use the `AsyncDocumentIdGenerator` convention to define the document ID generator method that will be used when storing a document without explicitly specifying its `Id`.
+
+* You can override this global ID generator for specific object types using the [RegisterAsyncIdConvention](../../client-api/configuration/identifier-generation/type-specific) convention.
+
+* DEFAULT:  
+  The default document ID generator is the `GenerateDocumentIdAsync` method, which is part of the `HiLoIdGenerator` object within the _DocumentStore_.
+  This method implements the [HiLo algorithm](../../client-api/document-identifiers/hilo-algorithm) to ensure efficient ID generation when storing a document without explicitly specifying its `Id`.
+
+{CODE AsyncDocumentIdGenerator@ClientApi\Configuration\Conventions.cs /}
+{CODE AsyncDocumentIdGeneratorSyntax@ClientApi\Configuration\Conventions.cs /}
+
+{NOTE/}
+{NOTE: }
+
 #### CreateHttpClient
 
 ---
@@ -123,7 +142,7 @@
 
 * For example, implementing your own HTTP client can be useful when you'd like your clients to provide the server with tracing info.  
 
-* If you override the default `CreateHttpClient` convention we advise that you also set the HTTP client type  
+* If you override the default `CreateHttpClient` convention we advise that you also set the HTTP client type
   correctly using the [HttpClientType](../../client-api/configuration/conventions#httpclienttype) convention.
 
 {CODE CreateHttpClient@ClientApi\Configuration\Conventions.cs /}
@@ -173,9 +192,9 @@
 * This behavior can be disabled when setting the `DisableTopologyCache` convention to `true`.  
   In such a case:
 
-   * The client will not load the topology from the cache upon failing to connect to a server.  
-   * Even if the client is configured to [receive topology updates](../../client-api/configuration/conventions#disabletopologyupdates) from the server, no topology files will be saved on disk,  
-     thus preventing the accumulation of these files.
+    * The client will not load the topology from the cache upon failing to connect to a server.
+    * Even if the client is configured to [receive topology updates](../../client-api/configuration/conventions#disabletopologyupdates) from the server,
+      no topology files will be saved on disk, thus preventing the accumulation of these files.
 
 * DEFAULT: `false`
 
@@ -290,7 +309,7 @@
 
 ---
 
-* Use the `FindIdentityPropertyNameFromCollectionName` convention to define a function that customizes  
+* Use the `FindIdentityPropertyNameFromCollectionName` convention to define a function that customizes
   the entity's ID property from the collection name.
 
 * DEFAULT: Will use the `Id` property.

diff --git a/Documentation/5.4/Raven.Documentation.Pages/client-api/document-identifiers/.docs.json b/Documentation/5.4/Raven.Documentation.Pages/client-api/document-identifiers/.docs.json
@@ -1,8 +1,14 @@
 [
-  {
-    "Path": "working-with-document-identifiers.markdown",
-    "Name": "Working with Document Identifiers",
-    "DiscussionId": "f3115d3f-7faa-4cd5-9581-1c56153f51a9",
-    "Mappings": []
-  }
-]
+    {
+        "Path": "working-with-document-identifiers.markdown",
+        "Name": "Working with Document Identifiers",
+        "DiscussionId": "f3115d3f-7faa-4cd5-9581-1c56153f51a9",
+        "Mappings": []
+    },
+    {
+        "Path": "hilo-algorithm.markdown",
+        "Name": "HiLo algorithm",
+        "DiscussionId": "4013b9b5-502b-4d79-b9b8-cefb79870ebb",
+        "Mappings": []
+    }
+]