Allows you to configure the Content Dashboard settings for Umbraco.

{
  "Umbraco": {
    "CMS": {
      "ContentDashboard": {
        "AllowContentDashboardAccessToAllUsers": false,
        "ContentDashboardPath": "cms",
        "ContentDashboardUrlAllowlist": []
      }
    }
  }
}

AllowContentDashboardAccessToAllUsers

Gets a value indicating whether the Content Dashboard should be available to all users.

When the value is true the dashboard is visible for all user groups. Otherwise, when the value is false, the default access rules for that dashboard will be in use.

ContentDashboardPath

Gets the path to use when constructing the URL for retrieving data for the content dashboard.

ContentDashboardUrlAllowlist

Gets the allowed addresses to retrieve data for the content dashboard.

No addresses specified indicates that any URL is allowed.

Umbraco uses the .NET built-in configuration pattern. This means that the configuration is handled in the appsettings.json file and primarily done using IConfiguration with diffent sources.

For more in depth information on the configuration pattern see Microsofts Configuration in ASP.NET Core article.

Managing Configuration

You might not always want to have the configuration stored in the appsettings.json file, for instance, you might not want to have the admin password in the file if using the unattended feature. You might also want to use a specific set of configurations when developing your solution. To achieve this, the IConfiguration pattern can be used for this.

With the configuration pattern the settings can be read from multiple different source, where some take precedence over other, you can configure you site with:

1. The appsettings.json file

2. An appsettings.{environment}.json file

3. UserSecrets (Only when in development)

4. Environment variables

5. Command line arguments

This list is in order of precedence, so the values from appsettings.json will only be used if they're not also defined in the environment variables. If they are, then the environment variable will be used instead.

There is one caveat, to this precedence though, the appsettings.{environment}.json file will only be used if the current environment matches the name of the config file, for instance, the appsettings.Development.json file will only be used when the environment is set to development.

Using Environment Variables for Configuration

It is not feasible to have an entire json file as an environment variable, and the : doesn't work with environment variables on all platforms, so instead a double underscore is used to create the hierachy.

As an example, if you want to set your unattended username, you would normally write it in the appsettings.json like so:

"Umbraco": {
  "CMS": {
    "Unattended": {
      "UnattendedUserName": "A.N. Other"
    }
  }
}

As an environment variable it becomes a variable with the name Umbraco__CMS__Unattended__UnattendedUserName and a value of A.N. Other.

Using Command Line Arguments Configuration

Like with environment variables, it's not feasible to use an entire JSON file as a command line argument. However, with the command line the : will work without issues, so each section of the hierarchy is separated with a : character. If we use the same example as above, you can achieve the same result by using the following when starting the site via the command line:

dotnet run Umbraco:CMS:Unattended:UnattendedUserName="A.N Other"

Using UserSecrets for Configuration

In the development environment it is possible to use UserSecrets for configuration, which is ideal for connection strings and similar settings that shouldn't be committed to source control. To use UserSecrets you need to first enable them for the project - this is done with the following command, issued within the directory that contains the .csproj file:

dotnet user-secrets init

Now it's possible to store the connection string with this command:

dotnet user-secrets set "ConnectionStrings:umbracoDbDSN" "CONNECTION_STRING_IN_HERE"

The name of the key is created in the same way as in the Command Line example above, and thus corresponds to this JSON chunk:

"ConnectionStrings": {
    "umbracoDbDSN": "CONNECTION_STRING_IN_HERE"
}

IntelliSense

A great thing about appsettings.json is that it allows for intellisense with a schema file. For most editors this should work out of the box, without having to configure anything, since the schema is specified in the top of the file like so: "$schema": "https://json.schemastore.org/appsettings.json".

Reading Configuration in Code

You might need to read the configuration from your code.

When reading the configuration you need to inject an IOptions<> or IOptionsMonitor<> object into the class that needs it. Here is an example of how you would read the Host value from the SMTP settings contained within the global settings:

using Microsoft.Extensions.Options;
using Umbraco.Cms.Core.Configuration.Models;

namespace MySite;

public class SomeClass
{
    private GlobalSettings _globalSettings;

    public SomeClass(IOptions<GlobalSettings> globalSettings)
    {
        _globalSettings = globalSettings.Value;

        var smtpHost = _globalSettings.Smtp.Host;
    }
}

First off using Microsoft.Extensions.Options is added, to gain access to the IOptions type, and using Umbraco.Cms.Core.Configuration.Models; is added to get access to the GlobalSettings type.

IOptions<GlobalSettings> is then injected into the constructor of the class, where we can use the Value property to gain access to the actual settings object.

Now we have a typed object containing our settings, so we can get the Host value by calling _globalSettings.Smtp.Host.

To see what setting types you can access see the complete list below, each document corresponds to a settings type.

Configuration Options

A complete list of all the configuration sections included in Umbraco, by default, can be seen here along with any keys they contain:

• Basic authentication settings

• Cache settings

• Connection strings settings

• Content settings

• Debug settings

• Examine settings

• Exception filter settings

• Global settings

• Health checks settings

• Hosting settings

• Imaging settings

• Indexing settings

• Install default data setting

• Logging settings

• Maximum upload size settings

• Models builder settings

• Package migration settings

• Plugins settings

• Request handler settings

• Runtime settings

• Security settings

• Serilog settings

• Type finder settings

• Unattended settings

• Web routing settings

Configured by code

• FileSystemProviders

Allows you to configure the basic authentication settings for Umbraco. A basic authentication section fully populated with default values can be seen here:

"Umbraco": {
  "CMS": {
    "BasicAuth": {
      "AllowedIPs": [],
      "Enabled": false,
      "RedirectToLoginPage": false,
      "SharedSecret": {
        "HeaderName": "X-Authentication-Shared-Secret",
        "Value": null
      }
    }
  }
}

AllowedIPs

This is a comma-separated list of IP addresses you want to limit where the requests can come from.

Enabled

If the value is set to true, the basic authentication is enabled. By default, the value is set to false.

RedirectToLoginPage

If the value is set to true, instead of showing the basic authentication popup in the browser, the user is redirected to the login page. This is required for external logins to work. By default, the value is set to false.

SharedSecret

A shared secret can be sent using an HTTP header to bypass the basic authentication. This can be valuable for server-to-server communication.

HeaderName

The header name used to compare the shared secret. By default, the value is set to X-Authentication-Shared-Secret.

Value

The value of the shared secret. Must be a string longer than 0 characters to be enabled. The default value is null.

Global settings contains at set of global settings for the CMS such as default UI language, reserved urls, and much more. All of these, except for SMTP settings contains default values, meaning that all configuration is optional, unless you wish to send emails from your site.

