Description
Type of issue
Missing documentation
Misleading documentation
What article/section is this about?
https://docs.umbraco.com/umbraco-cms/13.latest/reference/templating/modelsbuilder/configuration
https://docs.umbraco.com/umbraco-cms/13.latest/reference/templating/modelsbuilder/builder-modes
Describe the issue
The documentation mentions that configuration can be done in appsettings.json which is not incorrect.
"The following configuration option can be set in the application settings (in the appsettings.json file)."
and
"The mode is indicated by the Umbraco:CMS:ModelsBuilder:ModelsMode key in the configuration (appsettings.json files)."
In a multi-environment scenario, such as the one provided by Umbraco Cloud, we also get appsettings.Development.json (for the Development cloud environment), appsettings.Staging.json (for the Staging environment) and appsettings.Production.json (for the Live environment).
When using an Umbraco Cloud Development environment, by default, we have a scenario where the cloud environment and the local development environment share the same EnvironmentName, namely "Development".
This is, by ASP.NET Core default, stated in launchSettings.json in the environment variable "ASPNETCORE_ENVIRONMENT": "Development".
If we want to have different configurations for the Development environment on Umbraco Cloud and the local development environment, we can not do that without making some changes.
We could create a new appsettings file called appsettings.Whatever.json and then modify the environment variables in launchSettings.json to say "ASPNETCORE_ENVIRONMENT": "Whatever". This would effectively make the local environment use our newly created file which in turn allows us to make configurations that are only used when running locally.
However, this effectively changes our local EnviromentName to "Whatever" and that should not to be considered best practice since this name change changes and/or disables features that are built into ASP.NET Core that are dependent on that the environment is called "Development" and nothing else.
In such a scenario, it should be considered better practice to place your local ModelsBuilder configurations in launchSettings.json, like so:
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development",
"Umbraco__CMS__ModelsBuilder__ModelsMode": "SourceCodeManual",
"Umbraco__CMS__ModelsBuilder__FlagOutOfDateModels": true,
"Umbraco__CMS__ModelsBuilder__ModelsNamespace": "Umbraco.Cms.Web.Common.PublishedModels",
"Umbraco__CMS__ModelsBuilder__ModelsDirectory": "~/../TheNextAmazingWebProject.PublishedModels/Models",
"Umbraco__CMS__ModelsBuilder__AcceptUnsafeModelsDirectory": true,
"Umbraco__CMS__ModelsBuilder__DebugLevel": 1
}
As launchSettings.json is only used when running your project from Visual Studio and/or via dotnet run in CLI, this ensures that the configurations are only run in the local "Development" environment and preserves the EnvironmentName of the local environment as "Development" at the same time, thus not disabling or changing any of the program logic.
The documentation should be changed as it mentions appsetting.json and appsettings.json only as the place to put your Models Builder configurations.