Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Information on configuring Umbraco
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.
Are you looking for the RuntimeMinificationSettings?
Smidge, which held the RuntimeMinificationSettings configuration, was removed with the release of Umbraco 14.
You can install the Smidge package separately if needed. Learn more and see how to get started in the official Smidge documentation.
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:
The appsettings.json
file
An appsettings.{environment}.json
file
UserSecrets (Only when in development)
Environment variables
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.
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:
As an environment variable it becomes a variable with the name Umbraco__CMS__Unattended__UnattendedUserName
and a value of A.N. Other
.
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"
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:
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"
.
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:
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.
A complete list of all the configuration sections included in Umbraco, by default, can be seen here along with any keys they contain:
Information on the basic authentication section
Allows you to configure the basic authentication settings for Umbraco. A basic authentication section fully populated with default values can be seen here:
This is a comma-separated list of IP addresses you want to limit where the requests can come from.
If the value is set to true
, the basic authentication is enabled. By default, the value is set to false.
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.
A shared secret can be sent using an HTTP header to bypass the basic authentication. This can be valuable for server-to-server communication.
The header name used to compare the shared secret. By default, the value is set to X-Authentication-Shared-Secret
.
The value of the shared secret. Must be a string longer than 0 characters to be enabled. The default value is null
.
Information on the connection strings settings section
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:
We recommend using private cache for SQLite. You can read more on why shared cache is discouraged in the official SQLite documentation.
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:
If you're using Umbraco 9 SQL Server Compact database is supported instead of SQLite.
Because Umbraco cannot determine the provider name from the connection string in all cases. Umbraco follows Microsoft's convention for provider names, which involves specifying it as a postfix in the connection string name.
Information on the content dashboard settings section
Allows you to configure the Content Dashboard settings for Umbraco.
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.
Gets the path to use when constructing the URL for retrieving data for the content dashboard.
Gets the allowed addresses to retrieve data for the content dashboard.
No addresses specified indicates that any URL is allowed.
Information on the content settings section
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:
In the root level section, that is those without a seperate sub section like Imaging, you can configure:
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.
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.
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"]
.
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.
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.
This setting consists of a list of file extensions that editors shouldn't be allowed to upload via the backoffice.
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:
Enter the nodes id ("ContentId": 1
)
Enter the node's GUID ("ContentKey": "4f96ffdd-b969-46a8-949e-7935c41fabc0"
)
Use IContentLastChanceFinder to find the node.
Ids are usually local to the specific solution (so won't point to the same node in two different environments if you're using Umbraco Cloud).
GUIDs are universal and will point to the same node on different environments, provided the content was created in one environment and deployed to the other(s).
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.
This setting can be used to hide the Umbraco logo in backoffice.
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
.
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
.
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
.
This allows you to customize the preview badge being shown when you're previewing a node.
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.
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
.
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.
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".
See Content Version Cleanup for more details on overriding configuration and preventing cleanup of specific versions.
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.
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.
All versions that fall in this period will be kept.
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.
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.
This is a separated list of accepted image formats
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.
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.
Umbraco can send out email notifications, set the sender email address for the notifications emails here. To set the SMTP server used to send the emails, edit the standard Simple Mail Transfer Protocol (SMTP) section in the global section, see global settings for more information.
Information on debug settings section
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:
If this value is set to true, any scope that gets disposed without first being completed will trigger a log entry containing the stacktrace.
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
.
Information on the data types settings section
Allows you to configure the behavior of data types.
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.
Information on the Examine settings section
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
Information on the exception filter settings section
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:
Information on FileSystemProviders and how to configure them in Umbraco
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.
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
To configure the PhysicalFileSystem for a virtual folder, create a new filesystem with a root path and URL within the wwwroot folder. Refer to the example above and Extending FileSystemProviders for more information.
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
).
For more information see Extending FileSystemProviders.
To store media files in different systems, the type of provider must be changed. You can learn how to build a custom filesystem provider in the Extending Umbraco section.
At the moment when a file is saved, its full URL is stored as node property. This means that a configuration change will not apply to pre-existing media files but only to the ones saved after that.
If you want all your media files in the same location, you have to copy all pre-existing files to the new path. Additionally, you need to update the path property of the media item to the new URL. This can be either directly inside the database or by using the MediaService
.
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.
Information on the global settings section
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:
In the root level section, that is those without a seperate sub section like SMTP, you can configure
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.
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.
Adding additional values to the Reserves URLs and Reserved Paths will overwrite default/current values. This causes performance issues as well.
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.
Long session timeouts raise data exposure and unauthorized access risks. Thus, it's vital to establish a reasonable timeout to mitigate security risks.
The default language to use in the backoffice if a user isn't explicitly assigned one.
If you are running multiple sites, you don't want the top level node in your URL and can disable it with this setting.
Makes sure that all of the requests in the backoffice are called over HTTPS instead of HTTP when set to true.
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.
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.
By adding this you can specify a new/different folder for storing your CSS files, and still be able to edit them within Umbraco. It's also important to be aware of NetCores limitations regarding serving static file content here as well, by default, static content will only be served from the wwwroot folder. For more info see Extending filesystem
By adding this you can specify a new/different folder for storing your script/js files, and still be able to edit them within Umbraco. It's also important to be aware of NetCores limitations regarding serving static file content here as well, by default, static content will only be served from the wwwroot folder. For more info see Extending filesystem
By adding this you can specify a new/different folder for storing your media files, and still be able to edit them within Umbraco. It's also important to be aware of NetCores limitations regarding serving static file content here as well, by default, static content will only be served from the wwwroot folder. For more info see Extending filesystem
By adding this you can specify a new/different folder for storing your media files elsewhere on the server. Unlike UmbracoMediaPath
, this does not change the relative path that media is served from (e.g. /media) but allows for files to be stored outside of the wwwroot folder. Both relative paths (../../Shared/Media) and absolute server paths (X:/Shared/Media) are supported. For more info see Extending filesystem
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.
This is not a setting that commonly needs to be configured.
This value is primarily used on Umbraco Cloud for a small startup performance optimization. When this is true, the website instance will automatically be configured to not support load balancing and the website instance will be configured to be the 'primary' server for scheduling so no primary election occurs. This will save 1 database call during startup.
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"
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
.
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.
Deployment slots for a given Azure App Service share the same machine name. Without additional configuration, they will share a MainDomKey and therefore compete for MainDom status. This can be undesirable if attempting to deploy to a deployment slot followed by a swap with the production slot as once traffic has switched to the new instance the old production instance reboots and can re-acquire MainDom status. See What happens during a swap.
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.
Gets or sets the duration (in milliseconds) for which the MainDomLock release signal polling task should sleep. The default value is 2000ms.
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.
This setting specifies what view to render when there is no content on the site.
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.
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>"
Address of the SMTP host used to send the email from.
The port of the SMTP host, port 25 is a common port for SMTP.
The username used to authenticate with the specified SMTP server, when sending an email.
The password used to authenticate with the specified SMTP server, when sending an email.
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.
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.
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.
It's unlikely that you will have to change these settings unless you're using a load balanced setup.
Sets a value for the amount of time to wait between calls to the database on the background thread.
Sets a value for the time span to wait before considering a server stale, after it has last been accessed.
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.
Sets a value for the maximum number of instructions that can be processed at startup; otherwise the server cold-boots (rebuilds its caches).
Sets a value for the time to keep instructions in the database; records older than this number will be pruned.
Sets a value for the time to wait between each sync operation.
Sets a value for the time to wait between each prune operation.
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"
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.
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.
Information on the health check settings section
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:
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.
But let's go through the config one by one
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.
Settings relating to running the health checks automatically and sending out notifications.
Allows you to disable or enable all notifications methods, if set to false, the health checks will not automatically run.
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.
Specifies how often the health checks should run, as a DateTime string, in this example the checks will run every day (every 24 hours).
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:
Allows you to enable or disable specific checks.
Configures how verbose the reporting should be, the available options are:
Summary
Detailed
If set to true, the notification method will only run if a check has failed.
Allows you to set custom settings for a given implementation of a notification method, which settings are available depends on the specific implementation.
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
Information on the hosting settings section
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:
This setting specified the virtual path of the application, this path must start with a slash.
This setting specifies the location of the local temp storage.
Options:
Default
EnvironmentTemp
This setting allows you to run Umbraco in debug mode, by setting the value to true.
Gets or sets a value specifying the name of the site. The IWebHostEnvironment.ApplicationName is used if not specified
Information on the indexing section
This section allows you to configure how content is indexed for Examine.
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.
Information on the imaging settings section
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:
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.
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).
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).
Gets or sets the depth of the nested cache folders structure to store the images. Defaults to 8.
Gets or sets the length of the filename to use (minus the extension) when storing images in the image cache. Defaults to 12 characters.
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.
Contains configuration for image resizing.
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:
Information on the logging settings section.
The majority of logging related configuration has been moved to the Serilog configuration see Serilog settings for more information.
The following configuration is available in the Logging settings:
This setting allows you to configure the maximum log age for the internal audit log scrubbing. The default maximum age for the internal audit log is 24 hours. Change the duration with the MaxLogAge
key in the Logging settings.
To increase the maximum age of the entries in the audit log to 48 hours (2 days), set the value to 2.00:00:00
.
By default, all log files are saved to the umbraco/Logs
directory. You can define a custom directory for your log files by using the Directory
key in the Logging settings.
Set the value to ~/LogFiles
to add all log files to a LogFiles
directory in the root of the file structure.
Information on configuration allowing for the modification of default data installed in new projects
When Umbraco is installed for the first time, it creates a set of default data. These include a language, some Data Types, and some Media and Member Types.
In certain setups, you may want to take control over what is installed and opt-out of the creation of certain items.
When working in a team and using Umbraco Deploy for schema updates, consider your colleague's local project setup. The default installed data may not always be useful.
For example, if different languages are set up in Umbraco, it's better not to recreate them from the default language (en-US). In other situations, certain Umbraco default Data, Member and Media Types may not be required.
The following example configuration shows how this default data installation can be customized:
Each InstallData
setting can be one of the following values:
All
- all default data for the type will be installed (this is the default behavior if the configuration is omitted).
Values
- only the default data specified will be installed. For languages, the values are the ISO codes for the language. For all other types, the Guid for the type should be listed.
ExceptValues
- all default data except those specified will be installed.
None
- no default data of the type will be installed.
Be cautious when changing a Data Type configuration, as there are some dependencies between the different types. Make sure to check the reference information in the info
tab to ensure they are not referenced somewhere else.
For example, if you check the info tab of the Label (bigint)
Data Type, you can see that it is referenced by the Media Types
:
For DataTypes
, MediaTypes
and MemberTypes
the Guid identifiers for the default data items need to be provided in the Values
collection.
For Languages
, the Values
collection expects the standard language ISO codes to be provided. Given this code is enough to fully specify a language, it's possible to use this collection to install additional default data.
As an example, the following configuration would omit the default "English (United States)" language and instead install the "English (United Kingdom)" and "Italian" languages. As "English (United Kingdom)" is provided first, it would be created as Umbraco's default language for content creation.
The Guid values representing the default Data, Media, and Member Types installed are as follows.
Data types:
Media types:
Member types:
Information on the models builder settings section
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.
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.
When using Models Builder it is best practice to use the "Nothing" setting for all appsettings.json
files. If needed, the models mode can then be set to "SourceCodeManual" or "SourceCodeAuto" In the appsettings.json
file used on the local environment.
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
.
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.
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.
If you want to generate models outside the web project you can change the ModelsDirectory path. Suppose you have a data project called My.Website.Data the ModelsDirectory path should be:
~/../My.Website.Data/Models/
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.
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.
Information on how to change the default cap of upload size
Umbraco does not touch the default maximum allowed content size of the different services, but you can configure this yourself.
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:
maxAllowedContentLength
is specified in bytes, so this configuration would limit requests, and therefore uploaded files, to 2 megabytes
Are you hosting your site on Umbraco Cloud?
Umbraco Cloud uses IIS for hosting. This means you need to add the setting in a web.config
file for this to work on your Umbraco Cloud hosted sites. The upload size limit is 500mb on Umbraco Cloud.
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:
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.
Information on the NuCache settings section
This settings section allows you to specify the block size of the BTree used by NuCache. This is configured by default, so you don't need to configure this. However it is possible with something like:
This is how NuCache is configured by default. It is important to mention that the block size must be a power of two, at least 512, and at most 65536 (64K).
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.
It is possible to configure NuCache to work in memory only without reading/writing the NuCache database files.
Startup duration may increase for larger sites during a "warm boot" but smaller sites should see minimal impact.
The settings have not yet been exposed via the new configuration setup, instead you must configure with a composer.
Information on the plugins settings section
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.
Information on the package migration settings section
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:
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
.
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.
Information on the request handler settings section
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.
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.
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.
This setting tells Umbraco to use the default character replacements. If you don't want the default character replacements, set this to false.
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.
When managing entries from the collection, you need to do a couple of things for the change to be reflected:
Refresh the database cache from the "Published Status" tab in the Settings section of the backoffice.
Re-save and publish any node where you want the change reflected.
You can also use Publish with descendants... on the root node to update the URL for all descendants.
Information on the serilog settings section
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.
When you create a new Umbraco project the following Serilog section will be included by default:
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.
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 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:
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.
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:
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
Information on the runtime settings section
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 Runtime modes article.
TemporaryFileLifeTime
is specified as a timespan. The default value is one day - 1.00:00:00
.
Information on the security settings section
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:
At the root level of security you can configure the following
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.
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.
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".
The authentication cookie which is set in the browser when a backoffice user logs in, and defaults to UMB_UCONTEXT
.
The authentication cookie which is set in the browser when a backoffice user logs in is automatically set to the current domain.
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.
This section lets you define the password rules for users.
Specifies the minimum length a user password is allowed to be.
Requires a users password to contain at least one character which is not a letter or a digit if enabled.
Requires a users password to contain at least one digit if enabled.
Requires a users password to contain at least on lowercase letter if enabled.
Specifies the max amount of failed password attempts is allowed before the user is locked out of the site.
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"
This section allows you to define the password rules for members. This section is identical to the one for users.
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).
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).
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.
Information on the type finder settings section
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.
Information on the web routing settings section
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:
Are you on Umbraco Cloud?
It is not possible to change the UmbracoApplicationUrl setting
because the value is overwritten to the default Umbraco URL: https://[project-alias].[region].umbraco.io/
on Umbraco Cloud.
The following is an example of how you can use code to get the value for the UmbracoApplicationUrl
configuration key:
When set to true
Umbraco will check if any routed endpoints match a front-end request. This happens before the Umbraco dynamic router tries to map the request to a Umbraco content item. This setting should not be necessary as long as the Umbraco catch-all route is registered last.
Defines the value of Response.TrySkipIisCustomErrors when an error (404, 400, 500...) is encountered. In order to prevent IIS from displaying its own 404 or 500 pages, set this to true
to have your own page displayed.
When true, an internal redirect does not reset the alternative template, if any.
When true, the entire alternative templates feature of Umbraco is disabled.
validateAlternativeTemplates will not load the template from the database. If false
the template might not exists in the database. Otherwise the template need to exist in the database.
If set to true alternative templates will be validated
When true, content can't be found by their ID meaning that urls such as /1234 do not find content with ID 1234.
When you move and rename pages in Umbraco, 301 permanent redirects are automatically created, set this to true if you do not want this behavior.
Will set the URL provider mode, options are:
Default
: Indicates that the URL provider should do what it has been configured to do.
Relative
: Indicates that the URL provider should produce relative URLs exclusively.
Absolute
: Indicates that the URL provider should produce absolute URLs exclusively.
Auto
: Indicates that the URL provider should determine automatically whether to return relative or absolute URLs.
Defines the Umbraco application URL that the server should reach itself. By default, Umbraco will guess that URL from the first request made to the server. Use this setting if the guess is not correct (because you are behind a load-balancer, for example). Format is: http://www.mysite.com/
, ensure to contain the scheme (http/https) and complete hostname.
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.
Information on the unattended settings section
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:
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
Umbraco will only automatically install if this is set to true, and if there is a connection string pointing to an empty database.
If this is set to true, Umbraco will automatically run the upgrade migrations once the site has been upgraded.
This setting is used to specify the user name of the default admin user.
This setting is used to specify the email address of the default admin user.
This setting is used to specify the password of the default admin user.
Gets or sets a value indicating whether unattended package migrations are enabled.
This is true by default.