The following snippet contains all the available options, with default values, and some example values for the required keys From, Host and Port keys of the SMTP settings:

Root level settings

In the root level section, that is those without a seperate sub section like SMTP, you can configure

Reserved urls

Key: ReservedUrls Type: string (default: ~/.well-known,)

A comma-seperated list of files to be left alone by Umbraco, these files will be served, and the Umbraco request pipeline will not be triggered.

Reserved paths

Key: ReservedPaths Type: string (default: ~/app_plugins/,~/install/,~/mini-profiler-resources/,~/umbraco/,)

A comma-separated list of all the folders in your directory to be left alone by Umbraco. If you have folders with custom files, add them to this setting to make sure Umbraco leaves them alone.

Timeout

Key: TimeOut Type: string (default: 00:20:00)

Configure the session timeout to determine how much time without a request being made can pass before the user is required to log in again. The session timeout format needs to be set as HH:MM:SS. Any activity within the backoffice will reset the timer.

Default UI language

Key: DefaultUILanguage Type: string (default: en-US)

The default language to use in the backoffice if a user isn't explicitly assigned one.

Hide top level nodes from path

Key: HideTopLevelNodeFromPath Type: bool (default: true)

If you are running multiple sites, you don't want the top level node in your URL and can disable it with this setting.

Use https

Key: UseHttps Type: bool (default: false)

Makes sure that all of the requests in the backoffice are called over HTTPS instead of HTTP when set to true.

Version check period

Key: VersionCheckPeriod Type: int (default: 7)

When this value is set above 0, the backoffice will check for a new version of Umbraco every 'x' number of days where 'x' is the value defined for this setting. Set this value to 0 to never check for a new version.

Icons path

Key: IconsPath Type: string (default: umbraco/assets/icons)

By adding this value you can specify a new/different folder for storing your icon resources. It's important to be aware of NetCore's limitations regarding serving static file content. By default, static content will only be served from the wwwroot folder.

Umbraco CSS path

Key: UmbracoCssPath Type: string (default: ~/css)

Umbraco scripts path

Key: UmbracoScriptsPath Type: string (default: ~/scripts)

Umbraco media path

Key: UmbracoMediaPath Type: string (default: ~/media)

Umbraco media physical root path

Key: UmbracoMediaPhysicalRootPath Type: string (default: ~/media)

Install missing database

Key: InstallMissingDatabase Type: bool (default: false)

This is not a setting that commonly needs to be configured.

If enabled Umbraco will try to automatically install the database when it's missing. This is primarily used in conjuction with unattended installs.

Disable election for single server

Key: DisableElectionForSingleServer Type: bool (default: false)

This is not a setting that commonly needs to be configured.

Database factory version

Key: DatabaseFactoryServerVersion Type: bool (default: false)

This is not a setting that commonly needs to be configured.

This setting is used to specify which sql server version that the database is running, this setting is only required if you use SqlServer 2008, if this is the case set the setting to "SqlServer.V2008"

Main dom lock

Key: MainDomLock Type: string

Specifies the implementation of IMainDomLock to be used.

IMainDomLock is used to synchronize access to resources like the Lucene indexes.

Available options:

• "FileSystemMainDomLock"- Available cross-platform, uses lock files written to LocalTempPath to control acquisition of MainDom status.

• "MainDomSemaphoreLock" - Windows only, uses a named system Semaphore with a maximumCount of 1 to control acquisition of MainDom status.

• "SqlMainDomLock" - Available cross-platform, uses the database to control acquisition of MainDom status.

The default implementation unless configured otherwise is FileSystemMainDomLock.

Main dom key discriminator

Key: MainDomKeyDiscriminator Type: string

For advanced use cases e.g. deployment slot swapping on Azure app services.

When using SqlMainDomLock a MainDomKey is used to identify an instance of a running application.

The MainDomKey is by default comprised of the server's machine name & the application id.

This is generally all that is required to control MainDom status as starting a new process for the same application on the same server will result in a matching MainDomKey. This will then require that an existing instance yields MainDom status to the new process.

To prevent this from occurring you can specify a MainDomKeyDiscriminator which should be set as a slot-specific configuration to prevent the slots from competing for MainDom status.

It's worth noting that during the swap operation there is a period where both instances will share the same configuration and at this point, the old instance will yield MainDom status to the new instance.

Main dom release signal polling interval

Key: MainDomReleaseSignalPollingInterval Type: string

Gets or sets the duration (in milliseconds) for which the MainDomLock release signal polling task should sleep. The default value is 2000ms.

Id

Key: Id Type: string

This setting doesn't need to be configured.

This setting contains a unique ID used to identify your project, and is populated the first time your site runs, you shouldn't change this setting.

No nodes view path

Key: NoNodesViewPath Type: string (default: ~/umbraco/UmbracoWebsite/NoNodes.cshtml)

This setting specifies what view to render when there is no content on the site.

SMTP settings

By adding this settings to the appsettings.json you will be able to send out emails from your Umbraco installation. This could be notifications emails if you are using content workflow, or you are using Umbraco Forms you also need to specify SMTP settings to be able use the email workflows. The forgot password function from the backoffice also needs a SMTP server to send the email with the reset link.

From

Specifies the default address emails will be sent from, this setting may be overridden some place, such as when inviting a user, where the email of the user sending the invite will be used instead. The format of the address follows the RFC 822 standard so you can include a friendly name using the format "Friendly Name <your@emailaddress.com>"

Host

Address of the SMTP host used to send the email from.

Port

The port of the SMTP host, port 25 is a common port for SMTP.

Username

The username used to authenticate with the specified SMTP server, when sending an email.

Password

The password used to authenticate with the specified SMTP server, when sending an email.

Secure socket options

Allows you to specify what security should be used for the connection sending the email.

The options are:

• None - No SSL or TLS encryption should be used.

• Auto - Allow the IMailService to decide which SSL or TLS options to use (default). If the server does not support SSL or TLS, then the connection will continue without any encryption.

• SslOnConnect - The connection should use SSL or TLS encryption immediately.

• StartTls - Elevates the connection to use TLS encryption immediately after reading the greeting and capabilities of the server. If the server does not support the STARTTLS extension, then the connection will fail and a NotSupportedException will be thrown.

• StartTlsWhenAvailable - Elevates the connection to use TLS encryption immediately after reading the greeting and capabilities of the server, but only if the server supports the STARTTLS extension.

Delivery method

Specifies what delivery method should be used for emails, most of the time you'd want to use the default "Network" option to send emails over the network. It might be useful during development to use "SpecifiedPickupDirectory" to place the email messages in a folder on disk, instead of trying to send them over the network.

