From 4adb7b704f80e319069c4c40e38e043fbd692c99 Mon Sep 17 00:00:00 2001 From: Andy Butland Date: Tue, 5 Aug 2025 15:58:54 +0200 Subject: [PATCH 1/5] Added details of database availability checks. --- 16/umbraco-cms/SUMMARY.md | 1 + .../reference/database-availability.md | 45 +++++++++++++++++++ 2 files changed, 46 insertions(+) create mode 100644 16/umbraco-cms/reference/database-availability.md diff --git a/16/umbraco-cms/SUMMARY.md b/16/umbraco-cms/SUMMARY.md index df1cd51c554..b6b174f73bc 100644 --- a/16/umbraco-cms/SUMMARY.md +++ b/16/umbraco-cms/SUMMARY.md @@ -419,6 +419,7 @@ * [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) ## Tutorials diff --git a/16/umbraco-cms/reference/database-availability.md b/16/umbraco-cms/reference/database-availability.md new file mode 100644 index 00000000000..7dd9f028393 --- /dev/null +++ b/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(); + } +} + +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 [here](https://github.com/umbraco/Umbraco-CMS/blob/main/src/Umbraco.Infrastructure/Persistence/DefaultDatabaseAvailabilityCheck.cs). + From 442cfced74de8e35960514d4f978817538cfbcce Mon Sep 17 00:00:00 2001 From: sofietoft Date: Wed, 6 Aug 2025 08:58:37 +0200 Subject: [PATCH 2/5] Update link text --- 16/umbraco-cms/reference/database-availability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/reference/database-availability.md b/16/umbraco-cms/reference/database-availability.md index 7dd9f028393..feb5542350f 100644 --- a/16/umbraco-cms/reference/database-availability.md +++ b/16/umbraco-cms/reference/database-availability.md @@ -41,5 +41,5 @@ internal class MyDatabaseAvailabilityCheck : IDatabaseAvailabilityCheck ``` -For reference and inspiration, the default implementation can be found [here](https://github.com/umbraco/Umbraco-CMS/blob/main/src/Umbraco.Infrastructure/Persistence/DefaultDatabaseAvailabilityCheck.cs). +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). From 3f717df54232b613169b40bbe710918841e509fa Mon Sep 17 00:00:00 2001 From: Andy Butland Date: Thu, 7 Aug 2025 09:32:23 +0200 Subject: [PATCH 3/5] Added JSON serialization details --- 16/umbraco-cms/SUMMARY.md | 1 + .../reference/json-serialization.md | 48 +++++++++++++++++++ 2 files changed, 49 insertions(+) create mode 100644 16/umbraco-cms/reference/json-serialization.md diff --git a/16/umbraco-cms/SUMMARY.md b/16/umbraco-cms/SUMMARY.md index b6b174f73bc..180b40f6ff7 100644 --- a/16/umbraco-cms/SUMMARY.md +++ b/16/umbraco-cms/SUMMARY.md @@ -420,6 +420,7 @@ * [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 diff --git a/16/umbraco-cms/reference/json-serialization.md b/16/umbraco-cms/reference/json-serialization.md new file mode 100644 index 00000000000..f193e9dbc11 --- /dev/null +++ b/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(); + } +} + +internal class MyConfigurationEditorJsonSerializerEncoderFactory : IJsonSerializerEncoderFactory +{ + public JavaScriptEncoder CreateEncoder() + 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). + + From 52002639989316ae83a618674d172aa521518ea6 Mon Sep 17 00:00:00 2001 From: Andy Butland Date: Tue, 12 Aug 2025 13:08:39 +0100 Subject: [PATCH 4/5] Added details of strict domain matching --- .../reference/configuration/webroutingsettings.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/16/umbraco-cms/reference/configuration/webroutingsettings.md b/16/umbraco-cms/reference/configuration/webroutingsettings.md index 77b01924975..7f0797cab90 100644 --- a/16/umbraco-cms/reference/configuration/webroutingsettings.md +++ b/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. + From 4cf98049f784a3db0a536f43b34c4ea709dd1baf Mon Sep 17 00:00:00 2001 From: Andy Butland Date: Wed, 13 Aug 2025 10:00:53 +0100 Subject: [PATCH 5/5] Added information about DocumentSeedBatchSize and MediaSeedBatchSize --- .../reference/configuration/cache-settings.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/16/umbraco-cms/reference/configuration/cache-settings.md b/16/umbraco-cms/reference/configuration/cache-settings.md index 1454fa9efba..65ed6aec520 100644 --- a/16/umbraco-cms/reference/configuration/cache-settings.md +++ b/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 } } }