Merge pull request #7286 from umbraco/cms/database-availability-checks

16.2 Updates: Added details of abstractions of database availability checks, JSON serialization encoder creation and UseStrictDomainMatching option

Author: sofietoft

16/umbraco-cms/SUMMARY.md

@@ -424,6 +424,8 @@
 * [Custom Swagger API](reference/custom-swagger-api.md)
 * [Umbraco Flavored Markdown](reference/umbraco-flavored-markdown.md)
 * [Content Type Filters](reference/content-type-filters.md)
+* [Database Availability Checks](reference/database-availability.md)
+* [JSON Serialization](reference/json-serialization.md)
 
 ## Tutorials
 

16/umbraco-cms/reference/configuration/cache-settings.md

@@ -56,29 +56,31 @@ The `ContentTypeKeys` setting specifies which Document Types should be seeded in
 }
 ```
 
-### DocumentBreadthFirstSeedCount
+### DocumentBreadthFirstSeedCount and MediaBreadthFirstSeedCount
 
-The `DocumentBreadthFirstSeedCount` setting specifies how many documents should be seeded into the cache when doing a breadth-first traversal. The default value is 100.
+The `DocumentBreadthFirstSeedCount` setting specifies how many documents should be seeded into the cache when doing a breadth-first traversal. `MediaBreadthFirstSeedCount` provides the same for media. The default value for both is 100.
 
 ```json
 "Umbraco": {
   "CMS": {
     "Cache": {
-      "DocumentBreadthFirstSeedCount": 500
+      "DocumentBreadthFirstSeedCount": 500,
+      "MediaBreadthFirstSeedCount": 500
     }
   }
 }
 ```
 
-## MediaBreadthFirstSeedCount
+## DocumentSeedBatchSize and MediaSeedBatchSize
 
-The `MediaBreadthFirstSeedCount` setting specifies how many media items should be seeded into the cache when doing a breadth-first traversal. The default value is 100.
+When populating the cache on startup the content keys defined by the seeding strategy are processed in batches. The batch size for documents and media can be modified via the `DocumentSeedBatchSize` and `MediaSeedBatchSize` respectively. The default value for both is 100.
 
 ```json
 "Umbraco": {
   "CMS": {
     "Cache": {
-      "MediaBreadthFirstSeedCount": 500
+      "DocumentSeedBatchSize": 500,
+      "MediaSeedBatchSize": 500
     }
   }
 }

16/umbraco-cms/reference/configuration/webroutingsettings.md

@@ -20,7 +20,8 @@ An example of a web routing config with default values, and a placeholder for th
       "DisableFindContentByIdPath": false,
       "DisableRedirectUrlTracking": false,
       "UrlProviderMode": "Auto",
-      "UmbracoApplicationUrl": "http://www.mysite.com/"
+      "UmbracoApplicationUrl": "http://www.mysite.com/",
+      "UseStrictDomainMatching": false
     }
   }
 }
@@ -104,3 +105,14 @@ Defines the Umbraco application URL that the server should reach itself. By defa
 {% hint style="info" %}
 Previously before v9, it was required to specify **backofffice** path as this was customizable (`/umbraco` by default). However, from v9+ this is no longer possible, so it's sufficient to use the URL that contains the scheme (http/https) and complete hostname.
 {% endhint %}
+
+## Strict domain matching
+
+With multi-site setups multiple root nodes will be prepared with assigned domains. When routing a request, the content matched by path below the root node that matches the domain is returned.
+
+A request may be received on an unrecognized domain that otherwise matches by path to a content item. By default Umbraco will route this item.
+
+With `UseStrictDomainMatching` set to `true`, the request will only be routed if the domain as well as the path matches.
+
+Why use this? It's possible to receive requests on domains that are configured on web server but aren't setup as domains in Umbraco. The Azure web app default domain is an example of this. By switching this option on, requests that come in on that domain will no longer be routed.
+

16/umbraco-cms/reference/database-availability.md