Pickup directory location

If you're using the "SpecifiedPickupDirectory" option on as the delivery method, this setting allows you to specify what folder the emails should be saved to.

Database server registrar settings

It's unlikely that you will have to change these settings unless you're using a load balanced setup.

Wait time between calls

Key: DatabaseServerRegistrar.WaitTimeBetweenCalls Type: string (default: 00:01:00)

Sets a value for the amount of time to wait between calls to the database on the background thread.

Stale server timeout

Key: DatabaseServerRegistrar.StaleServerTimeout Type: string (default: 00:02:00)

Sets a value for the time span to wait before considering a server stale, after it has last been accessed.

Database server messenger

It's unlikely that you will have change these settings, unless you're using a load balanced setup. These settings are all about how load balancing instructions from the database are processed and pruned.

Max processing instruction

Key: DatabaseServerMessenger.MaxProcessingInstructionCount Type: string (default: 1000)

Sets a value for the maximum number of instructions that can be processed at startup; otherwise the server cold-boots (rebuilds its caches).

Time to retain instructions

Key: DatabaseServerMessenger.TimeToRetainInstructions Type: string (default: 2.00:00:00)

Sets a value for the time to keep instructions in the database; records older than this number will be pruned.

Time between sync operations

Key: DatabaseServerMessenger.TimeBetweenSyncOperations Type: string (default: 00:00:05)

Sets a value for the time to wait between each sync operation.

Time between prune operations

Key: DatabaseServerMessenger.TimeBetweenPruneOperations Type: string (default: 00:01:00)

Sets a value for the time to wait between each prune operation.

Distributed Locking Mechanism

Key: DistributedLockingMechanism Type: string

This is not a setting that commonly needs to be configured.

Gets or sets a value representing the DistributedLockingMechanism to use.

Valid values:

• "SqlServerDistributedLockingMechanism"

• "SqliteDistributedLockingMechanism"

Distributed Read Lock DefaultTimeout

Key: DistributedLockingReadLockDefaultTimeout Type: string (default: 00:01:00)

Gets or sets a value representing the maximum time to wait whilst attempting to obtain a distributed read lock.

The default value is 60 seconds.

Distributed Write Lock DefaultTimeout

Key: DistributedLockingWriteLockDefaultTimeout Type: string (default: 00:00:05)

Gets or sets a value representing the maximum time to wait whilst attempting to obtain a distributed write lock.

The default value is 5 seconds.

The connection strings settings section contains the connection string to the database Umbraco will connect to. This section is similar to what is used by default in .NET Core. The important thing is that the key for the connection string Umbraco will use is "umbracoDbDSN". It is also important to know that this section is outside the Umbraco.CMS section, and is therefore in the root of the config.

An connection strings config can look like this:

The connection string used here is an SQLite connection string, that will connect to a data in the file Umbraco.sqlite.db located in /umbraco/Data .

Umbraco currently supports using either a Microsoft SQL Server or a SQLite database. Both of these options will have different connection strings. For more information about the specific connection strings, see:

Provider name

Because Umbraco cannot determine the provider name from the connection string in all cases. Umbraco follows for provider names, which involves specifying it as a postfix in the connection string name.

Allows you to configure the behavior of data types.

CanBeChanged

Gets or sets a value indicating if data types can be changed after they've been used.

Valid values:

• "True"

  • Allows data types to be changed after creation. This can lead to data on content is not valid on the Data Type.

• "False"

  • Disallow Data Type changes. (Recommeded value, unless you really know what you are doing)

• "FalseWithHelpText"

  • Disallow Data Type changes, but show the users a help text so they understand why.

Umbraco does not touch the default maximum allowed content size of the different services, but you can configure this yourself.

Using IIS

To configure the default 28.6MB upload limit using IIS, we have to create a web.config file at the root of the project. It should contain this:

<?xml version="1.0"?>
<configuration>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- ~ Below is the number of bytes allowed, 4GB is the maximum -->
        <requestLimits maxAllowedContentLength="2000000" />
      </requestFiltering>
    </security>
  </system.webServer>
</configuration>

maxAllowedContentLength is specified in bytes, so this configuration would limit requests, and therefore uploaded files, to 2 megabytes

Using Kestrel

Runtime settings allow you to configure the MaxRequestLength and MaxQueryStringLength for kestrel. If you want to upload files larger than 28.6MB, then you have to configure these settings. If nothing is configured requests and query strings can only be the default size and smaller.

An example of a configuration could look something like this:

"Umbraco": {
  "CMS": {
    "Runtime": {
      "MaxQueryStringLength": 90,
      "MaxRequestLength": 2000
    }
  }
}

MaxRequestLength is specified in kilobytes. This configuration will limit requests, and therefore uploaded files, to 2 megabytes, and a maximum query string length of 90 characters.

Using Nginx (external)

Using apache (external)

This section contains configurations regarding debugging, and should therefore only be used in development.

The debug section has two settings you can configure, "LogIncompletedScopes" and "DumpOnTimeoutThreadAbort", both of these are false by default:

Log incompleted scopes

If this value is set to true, any scope that gets disposed without first being completed will trigger a log entry containing the stacktrace.

DumpOnTimeoutThreadAbort

If this value is set to true, a memory dump will be taken if a thread aborts due to a timeout. This dump will be saved to /umbraco/Data/MiniDump.

Content settings contains a handful of settings related to the content in the CMS. It includes settings such as allowed upload files, image settings, and much more. All the values in the content settings has default values, so all configuration is optional.

The following snippet will give an overview of the keys and values in the content section including the default values:

Root level settings

In the root level section, that is those without a seperate sub section like Imaging, you can configure:

Allow Edit Invariant From Non-Default

Invariant properties are properties on a multilingual site that are not varied by culture. This means that they share the same value across all languages added to the website.

When the setting is set to false the invariant properties that are shared between all languages can only be edited from the default language. This means you need access to the default language, in order to edit the property.

When set to true (default) the invariant properties will need to be unlocked before they can be edited. The lock exists in order to make it clear that this change will affect more languages.

Allowed upload files

If greater control is required than available from the above, this setting can be used to store a list of file extensions. If provided, only files with these extensions can be uploaded via the backoffice.

Allowed media hosts

By default, only relative URLs are allowed when getting URLs for resized images or thumbnails using the ImagesController. If you need absolute URLs you will have to add the allowed hosts to this list. The value could be ["umbraco.com", "www.umbraco.com", "our.umbraco.com"].

Disable delete when referenced

This setting allows you to specify whether a user can delete content or media items that depend on other items. This also includes any descendants that have dependencies. Setting this to true will remove or disable the Delete button.

