diff --git a/16/umbraco-cms/SUMMARY.md b/16/umbraco-cms/SUMMARY.md index df1cd51c554..180b40f6ff7 100644 --- a/16/umbraco-cms/SUMMARY.md +++ b/16/umbraco-cms/SUMMARY.md @@ -419,6 +419,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 diff --git a/16/umbraco-cms/reference/database-availability.md b/16/umbraco-cms/reference/database-availability.md new file mode 100644 index 00000000000..feb5542350f --- /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 [in the Umbraco CMS source code](https://github.com/umbraco/Umbraco-CMS/blob/main/src/Umbraco.Infrastructure/Persistence/DefaultDatabaseAvailabilityCheck.cs). + 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). + +