@@ -0,0 +1,45 @@
+---
+description: Describes the checks Umbraco will do on startup to determine the availability of the database, and how this behavior can be customized.
+---
+
+# Database Availability Checks
+
+When Umbraco boots it will check for a configured database and, if found, verify that a connection can be made.
+
+The default behavior is to check five times with a one second delay between attempts. If, after that, a connection cannot be established, Umbraco will fail with a `BootFailedException`.
+
+## Implementing Custom Behavior
+
+For projects in development with the potential for misconfigured database settings, this is likely a reasonable approach to take.
+
+In production, when you have stable configuration, you may prefer to override the behavior to better handle cases where your hosting infrastructure might restart.
+
+We support this by abstracting the default behavior behind the `IDatabaseAvailabilityCheck` interface found in the `Umbraco.Cms.Infrastructure.Persistence` namespace.
+
+You can implement your own version of this interface and register it via a composer. This is shown in the following, stub example:
+
+```csharp
+using Umbraco.Cms.Core.Composing;
+using Umbraco.Cms.Infrastructure.Persistence;
+
+public class MyDatabaseAvailabilityCheckComposer : IComposer
+{
+    public void Compose(IUmbracoBuilder builder)
+    {
+        builder.Services.AddUnique<IDatabaseAvailabilityCheck, MyDatabaseAvailabilityCheck>();
+    }
+}
+
+internal class MyDatabaseAvailabilityCheck : IDatabaseAvailabilityCheck
+{
+    public bool IsDatabaseAvailable(IUmbracoDatabaseFactory databaseFactory)
+    {
+        // Provide your custom logic to check database availability, wait as required, and return true once a connection is established.
+        return true;
+    }
+}
+
+```
+
+For reference and inspiration, the default implementation can be found [in the Umbraco CMS source code](https://github.com/umbraco/Umbraco-CMS/blob/main/src/Umbraco.Infrastructure/Persistence/DefaultDatabaseAvailabilityCheck.cs).
+

16/umbraco-cms/reference/json-serialization.md

@@ -0,0 +1,48 @@
+---
+description: Describes how the JSON serialization within Umbraco can be customized.
+---
+
+# JSON Serialization
+
+Umbraco uses JSON as a format to serialize information to the database and for output. For example, the configuration of data types and the property values of complex editors are serialized to JSON for persistence.
+
+The serializers within Umbraco uses a `JavascriptEncoder` which only considers basic latin characters as unnecessary to encode.
+
+## Implementing Custom Behavior
+
+For projects making use of non-Latin characters you may want to amend this behavior. By doing so you can reduce the space the serialized information takes up in the database.
+
+We support this by abstracting the default behavior behind the `IJsonSerializerEncoderFactory` interface found in the `Umbraco.Cms.Core.Serialization` namespace.
+
+You can implement your own version of this interface and register it via a composer. This is shown in the following example that marks Cyrillic characters as excluded for encoding:
+
+```csharp
+using System.Text.Encodings.Web;
+using System.Text.Unicode;
+using Umbraco.Cms.Core.Composing;
+using Umbraco.Cms.Core.Serialization;
+using Umbraco.Cms.Infrastructure.Serialization;
+
+namespace Umbraco.Cms.Web.UI.Custom.SystemTextConfigurationEditor;
+
+public class SystemTextConfigurationEditorComposer : IComposer
+{
+    public void Compose(IUmbracoBuilder builder)
+    {
+        builder.Services.AddUnique<IJsonSerializerEncoderFactory, MyConfigurationEditorJsonSerializerEncoderFactory>();
+    }
+}
+
+internal class MyConfigurationEditorJsonSerializerEncoderFactory : IJsonSerializerEncoderFactory
+{
+    public JavaScriptEncoder CreateEncoder<TSerializer>()
+        where TSerializer : IJsonSerializer
+    {
+        return JavaScriptEncoder.Create(UnicodeRanges.BasicLatin, UnicodeRanges.Cyrillic);
+    }
+}
+```
+
+For reference, the default implementation can be found [in the Umbraco CMS source code](https://github.com/umbraco/Umbraco-CMS/blob/main/src/Umbraco.Infrastructure/Serialization/DefaultJsonSerializerEncoderFactory.cs).
+
+