Disable unpublish when referenced

This setting allows you to specify whether or not users can unpublish content items that depend on other items or have descendants that have dependencies. Setting this to true will disable the Unpublish button.

Disallowed upload files

This setting consists of a list of file extensions that editors shouldn't be allowed to upload via the backoffice.

Error 404 collection

In case of a 404 error (page not found) Umbraco can return a default page instead. This is set here. Notice you can also set a different error page, based on the current culture so a 404 page can be returned in the correct language.

The above example shows what you need to do if you only have a single site that needs to show a custom 404 page. You specify which node that should be shown when a request for a non-existing page is being made. You can specify the node in three ways:

1. Enter the nodes id ("ContentId": 1)

2. Enter the node's GUID ("ContentKey": "4f96ffdd-b969-46a8-949e-7935c41fabc0")

If you have multiple sites, with different cultures, setup in your tree then you will need to setup the errors section like below:

If you have more than two sites and forget to add a 404 page and a culture, the default page will act as fallback. Same happens if you for some reason forget to define a hostname on a site.

Hide backoffice logo

This setting can be used to hide the Umbraco logo in backoffice.

Login background image

You can specify your own background image for the login screen here. The image will automatically get an overlay to match backoffice colors. This path is relative to the wwwroot/umbraco path. The default location is: wwwroot/umbraco/login/login.jpg.

Login logo image

You can specify your own image for the small logo in the top left corner of the login screen. This path is relative to the wwwroot/umbraco path. The default location is: wwwroot/umbraco/login/logo_light.svg.

Login logo image (alternative)

You can specify your own alternative image for the small logo in the top left corner of the login screen. The alternative image is shown on light backgrounds (for example for mobile resolutions). This path is relative to the wwwroot/umbraco path. The default location is: wwwroot/umbraco/login/logo_dark.svg.

Preview badge

This allows you to customize the preview badge being shown when you're previewing a node.

Resolve urls from text string

This setting is used when you're running Umbraco in virtual directories. Setting this to true can increase render time for pages with a large number of links. However, this is required if Umbraco is running in a virtual directory.

Show deprecated property editors

This setting is used for controlling whether or not the Data Types marked as obsolete should be visible in the dropdown when creating new Data Types.

By default this is set to false. To make the obsolete data types visible in the dropdown change the value to true.

Show Domain Warnings

If you do not configure Domains for each language in a multilingual site then every time you publish your content you get this warning:

Content published: Domains are not configured for multilingual site, please contact an administrator, see log for more information.

If you have a use case for not setting the domains, you can set this setting ShowDomainWarnings to false to stop the warning from displaying.

ContentVersionCleanupPolicy

The global settings for the scheduled job which cleans historic content versions. These settings can be overridden per Document Type.

Current draft and published versions will never be removed, nor will individual content versions which have been marked as "preventCleanup".

If you don't wish to retain any content versions except for the current draft and currently published you can set both of the "keep" settings values to 0. After doing this, the next time the scheduled job runs (hourly) all non-current versions (except those marked "prevent cleanup") will be removed.

EnableCleanup

When true a scheduled job will delete historic content versions that are not kept according to the policy every hour.

When false, the scheduled job will never delete any content versions regardless of overridden settings for a Document Type.

This defaults to false when not set in the configuration which will be the case for those upgrading from v9.0.0. However, the dotnet new template will supply an appsettings.json with the value set to true for all sites starting from Umbraco 9.1.0.

KeepAllVersionsNewerThanDays

All versions that fall in this period will be kept.

KeepLatestVersionPerDayForDays

For content versions that fall in this period, the most recent version for each day is kept. All previous versions for that day are removed unless marked as preventCleanup.

This variable is independent of KeepAllVersionsNewerThanDays, if both were set to the same value KeepLatestVersionPerDayForDays would never apply as KeepAllVersionsNewerThanDays is considered first.

Imaging

This section is used for managing how Umbraco handles images, allowed attributes and, which properties of an image that should be automatically updated on upload.

Let's break it down.

ImageFileTypes

This is a separated list of accepted image formats

AutoFillImageProperties

You can define what properties should be automatically updated when an image is being uploaded. This means that if you decide to rename the default umbracoWidth and umbracoHeight properties the values in "WidthFieldAlias" and "HeightFieldAlias" need to be updated. This needs to happen in order to automatically populate the values when the image is being uploaded.

Custom media document

If you need to create a custom Media Type to handle images you need to add another object using the custom Media Type alias. Like below. Keep in mind that the width and height attributes have also been changed in this example.

Notifications

Filesystem providers are configured via code, you can either configure it in a composer, or in the Program.cs file.

By default Umbraco will save Media in a folder called /media within the webroot on the Physical file system. The code snippet above will change the location to instead save the media in a folder called /CustomMediaFolder within the webroot.

The media provider can be of many types, for example in case you want to store media on Azure, Amazon or even DB. But the provider that comes by default with the installation of Umbraco is the PhysicalFileSystem provider.

PhysicalFileSystem Configuration

The physical file system provider manages the interaction of Umbraco with the local file system. It can be configured for two different scenarios:

• Media files stored inside a virtual folder of the site

• Media files stored somewhere else outside of the site and accessed via a custom URL

Virtual Folder

Physical path

There are a few more steps involved if you want to store the media files in a separate folder outside the webroot.

First you must register the folder as a static file provider in your Program.cs file like so:

Now you can register the folder as the media filesystem

This is much the same as when you register it within the wwwroot with a virutal folder. The only differnce is that now you provide an absolute root path and root URL to the physical filesystem.

• rootPath is the full filesystem path where you want media files to be stored. It has to be rooted, must use directory separators (\) and must not end with a separator. For example, Z: or C:\path\to\folder or \\servername\path.

