SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsumbraco-configuration

umbraco-configuration

Deployment & operations

View repository

Updated 10-27 05:04

About this skill

Umbraco configuration

Umbraco reads standard .NET configuration, so "configure Umbraco" means choosing the right settings for the environment and getting them from the right source. This skill ships three golden profiles that are validated against Umbraco's own options classes, its shipped JSON schema, and its production runtime validators — start from one instead of assembling settings from memory. General reference: Configuration.

Scenario Reference Assets Pick it when
Production, single server production-single-server.md production.json One IIS/Linux/container instance
Load balanced load-balanced.md load-balanced.json + a role overlay, ConfiguredServerRoleComposer.cs Two or more instances behind a load balancer, on any host
Azure App Service azure-app-service.md azure-app-service.json, azure-app-service-settings.json App Service + Azure SQL (+ Blob media). Scale-out also needs the load-balanced reference

How to decide

Ask where it will run and how many instances serve traffic. If the answer is "Azure" and more than one instance, use both the Azure and load-balanced references. If unsure, start with production single server — it is the subset the others extend. A developer machine needs none of them: a fresh install already runs in BackofficeDevelopment mode with no configuration, and a production profile will not boot there.

Open the scenario's reference before writing any configuration, and start from its asset. Each profile is a starting point: copy it to the target appsettings.<Environment>.json, replace the <Placeholder> tokens, then keep only what differs from Umbraco's defaults.

Rules that apply to every profile

  • Secrets never go in a committed file. Connection strings, SMTP passwords, unattended-install passwords, storage keys: user-secrets in development, environment variables or Key Vault references elsewhere. The profiles contain none, and the tests fail if one appears.
  • Environment variables use __ for :: Umbraco:CMS:Global:UseHttps is Umbraco__CMS__Global__UseHttps. Precedence, lowest to highest: appsettings.json, appsettings.{Environment}.json, user-secrets (Development only), environment variables, command line.
  • Verify every key against the project's own schema — appsettings-schema.Umbraco.Cms.json ships in the project root and matches the installed Umbraco version. Do not write a key from memory or from newer docs; the docs describe the latest version, and settings arrive in minors (for example Hosting:MachineIdentifier exists from 17.6, not in 17.5).
  • The schema is not always right. It is generated from property names, so a few sections are named differently from the keys Umbraco binds. Known cases on 17.5.3: DistributedJobs (schema says DistributedJobSettings) and Core:Debug (schema says Debug). When the docs and the schema disagree, trust the docs and confirm against the installed package, not against a newer Umbraco source checkout. A wrong section name is silently ignored — the setting just never applies — so check that the behaviour changed, not only that the app starts. Never edit the appsettings-schema*.json files to make a key validate: the build regenerates them. Use the bound key and tell the user their editor will not recognise it.
  • Production mode fails the boot on purpose unless UseHttps is on, UmbracoApplicationUrl is set, ModelsMode is Nothing and the app is a Release build. Treat a BootFailedException here as the profile doing its job.

Version compatibility

Targets Umbraco 17+ (profiles validated against 17.5.3). Server roles use IServerRoleAccessor / SetServerRegistrar, present throughout 17. Load balancing the backoffice itself is a 17+ option and is described, not shipped, in the load-balanced reference.

Validation

Assertions live in evals/evals.json; run them with the umbraco-skill-evaluator skill.

Coverage tier: Bound. The profiles are checked against Umbraco's options classes, schema and production validators (examples/golden-configs/), not booted in a load-balanced or Azure topology. When handing over, say "validated against Umbraco's configuration model", never "tested on Azure" or "tested under load balancing".