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.
Connection strings settings
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 shared cache for SQLite when using Umbraco, as it provides better performance and consistency when multiple connections may access the database simultaneously.
Content Dashboard Settings
Information on the content dashboard settings section
Allows you to configure the Content Dashboard settings for Umbraco.
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.
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 is supported instead of SQLite.
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.
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.
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:
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.
Using Kestrel
Runtime settings allow you to configure the MaxRequestLength and MaxQueryStringLength for kestrel. If you want to upload files larger than 50MB, 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.
Basic Authentication Settings
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:
AllowedIPs
This is a comma-separated list of IP addresses you want to limit where the requests can come from.
<?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>
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.
Health checks
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 disable the macro errors check, and 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, corresponding to the GUID of the health check to disable.
There is also a DisabledOn key representing the date the health check was disabled 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.
Type finder settings
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.
The tours section contains the "EnableTours" value which allows you to enable or disable tours. By default tours are enabled. If you wish to disable tours set the "EnableTours" to false, like so:
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 "ExceptionFilter" section to your config with the "Disabled" key set to true like so:
Examine settings
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:
Logging settings
Information on the logging settings section.
The majority of logging related configuration has been moved to the Serilog configuration see for more information.
The following configuration is available in the Logging settings:
MaxLogAge
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
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
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.
Directory
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.
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.
Data Types Settings
Information on the data types settings section
Allows you to configure the behavior of data types.
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
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:
Root level settings
In the root level section, that is those without a separate sub section like Imaging, you can configure:
Runtime minification settings
Information on the runtime minification settings section
Smidge with RunTimeMinification setting is scheduled for removal on Umbraco 14. You can install the package separately if needed and read the documentation on how to get started.
This section allows you to configure the runtime minifications (defaults shown), used by
Package Migration
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.
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 (default) 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 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 file extensions
If greater control is required than available from the DisallowedUploadedFileExtensions setting, 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:
Enter the nodes id ("ContentId": 1)
Enter the node's GUID ("ContentKey": "4f96ffdd-b969-46a8-949e-7935c41fabc0")
Enter the XPath to find the node ("ContentXPath": "/root/Home//TextPage[@urlName = 'error404'")
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).
When using XPath, there is no "context" (like, you can't find the node based on "currentPage") so needs to be a global absolute path.
The current implementation of XPath is suboptimal, marked as obsolete, and scheduled for removal in Umbraco 14. The replacement for ContentXPath is IContentLastChanceFinder.
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/assets/img/installer.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/assets/img/application/umbraco_logo_white.svg.
Macro errors
This setting allows you to specify how errors in macros should be handled.
Options:
Inline - Default Umbraco behavior, show an inline error within the macro but allow the page to continue rendering.
Silent - Silently suppress the error and do not display the offending macro.
Throw - Throw an exception.
Content - Silently suppress the error, and display custom content reported in the error event args.
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.
Show unroutable content warnings
If your routing setup leads to more than one document having the same URL, on publish a warning will be displayed:
Content published: The document does not have a URL, possibly due to a naming collision with another document. More details can be found under Info.
To suppress these warnings, set this option to false.
Content version cleanup policy
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.
To retain only the current draft and published version, set both the "keep" settings values to 0. The next time the scheduled job runs (hourly) all non-current versions (except those marked "prevent cleanup") will be removed.
Enable cleanup
When set to true, a scheduled job will delete historic content versions that are not retained according to the policy every hour.
When set to false, the scheduled job will not delete any content versions, regardless of any overridden settings for a Document Type.
The dotnet new template provides an appsettings.json file with the default value set to true for all sites.
Keep all versions newer than days
All versions that fall in this period will be kept.
Keep latest version per day for days
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.
Image file types
This is a separated list of accepted image formats
Auto fill image properties
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
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.
Use 'in memory' cache
This setting determines whether Smidge should save it's cached output in memory, or in a file on disk. If set to false, then the folder will be created at the wwwroot of your Umbraco site in a folder called 'Smidge'/
It is not possible to disable in memory caching when Timestamp is chosen as CacheBuster method.
Cache buster
Specifies mechanism for cache invalidation.
The options are:
Version - Caches will be busted when your assembly version changes, when the upstream Umbraco version changes and when the version string specified in Configuration changes.
AppDomain - Caches will be busted when the app restarts.
Timestamp - Caches will be busted based on a timestamp of the bundled files.
Manually changing the Cache buster version
If you use a CacheBuster setting of "Version" you can add an additional configuration option, also called 'Version' , which allows you to set a value that you can incremement manually, or via a build server to make sure the version number changes for Smidge and busts the cache.
The actual 'Version' number will not be visible in the url of the assets, this is because it is combined, along with the Umbraco Version from configuration and the your project assembly dll, and then once combined a 'hash' is generated to obscure these details.
in the HTML link thus: <link href='/sb/umbraco-backoffice-init-css.css.v7a71f91360259c5f7c3337f152b0df01eeee36f0' rel='stylesheet' type='text/css'/> (when Umbraco:CMS:Hosting:Debug:false)
So if you increased the Version in the configuration by 1 to 1235, all you would see is a different hash!
For production environments, it's recommended to set Cache Buster to 'Version' (you don't actually need to supply a version number, but if you do, you can control when the cache breaks, eg if a package has installed new assets) or to 'AppDomain'.
Another configuration option (of Smidge) is the "dataFolder" setting, this setting specifies what folder Smidge will use for its temporary data, it should not be necessary to change this either, it will only be used if UseInMemoryCache is set to false.
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.
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 global configuration of RichTextEditor will be removed in Umbraco 14 to support more rich text editors in the future. Instead, a new extension type called “tinyMcePlugin” will be added.
This settings section allows you to configure the behaviour of the rich text editor, everything from plugins to commands. Everything has a default value, so it's not required to configure any of this yourself.
Are you using custom configuration or plugins with TinyMCE?
In Umbraco 11 the TinyMCE version supported has been upgraded from version 4 to version 6. You need to migrate to the latest version if you are using TinyMCE plugins or custom configuration.
If your site is upgraded from an older version, follow the migration guides below to upgrade the TinyMCE version as well.
A config with all the values can be seen underneath. Since there are a lot of defaults configured, some of these have been omitted for the sake of readability. Anywhere something has been omitted it is shown with {...}.
Plugins
Allows you to specify what plugins should be enabled for the rich text editor as a comma separated list of the plugin names.
To learn more about how to use the plugins, see the article.
Valid elements
Allows you to specify the valid HTML elements for the rich text editor as well as the allowed properties. For instance, in the config above the a element is allowed, and it's allowed to have onclick, href, and many more attributes.
Invalid elements
Specifies invalid HTML elements for the rich text editor. For instance, in the config above the font element is not allowed.
Commands
Allows you to specify what commands should be available, as a list of object. These commands are the little buttons you find at the top of the editor, such as bold, italic, and so on.
When specifying these, every object should contain:
Alias - The alias of the command
Name - A friendly name descriping the command
Mode - The mode the command runs on
Custom config
Allows you to specify custom key value pairs for the rich text editor.
Examples
Remove default <p> tag.
Add custom styles to the Formats dropdown list in the Richtext Editor.
Use a text editor to find and replace \" with ". This will allow you to edit the JSON file in an easier-to-read format. Don't forget to add the \ back in when you are ready to paste the code back into your appsettings.json file.
Cloud API key
Allows you to specify a Cloud API key for the rich text editor. Set this if you want to use the service. After setting this the Backoffice automatically loads the plugins.js file from the cloud service, which is known as .
To learn more about how to use the Cloud API key, see the article.
You can go to and sign up for a free trial. You will get a Cloud API key that you can use to try out the premium plugins.
Hosting settings
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:
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 is used if not specified
Runtime settings
Information on the runtime settings section
Runtime settings allows you to configure the MaxRequestLength and MaxQueryStringLength for your application. Neither of these settings needs to be configured. If nothing is configured reqests and query string can be any size.
An example of a configuration could look something like:
MaxRequestLength is specified in kilobytes, limiting requests, and therefore uploaded files, to 2 megabytes. Additionally, it sets a maximum query string length of 90 characters.
Mode can have three values: BackofficeDevelopment (default), Development, and Production.
For more information, see the article.
Imaging settings
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 as default implementation). If you need to configure allowed image file types or auto fill image properties, you want to use 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:
Cache
Web routing
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?
Unattended
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.
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.
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:
HMAC secret key
Specifies the key used to secure image requests by generating a hash-based message authentication code (HMAC). This ensures that only valid requests can access or manipulate images.
To enable it, you need to set a secure random key. This key should be kept secret and not shared publicly. The key can be set through the IOptions pattern, or you can insert a base64 encoded key in the appsettings.json file. The key should ideally be 64 bytes long.
The key must be the same across all environments (development, staging, production) to ensure that image requests work for content published across environments.
Default Behavior
If the HMACSecretKey is not set, image requests are not secured, and any person can request images with any parameters. This may expose your server to abuse, such as excessive resizing requests or unauthorized access to images.
Key Length
The HMACSecretKey should be a secure, random key. For most use cases, a 64-byte (512-bit) key is recommended. If you are using HMACSHA384 or HMACSHA512, you may want to use a longer key (for example: 128 bytes).
Example Configuration
appsettings.json
Using the IOptions pattern
To generate the HMACSecretKey programmatically instead of hardcoding it in configuration files, use the IOptions pattern. The following example demonstrates how to generate a secure random key at runtime:
The HMACSecretKey must be kept secret and never exposed publicly. If the key is exposed, malicious users may generate valid HMACs and exploit server resources.
Testing the Configuration
To verify that your HMACSecretKey is working correctly:
Set the HMACSecretKey key in the appsettings.json file or via the IOptions pattern.
Make a request to an image URL with valid parameters and ensure it works as expected.
Modify the URL parameters or remove the HMAC signature and confirm that the request is rejected.
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.
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:
Try matching endpoints for all pages
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.
Try skip IIS custom errors
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.
Internal redirect preserves template
When true, an internal redirect does not reset the alternative template, if any.
Disable alternative templates
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.
Validate alternative templates
If set to true alternative templates will be validated
Disable find content by ID path
When true, content can't be found by their ID meaning that urls such as /1234 do not find content with ID 1234.
Disable redirect URL tracking
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.
URL provider mode
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.
Umbraco application URL
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 backoffice 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.
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
};
});
}
using System.Security.Cryptography;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.Configuration.Models;
public class HMACSecretKeyComposer : IComposer
{
public void Compose(IUmbracoBuilder builder)
=> builder.Services.Configure<ImagingSettings>(options =>
{
if (options.HMACSecretKey.Length == 0)
{
byte[] secret = new byte[64]; // Change to 128 when using HMACSHA384 or HMACSHA512
RandomNumberGenerator.Create().GetBytes(secret);
options.HMACSecretKey = secret;
var logger = builder.BuilderLoggerFactory.CreateLogger<HMACSecretKeyComposer>();
logger.LogInformation("Imaging settings is now using HMACSecretKey: {HMACSecretKey}", Convert.ToBase64String(secret));
}
});
}
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;
}
}
Security Settings
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:
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 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.
Member require unique email
By default Umbraco will not allow creation of more than one member account with the same email address. If you wish to allow this, set this value to false.
Allowed user name characters
Defines the allowed characters for a username.
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"
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.
User login duration
Umbraco provides protection from user enumeration attacks looking to identify valid backoffice login accounts. It does this by attempting to equalize the time taken for successful and failed logins.
The UserDefaultFailedLoginDurationInMilliseconds can be used to provide a more realistic expected time for a successful login if the default isn't appropriate. This will be used before actual successful logins are detected. UserMinimumFailedLoginDurationInMilliseconds provides a minimum duration for a failed login.
Configuration
Information on configuring Umbraco
In Umbraco 9+, we have moved away from the previous configuration using .config files, to instead using the .NET built-in configuration pattern. This means that there is no longer separate files for different configuration, the configuration is now primarily done using IConfiguration with different sources. E.g. The appsettings.json file.
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)
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 hierarchy.
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.
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 example above, and thus corresponds to this JSON chunk:
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 or 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.
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:
Configured by code
Request handler settings
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.
Install Default Data Settings
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:
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.
Convert file names to ASCII
This setting works the same as "Convert URLs to ASCII" above, but for Media item file names.
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.
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.
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;
}
}
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:
Data Type referenced by Media Type
Data Identifiers
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.
Reference
The Guid values representing the default Data, Media, and Member Types installed are as follows.
Data types:
Media types:
Member types:
Serilog settings
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.
Default configuration
When you create a new Umbraco project the following Serilog section will be included by default:
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
For information on what each of these levels means see .
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.
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:
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 . 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:
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
NuCache Settings
Information on the NuCache settings section
The NuCache settings allow you to configure different aspects of how cached content is stored and retrieved. Below are the details of the available settings and how they can be configured to optimize performance and compatibility with your project needs.
BTreeBlockSize
The block size must be a power of two. It should be at least 512 and at most 65536 (64K).
UsePagedSqlQuery
When UsePagedSqlQuery is set to False, the Fetch method is used instead of the QueryPaged method for rebuilding the NuCache files. This will increase performance on larger Umbraco websites with a lot of content when rebuilding the NuCache.
NuCacheSerializerType
The NuCacheSerializerType setting allows developers to specify the serialization format for NuCache content. This setting is particularly relevant for projects migrating from older versions of Umbraco that relied on JSON formats.
To use JSON serialization instead of the default MessagePack:
Using 'Program.cs'
Using 'appsettings.json'
Additional Settings
You can configure NuCache to work in memory only without reading/writing to 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.
public class DisableNuCacheDatabaseComposer : IComposer
{
public void Compose(IUmbracoBuilder builder)
{
var settings = new Umbraco.Cms.Infrastructure.PublishedCache.PublishedSnapshotServiceOptions
{
IgnoreLocalDb = true
};
builder.Services.AddSingleton(settings);
}
}
Global Settings
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:
Root level settings
In the root level section, that is those without a separate sub section like SMTP, you can configure
Reserved urls
A comma-separated 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
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.
Timeout
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.
Default UI language
The default language to use in the backoffice if a user isn't explicitly assigned one.
Hide top level nodes from path
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
Makes sure that all of the requests in the backoffice are called over HTTPS instead of HTTP when set to true.
Version check period
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
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
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
Umbraco scripts path
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
Umbraco media path
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
Umbraco media physical root path
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
Install missing database
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 conjunction with unattended installs.
Disable election for single server
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 occurs. This will save 1 database call during startup.
Database factory version
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
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.
The default implementation unless configured otherwise is FileSystemMainDomLock.
Main dom key discriminator
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 .
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
Gets or sets the duration (in milliseconds) for which the MainDomLock release signal polling task should sleep. The default value is 2000ms.
Id
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
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 <[email protected]>"
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.
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
Sets a value for the amount of time to wait between calls to the database on the background thread.
Stale server timeout
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
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
Sets a value for the time to keep instructions in the database; records older than this number will be pruned.
Time between sync operations
Sets a value for the time to wait between each sync operation.
Time between prune operations
Sets a value for the time to wait between each prune operation.
Sanitize TinyMce
Gets or sets a value indicating whether TinyMCE scripting sanitization should be applied.
The default value is false.
Distributed Locking Mechanism
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
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
Gets or sets a value representing the maximum time to wait whilst attempting to obtain a distributed write lock.
"SqlMainDomLock" - Available cross-platform, uses the database to control acquisition of MainDom status.
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.
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
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 AcceptUnsafeModelsDirectory 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/
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.
Include version number in generated models
When source code options are used, the Umbraco version number written to the generated code for each property of the model. This can be useful for debugging purposes but isn't essential. It causes the generated code to change every time Umbraco is upgraded and models are regenerated. In turn, this leads unnecessary code file changes that need to be checked into source control.
If you prefer to exclude this version number from being written to the generated code, set this value to false.
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.
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
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 for more information.
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 virtual folder. The only difference 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
For more information see .
Custom providers
To store media files in different systems, the type of provider must be changed. You can learn 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.
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. TThis example demonstrates using MediaFileManager to validate file existence and stream it back from a controller.
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Cms.Core.IO;
using Umbraco.Cms.Infrastructure.DependencyInjection;
using IHostingEnvironment = Umbraco.Cms.Core.Hosting.IHostingEnvironment;
namespace FilesystemProviders;
public class FilesystemComposer : IComposer
{
public void Compose(IUmbracoBuilder builder) =>
builder.SetMediaFileSystem(factory =>
{
IHostingEnvironment hostingEnvironment = factory.GetRequiredService<IHostingEnvironment>();
var folderLocation = "~/CustomMediaFolder";
var rootPath = hostingEnvironment.MapPathWebRoot(folderLocation);
var rootUrl = hostingEnvironment.ToAbsolute(folderLocation);
return new PhysicalFileSystem(
factory.GetRequiredService<IIOHelper>(),
hostingEnvironment,
factory.GetRequiredService<ILogger<PhysicalFileSystem>>(),
rootPath,
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
using System.IO;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Cms.Core.Hosting;
using Umbraco.Cms.Core.IO;
using Umbraco.Cms.Infrastructure.DependencyInjection;
namespace FilesystemProviders;
public class FilesystemComposer : IComposer
{
public void Compose(IUmbracoBuilder builder)
{
builder.SetMediaFileSystem((factory) =>
{
IHostingEnvironment hostingEnvironment = factory.GetRequiredService<IHostingEnvironment>();
var rootPath = Path.Combine("C:", "storage", "umbracoMedia");
var rootUrl = hostingEnvironment.ToAbsolute("/CustomPath");
return new PhysicalFileSystem(
factory.GetRequiredService<IIOHelper>(),
hostingEnvironment,
factory.GetRequiredService<ILogger<PhysicalFileSystem>>(),
rootPath,
rootUrl);
});
}
}
using System.IO;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.StaticFiles;
using Umbraco.Cms.Core.Cache;
using Umbraco.Cms.Core.Hosting;
using Umbraco.Cms.Core.IO;
using Umbraco.Cms.Core.Logging;
using Umbraco.Cms.Core.Routing;
using Umbraco.Cms.Core.Services;
using Umbraco.Cms.Core.Web;
using Umbraco.Cms.Infrastructure.Persistence;
using Umbraco.Cms.Web.Website.Controllers;
namespace FilesystemProviders;
public class MediaController : SurfaceController
{
private readonly MediaFileManager _mediaFileManager;
private readonly IHostingEnvironment _hostingEnvironment;
public MediaController(
IUmbracoContextAccessor umbracoContextAccessor,
IUmbracoDatabaseFactory databaseFactory,
ServiceContext services,
AppCaches appCaches,
IProfilingLogger profilingLogger,
IPublishedUrlProvider publishedUrlProvider,
MediaFileManager mediaFileManager,
IHostingEnvironment hostingEnvironment)
: base(umbracoContextAccessor, databaseFactory, services, appCaches, profilingLogger, publishedUrlProvider)
{
_mediaFileManager = mediaFileManager;
_hostingEnvironment = hostingEnvironment;
}
public IActionResult Index(string id, string file)
{
var path = _hostingEnvironment.MapPathWebRoot($"/media/{id}/{file}");
if (_mediaFileManager.FileSystem.FileExists(path))
{
var stream = _mediaFileManager.FileSystem.OpenFile(path);
stream.Seek(0, SeekOrigin.Begin);
var provider = new FileExtensionContentTypeProvider();
string contentType;
if (!provider.TryGetContentType(file, out contentType))
{
contentType = "application/octet-stream";
}
return new FileStreamResult(stream, contentType);
}
return new NotFoundResult();
}
}