• rootUrl is the URL where the files will be accessible from. It must use URL separators (/) and must not end with a separator. It can either be a folder, like /UmbracoMedia, in which case it will considered as subfolder of the main domain (example.com/UmbracoMedia) or can be a fully qualified URL, with also domain name and protocol (for ex http://media.example.com/media).

Custom providers

Get the contents of a file as a stream

The recommended approach to obtain a file's content as a stream is to utilize the MediaFileManager. It is advised to avoid reading the file directly from the server using methods like Server.MapPath. This will ensure that, regardless of the file system provider, the stream will be returned correctly. This example demonstrates using MediaFileManager to validate file existence and stream it back from a controller.

Since the majority of Examine configuration takes place in code, this section is small and contains only one setting to change: LuceneDirectoryFactory. This setting allows you to change the behavior of the ExamineIndexes directory.

This section has a default value, and does not need to be configured, configuring Examine might look something like this:

This is how Examine is configured by default. There is three different types of Lucene directory factories:

• Default - The index will operate from the default location: umbraco/Data/TEMP/ExamineIndexes

• SyncedTempFileSystemDirectoryFactory - The index will operate on a local index created in the processes %temp% location and will replicate back to main storage in umbraco/Data/TEMP/ExamineIndexes

• TempFileSystemDirectoryFactory - The index will operate only in the processes %temp% directory location

In the Runtime settings you can configure:

• Size limits for requests and query strings. Neither of these settings needs to be configured. If nothing is configured, requests and query strings can be any size.

• The runtime mode of Umbraco.

• The lifetime of temporary file uploads. This is primarily used when uploading images and other media in the backoffice.

An example of a configuration could look something like:

• MaxRequestLength is specified in kilobytes. Setting this limits the request size, including the size of uploaded files.

• MaxQueryStringLength is specified in number of characters. Setting this limits the maximum query string length.

• Mode can have three values: BackofficeDevelopment (default), Development, and Production. For more information, see the article.

• TemporaryFileLifeTime is specified as a timespan. The default value is one day - 1.00:00:00.

The Plugins settings allow you to configure how Umbraco handles plugins. Currently, you can only configure browsable file extensions, which allows you to customize what file types plugins are allowed to use for the front end. The default configuration looks like this:

As you can see above, by default, markup, styles, scripts, images, fonts, configurations, and license type are included. If you were to, for example, remove the ".html" entry, then plugins would no longer be allowed to use HTML files.

Cache Settings

HybridCacheOptions

Umbraco's cache is implemented using Microsofts HybridCache, which also has its own settings. For more information .

MaximumPayLoadBytes

One HybridCache setting of particular interest is the MaximumPayloadBytes setting. This setting specifies the maximum size of a cache entry in bytes and replaces the BTreeBlockSize setting from NuCache. The default from Microsoft is 1MB. However, this limit could quickly be reached, especially when using multiple languages or property editors like the block grid. To avoid this Umbraco overrides the setting to 100MB by default. You can also configure this manually using a composer:

Seeding settings

ContentTypeKeys

The ContentTypeKeys setting specifies which Document Types should be seeded into the cache. The setting is a comma-separated list of Document Type keys.

DocumentBreadthFirstSeedCount

The DocumentBreadthFirstSeedCount setting specifies how many documents should be seeded into the cache when doing a breadth-first traversal. The default value is 100.

MediaBreadthFirstSeedCount

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.

Cache Entry settings

The Entry settings allow you to specify how long cache entries should be kept. The cache entry settings are identical for documents and media.

LocalCacheDuration

Specifies the duration for which cache entries should be kept in the local memory cache. The default value is 24 hours.

RemoteCacheDuration

Specifies the duration that cache entries should be kept in the remote cache, second level cache. This setting is only relevant if a second-level cache is configured. The default value is 1 year.

SeedCacheDuration

Specifies the duration for which seeded cache entries should be kept in the cache. The default value is 1 year.

NuCache Settings

For backward compatibility reasons, certain settings are under the Umbraco:CMS:NuCache settings node.

UsePagedSqlQuery

Setting UsePagedSqlQuery to False your project will use the Fetch method instead of the QueryPaged method when rebuilding the NuCache files. This will increase performance on bigger Umbraco websites with a lot of content when rebuilding the NuCache.

SqlPageSize

Specifying the SqlPageSize will change the size of the paged SQL queries. The default value is 1000.

This settings section provides control over how package migrations are executed in different environments (local, development, live etc.)

Package migrations are defined by package developers allowing them to add functionality to their package that enhances the Umbraco CMS. There can be various types of migrations applied, including creating custom database tables and installing Umbraco schema and content.

They run on start-up, thus ensuring that the functionality of the package has the necessary infrastructure, schema, and content in place when it is used.

Migration steps that are explicitly created by the package developer to make database schema changes will always run in all environments.

Depending on your workflow, for those steps that install Umbraco data - whether schema such as document types, content, or media - you may want them run in all environments, or you may prefer to only do this in certain ones.

The default behavior for Umbraco CMS is for all package migrations to run in all environments.

If using Umbraco Cloud, the default is to run package migrations fully only in local environments. By doing this, for schema, .uda files will be generated in the /umbraco/Deploy/Revision folder, which when pushed to a Cloud environment will be used to install the schema and content there. For content and media, the "queue for transfer" operation can be used. With this behavior, we avoid any issues caused by both a package migration and a deployment operation attempting to create schema and content.

If different behavior is required, or if using Umbraco Deploy On-Premises, the following settings can be applied:

RunSchemaAndContentMigrations

If set to true, the default behavior described above for Umbraco CMS on-premises and Umbraco Cloud will be applied. By setting to false, the installation of Umbraco schema and content from a package migration will be skipped. If missing the default value is true.

AllowComponentOverrideOfRunSchemaAndContentMigrations

If this is set to the default value of true, Umbraco Cloud (or other deployment tools) can override the configured value of RunSchemaAndContentMigrations as is appropriate for their operation. By setting to false such tools should respect this setting, not make any overrides and use the configured value.

The options in the request handler let us do some useful things. It could be deciding whether or not to use trailing slashes and setting URL replacement for special characters.

Let's have a further look at each option below.

Here is a snippet containing all the default values of the RequestHandler section.

Add trailing slash

This will add a trailing slash to the URL when <addTrailingSlash> is set to "true". If you don't want to have a trailing slash, set the value to false.

Convert URLs to ascii

This setting tells Umbraco to convert all URLs to ASCII: American Standard Code for Information Interchange, if set to false the URLs will remain UTF-8.

This setting can be set to try This will make the engine try to convert the name to an ASCII implementation. If it fails, it will fallback to the name. Reason is that some languages don't have ASCII implementations, therefore the URLs would end up being empty.

Enable default character replacements

This setting tells Umbraco to use the default character replacements. If you don't want the default character replacements, set this to false.

Char collection

This settings contains objects with a "Char" and "Replacement key. Each of these objects holds a character that should be replaced and what it should be replaced with.

When something like the following is added to the list, the ñ will be shown as a n in the URL.

This section allows you to configure the Umbraco models builder, a complete section with default values can be seen here:

Let's go through them one by one.

Models mode

Specifies how the models builder will generate models and when to generate them. The options are:

• Nothing - The modelsbuilder will not generate any models, this means that all views will use IPublishedContent, instead of strongly typed models.

• InMemoryAuto - Models will automatically be generated each time a content type change occurs, and will then be compiled, and loaded into memory dynamically. This means that the models are only available in views, however they will be available instantly.

• SourceCodeManual - Models will be generated as .cs files whenever a user clicks the "Generate models" button on the models builder dashboard - however, the models will not be compiled and loaded into memory dynamically. This means that models are available to edit within the project. The project needs to be recompiled and restarted for the new models, or model changes, to take effect.

• SourceCodeAuto - This mode behaves the same as SourceCodeManual with one difference, the generation of models happens automatically every time a content type change occurs.

Models namespace

This setting allows you to customize the namespace of the generated models, for instance you might want to change this to something that aligns better with your project structure, such as MySite.ContentModels.

Flag out of date models

This setting allows you to specify if a model should be flagged as out of date if its content type, or a datatype the content type depends on, are changed. When a model is flagged as out of date you will be able to see that you need to regenerated models in modelsbuilder dashboard.

This setting is only really relevant if you use the SourceCodeManual models mode, since otherwise the models will be automatically regenerated, and will therefore never be out of date.

If you set this setting to true while using an Auto mode, it will automatically be interpreted as false.

Models directory

Allows you to specify a custom directory for your generated models. By default this settings has to be a virtual directory, that is, it must start with ~/, if needed AccceptUnsafeModelsDirectory can be set to true, to allow the path to be outside the website root, be aware though that this is a potential security risk.

Accept unsafe models directory

By setting this to true, you specify that the models directory is allowed to be outside the websites root. This is not allowed by default since it can be a potential security risk.

Debug level

This setting specifies the logging level for the models builder. By default this is set to 0, which means minimal logging. Anything higher that 0 means increased logging. Be aware that this setting should only be set to something higher than 0 for development use, not on live sites.

The health checks section allows you to disable certain health checks, and configure your own custom notification methods, that will automatically run the health checks every so often, and notify you if any health checks fails.

An example of a HealthChecks settings can look something like this:

"Umbraco": {
  "CMS": {
    "HealthChecks": {
      "DisabledChecks": [
        {
          "Id": "D0F7599E-9B2A-4D9E-9883-81C7EDC5616F"
        }
      ],
      "Notification": {
        "Enabled": true,
        "FirstRunTime": "* 4 * * *",
        "Period": "1.00:00:00",
        "NotificationMethods": {
          "email": {
            "Enabled": true,
            "Verbosity": "Detailed",
            "FailureOnly": true,
            "Settings": {
              "RecipientEmail": "alerts@mywebsite.tld"
            }
          }
        }
      }
    }
  }
}

This config will enable notifications to run the checks and notify via email if a check fails. The checks will run the first time five minutes after the site is booted, and then once every day.

The email notification method is built in, if you want to read more about creating you own notification methods, or see a list of the ID of every built in health check, then see Extending health checks

But let's go through the config one by one

Disabled checks

A list of DisabledHealthCheckSettings objects, each of these objects represents a disabled health check. Only the Id key needs to be present and have a value, corosponding to the GUID of the health check to disable.

There is also a DisabledOn key representing the date the health check was disabked and a DisabledBy key containing the ID of the user that disabled the health check, however these values are currently not used.

Notification

Settings relating to running the health checks automatically and sending out notifications.

Enabled

Allows you to disable or enable all notifications methods, if set to false, the health checks will not automatically run.

First run time

This will configure when you run the health checks for the first time, if the value is not configured the health checks will run immediately after the site boots for the first time. This value is specified as a string in crontab format, so in this example, the health checks will first run at 4 a.m.

Period

Specifies how often the health checks should run, as a DateTime string, in this example the checks will run every day (every 24 hours).

Notification methods

A dictionary of all the notification methods that should be used.

The key of the dictionary is the alias of the notification method, and the value is a HealthChecksNotificationMethodSettings configuration object, in this case it's the built in email notification method.

Each object allows the following to be configured:

Enabled

Allows you to enable or disable specific checks.

Verbosity

Configures how verbose the reporting should be, the available options are:

• Summary

• Detailed

Failure only

If set to true, the notification method will only run if a check has failed.

Settings

Allows you to set custom settings for a given implementation of a notification method, which settings are available depends on the specific implementation.

The imaging settings section lets you configure the cache and resize settings for processed images on your project (using ImageSharp.Web as default implementation). If you need to configure allowed image file types or auto fill image properties, you want to use content settings instead.

All these settings contain default values, so nothing needs to be explicitly configured. A complete settings section for imaging can be seen here with all the default values:

"Umbraco": {
  "CMS": {
    "Imaging": {
      "Cache": {
        "BrowserMaxAge": "7.00:00:00",
        "CacheMaxAge": "365.00:00:00",
        "CacheFolderDepth": 8,
        "CacheHashLength": 12,
        "CacheFolder": "~/umbraco/Data/TEMP/MediaCache"
      },
      "Resize": {
        "MaxWidth": 5000,
        "MaxHeight": 5000
      }
    }
  }
}

Cache

Contains configuration for browser and server caching. When changing these cache headers, it is recommended to clear your media cache. This is due to the data being stored in the cache and not updated when the configuration is changed.

Browser max age

Specifies how long a requested processed image may be stored in the browser cache by using this value in the Cache-Control response header. The default is 7 days (formatted as a timespan).

Cache max age

Specifies how long a processed image may be used from the server cache before it needs to be re-processed again. The default is one year (365 days, formatted as a timespan).

Cache folder depth

Gets or sets the depth of the nested cache folders structure to store the images. Defaults to 8.

Cache hash length

Gets or sets the length of the filename to use (minus the extension) when storing images in the image cache. Defaults to 12 characters.

Cache folder

Allows you to specify the location of the cached images folder. By default, the cached images are stored in ~/umbraco/Data/TEMP/MediaCache. The tilde (~) resolves to the content root of your project/application.

Resize

Contains configuration for image resizing.

Max width/max height

Specifies the maximum width and height an image can be resized to. If the requested width and height are both above the configured maximums, no resizing will be performed. This adds basic security to prevent resizing to big dimensions and using a lot of server CPU/memory to do so.

The maximum width and height settings are enforced by setting the ImageSharpMiddlewareOptions.OnParseCommandsAsync option of ImageSharp to an Umbraco-specific function. If you want to add your own logic without overwriting this behaviour, use the following code:

public class ConfigureImageSharpMiddlewareOptionsComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder.Services.Configure<ImageSharpMiddlewareOptions>(options =>
        {
            // Capture existing task to not overwrite it
            var onParseCommandsAsync = options.OnParseCommandsAsync;
            options.OnParseCommandsAsync = async context =>
            {
                // Custom logic before

                await onParseCommandsAsync(context);

                // Custom logic after
            };
        });
}

This section allows you to disable the ModelBindingExceptionFilter, this filter is only enable if the models builder mode is set to InMemoryAuto. This filter will return a redirect to the page being loaded after one second, if a ModelsBindingException or InvalidCastException occurs. The reason for this filter is that a page might be requested at the same time as the content type has been changed. If this occurs, the new model might not have been generated and loaded yet. This filter will take care of this. By default this filter is enabled, but will be ignored if the mode is not InMemoryAuto. To manually disable the filter add the "ExecptionFilter" section to your config with the "Disabled" key set to true like so:

"Umbraco": {
  "CMS": {
    "ExceptionFilter": {
      "Disabled": true
    }
  }
}

This section allows you to configure how content is indexed for Examine.

"Umbraco": {
  "CMS": {
    "Indexing": {
      "ExplicitlyIndexEachNestedProperty": true
    }
  }
}

ExplicitlyIndexEachNestedProperty

When indexing content, each property contained within certain complex editors are indexed as separate fields by default. These complex editors include:

• Block List

• Block Grid

The complex editors are also indexed to their own separate fields, which then contains "the sum" of all properties contained within.

In some cases this yields a lot of fields in the index, which can lead to errors when performing searches. Changing this setting to false can mend that issue. It prevents each contained property from being written to the index in its own field.

Hosting settings contains settings regarding the hosting of the site, such as application virtual path, local temporary storage location and debug.

A full configuration with default values can be seen here:

"Umbraco": {
  "CMS": {
    "Hosting": {
      "ApplicationVirtualPath": "/",
      "LocalTempStorageLocation": "Default",
      "Debug": false,
      "SiteName"
    }
  }
}

Setting overview

Application virtual path

This setting specified the virtual path of the application, this path must start with a slash.

Local temp storage location

This setting specifies the location of the local temp storage.

Options:

• Default

• EnvironmentTemp

Debug

This setting allows you to run Umbraco in debug mode, by setting the value to true.

Site name

Gets or sets a value specifying the name of the site. The IWebHostEnvironment.ApplicationName is used if not specified

The type finder settings allows you to specify assemblies that accept load exceptions when they are type scanned. For multiple assemblies separate them with a comma (,). To accept load exceptions for all assemblies use an asterisk (*), like so:

Furthermore it is possible to add additional assemblies to the exclusion filter. Thereby these assemblies will be ignored by Umbraco. This can be useful depending on nuget packages that are not Umbraco packages.

"Umbraco": {
  "CMS": {
    "TypeFinder": {
      "AssembliesAcceptingLoadExceptions": "*",
      "AdditionalAssemblyExclusionEntries": []
    }
  }
}

This settings lets you configure the unattended install & upgrade settings. This is a feature that allows Umbraco to install without using the UI. If you don't intended to use this feature, you don't need to configure this.

It's important to know that the install feature will only work if there is a connection string configured pointing to an empty database. A configuration for unattended install & upgrade can look something like:

{
  "$schema": "https://json.schemastore.org/appsettings.json",

  "ConnectionStrings": {
    "umbracoDbDSN": "Server=.;Database=DocsSite;Integrated Security=true"
  },
  "Umbraco": {
    "CMS": {
      "Unattended": {
        "InstallUnattended": true,
        "PackageMigrationsUnattended": true,
        "UpgradeUnattended": true,
        "UnattendedUserName": "A.N. Other",
        "UnattendedUserEmail": "AN@Other.com",
        "UnattendedUserPassword": "APasswordMeetingRequirements"
      }
    }
  }
}

This will automatically install Umbraco to the DocsSite database on the local SQL server, and will also automatically upgrade whenever there is an upgrade to install.

It is generally not recommended to keep user credentials in config files, therefore we recommend using environment variables to configure these settings.

Let's go through the settings one by one

Install unattended

Umbraco will only automatically install if this is set to true, and if there is a connection string pointing to an empty database.

Upgrade unattended

If this is set to true, Umbraco will automatically run the upgrade migrations once the site has been upgraded.

Unattended user name

This setting is used to specify the user name of the default admin user.

Unattended email

This setting is used to specify the email address of the default admin user.

Unattended user pass

This setting is used to specify the password of the default admin user.

Package migrations unattended

Gets or sets a value indicating whether unattended package migrations are enabled.

This is true by default.

Umbraco uses Serilog as its logging library, this means that the configuration of logging is offloaded to Serilog instead of the CMS. This means that logging specific configuration is not in the Umbraco.Cms section, but instead the Serilog section.

We will go through some of the more common logging configurations here, but for more information see the Serilog settings GitHub project.

Default configuration

When you create a new Umbraco project the following Serilog section will be included by default:

"Serilog": {
  "MinimumLevel": {
    "Default": "Information",
    "Override": {
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information",
      "System": "Warning"
    }
  }
}

Specifying minimum log level

As you can see above, the CMS comes with a default Serilog config that defines the minimum log level with the "MinimumLevel" key.

You can specify the overall minimum log level with the "Default" key. This will apply to all namespaces, however it's also possible to override this log level for specific names spaces with the "Override" key. In the example above, any logging coming from the Microsoft and System namespaces will only log warnings and up, however the Microsoft.Hosting.Lifetime namespace will log information and up.

The possible values, from most verbose to least, is:

• Verbose

• Debug

• Information

• Warning

• Error

• Fatal

For information on what each of these levels means see the Serilog wiki.

Changing the log level for specific namespaces

This can be done by updating the appsettings.json configuration file to specify namespaces in which you want to change the log level for.

  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "Microsoft.Hosting.Lifetime": "Information",
        "System": "Warning",
        "Examine.Lucene.Providers.LuceneIndex": "Debug",
        "Examine.BaseIndexProvider": "Debug",
        "MyNamespace": "Verbose"
      }
    }
  }

Logging to a different output

Serilog has the ability to log to a number of different mechanisms, from console to files, even to Slack or email. This is all configured using what Serilog calls sinks.

An example of this can be seen in the default appsettings.Development.json, where Serilog is configured to log to the console using the Async wrapper sink:

  "Serilog": {
    "MinimumLevel": {
      "Default": "Information"
    },
    "WriteTo": [
      {
        "Name": "Async",
        "Args": {
          "configure": [
            {
              "Name": "Console"
            }
          ]
        }
      }
    ]
  }

Here you can see that we use the "WriteTo" key to specify a list of sinks the logger should write to. In this case we use the "Async" sink configured to write to the console, this means that we'll log to the console asynchronously.

Now there's too many sinks to cover here, for a full list of all available sinks see Provided sinks. Each of these entries will have their own documentation on how to set up the logging with the particular sink.

Changing the Umbraco 'sink'

By default, Umbraco uses a special Serilog 'sink' that is optimized for performance. To change parameters for only this sink, but not the default. For E.g higher log level for this compared to other sinks you can do it in the following way:

  "Serilog": {
    "MinimumLevel": {
      "Default": "Information"
    },
    "WriteTo": [
      {
        "Name": "UmbracoFile",
        "Args": {
          "RestrictedToMinimumLevel": "Warning",
          "FileSizeLimitBytes": 1073741824,
          "RollingInterval" : "Day",
          "FlushToDiskInterval": null,
          "RollOnFileSizeLimit": false,
          "RetainedFileCountLimit": 31
        }
      }
    ]
  }

Adding a custom log property to all log items

You may wish to add a log property to all log messages. A good example could be a log property for the environment to determine if the log message came from development or production.

This is useful when you could be writing logs from all environments or multiple customer projects into a single logging source, such as Elasticsearch. This would allow you to search and filter for a specific project and its environment to see the log messages. You can also reference your hosting server's environment variables in the property values.

In the appsettings.json configuration file you can add the following lines

  "Serilog": {
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "Microsoft.Hosting.Lifetime": "Information",
        "System": "Warning"
      }
    },
    "Properties": {
      "Customer": "Super Customer",
      "Environment": "Production"
    }
  }

The options in the security section allows you to configure all things security, whether to keep users logged in, password rules and more.

A full configuration with all default values can be seen here:

"Umbraco": {
  "CMS": {
    "Security": {
      "KeepUserLoggedIn": false,
      "HideDisabledUsersInBackOffice": false,
      "AllowPasswordReset": true,
      "AuthCookieName": "UMB_UCONTEXT",
      "AuthCookieDomain": "",
      "UsernameIsEmail": true,
      "UserPassword": {
        "RequiredLength": 10,
        "RequireNonLetterOrDigit": false,
        "RequireDigit": false,
        "RequireLowercase": false,
        "RequireUppercase": false,
        "HashAlgorithmType": "PBKDF2.ASPNETCORE.V3",
        "MaxFailedAccessAttemptsBeforeLockout": 5
      },
      "MemberPassword": {
        "RequiredLength": 10,
        "RequireNonLetterOrDigit": false,
        "RequireDigit": false,
        "RequireLowercase": false,
        "RequireUppercase": false,
        "HashAlgorithmType": "PBKDF2.ASPNETCORE.V3",
        "MaxFailedAccessAttemptsBeforeLockout": 5
      },
      "UserDefaultLockoutTimeInMinutes": 43200,
      "MemberDefaultLockoutTimeInMinutes": 43200,
      "AllowConcurrentLogins": false
    }
  }
}

Root level settings

At the root level of security you can configure the following

Keep user logged in

When set to false a user will be logged out after a specific amount of time has passed with no activity. You can specify this time span in the global settings with the TimeOut key.

Hide disabled users in backoffice

When this is set to "true" it's not possible to see disabled users. This means it's not possible to re-enable their access to the backoffice again. It also means you can't create an identical username if the user was disabled by a mistake.

Allow password reset

This feature allows users to reset their passwords if they have forgotten them. By default, this is enabled. It can be disabled at both the UI and API level by setting this value to "false".

Auth cookie name

The authentication cookie which is set in the browser when a backoffice user logs in, and defaults to UMB_UCONTEXT.

Auth cookie domain

The authentication cookie which is set in the browser when a backoffice user logs in is automatically set to the current domain.

Username is email

This setting specifies whether the username and email address are separate fields in the backoffice editor. When set to "false", you can specify an email address and username, only the username can be used to log on. When set to "true" (the default value) the username is hidden and always the same as the email address.

User password settings

This section lets you define the password rules for users.

Required length

Specifies the minimum length a user password is allowed to be.

Require non letter or digit

Requires a users password to contain at least one character which is not a letter or a digit if enabled.

Require digit

Requires a users password to contain at least one digit if enabled.

Require lowercase

Requires a users password to contain at least on lowercase letter if enabled.

Max failed access attempts before lockout

Specifies the max amount of failed password attempts is allowed before the user is locked out of the site.

Hash algorithm type

Allows you to specify what hashing algorithm should be used to store the users password.

Options are:

• "PBKDF2.ASPNETCORE.V3"

• "PBKDF2.ASPNETCORE.V2"

• "HMACSHA256"

• "HMACSHA1"

Member password settings

This section allows you to define the password rules for members. This section is identical to the one for users.

User Default Lockout Time In Minutes

Use this setting to configure how long time a User is locked out of the Umbraco backoffice when a lockout occurs. The setting accepts an integer which defines the lockout in minutes.

The default lockout time for users is 30 days (43200 minutes).

Member Default Lockout Time In Minutes

Use this setting to configure how long time a Member is locked out of the Umbraco website when a lockout occurs. The setting accepts an integer which defines the lockout in minutes.

The default lockout time for users is 30 days (43200 minutes).

Allow concurrent logins

When set to false, any user account is prevented from having multiple simultaneous sessions. In this mode, only one session per user can be active at any given time. This enhances security and prevents concurrent logins with the same user credentials.

This section allows you to configure routing for your solution, all of these settings have either default values, or do not need to be configured. However, you might want to tweak these settings in some scenarios, for instance, if you're running in a load-balanced setup.

An example of a web routing config with default values, and a placeholder for the application URL can be seen here:

"Umbraco": {
  "CMS": {
    "WebRouting": {
      "TryMatchingEndpointsForAllPages": false,
      "TrySkipIisCustomErrors": false,
      "InternalRedirectPreservesTemplate": false,
      "DisableAlternativeTemplates": false,
      "ValidateAlternativeTemplates": false,
      "DisableFindContentByIdPath": false,
      "DisableRedirectUrlTracking": false,
      "UrlProviderMode": "Auto",
      "UmbracoApplicationUrl": "http://www.mysite.com/"
    }
  }
}

Using the webrouting options in code

The following is an example of how you can use code to get the value for the UmbracoApplicationUrl configuration key:

using Microsoft.Extensions.Options;
using Umbraco.Cms.Core.Configuration.Models;

namespace UmbracoDocs;

public class TestService
{
    private readonly IOptionsMonitor<WebRoutingSettings> _webRoutingSettings;

    public TestService(IOptionsMonitor<WebRoutingSettings> webRoutingSettings)
    {
        _webRoutingSettings = webRoutingSettings;
    }

    public void DocsExample()
    {
        var umbracoApplicationUrl = _webRoutingSettings.CurrentValue.UmbracoApplicationUrl;
    }
}