Installer connection string, default to appsettings.Development.json

[callumbwhyte]

Background

It has always frustrated me that Umbraco's installer defaults to putting a connection string in appsettings.json.

The .NET template ships a appsettings.Development.json file by default, and best practise would say this is where you should put your local development config.

.NET resolves configuration top down:

• appsettings.json
• appsettings.{Environment}.json
• User Secrets
• Environment Variables
• etc

Config in appsettings.Development.json is used above config in appsettings.json, etc.

Having connection strings in appsettings.json does actually present some potential issues when deploying beyond local...

The connection string may not be accessible on all environments – leading to a database unavailable error on boot. SQLite files are explicitly ignored in gitignore so won't be deployed either...

By default Umbraco installs a SQLite database with the corresponding umbracoDbDSN_providerName also set to use SQLite. Even if an environment specific connection string is configured, it is essential to also set the umbracoDbDSN_providerName too else the value will fallback to using what is set in appsettings.json. If the database type doesn't match (likely, don't want to use SQLite in prod) this leads to some confusing boot errors. Whilst setting the providerName is best practise and in the docs, it's not a totally obvious thing to remember IMO.

Change

I have adjusted the installer process to first check for the presence of a appsettings.Development.json file, and to use that instead to store the connection string. If it does not exist the appsettings.json file will be used instead, as currently.

When looping to find a JsonConfigurationProvider instance, we also check if the configuration file name contains "appsettings.{environment}.json".

An additional optional param was added to an already private method, and the order of those params was changed, so all uses of that method have been updated.

Testing

1. Create a blank Umbraco installation
2. Run the installer
3. Connection string will be added to application.Development.json instead of appsettings.json

Questions

• Are we happy with the hardcoded Development environment name? This is the default that .NET uses, and what Umbraco ships inside launch.json too, so feels sensible. We could default to attempting the current ASPNETCORE_ENVIRONMENT instead though...?

• Should there still be a something in appsettings.json? One benefit of the current approach is there will always be a connection string for every environment, even if it's invalid. This prevents the installer from being able to be run, e.g. in production. (the impact of this feels low... someone would only be able to create a SQLite file) One solution might be to have the installer place a blank connection string in appsettings.json as well.

Happy to take the guidance on best approach from HQ here!

[github-actions]

Hi there @callumbwhyte, thank you for this contribution! 👍

While we wait for one of the Core Collaborators team to have a look at your work, we wanted to let you know about that we have a checklist for some of the things we will consider during review:

• It's clear what problem this is solving, there's a connected issue or a description of what the changes do and how to test them
• The automated tests all pass (see "Checks" tab on this PR)
• The level of security for this contribution is the same or improved
• The level of performance for this contribution is the same or improved
• Avoids creating breaking changes; note that behavioral changes might also be perceived as breaking
• If this is a new feature, Umbraco HQ provided guidance on the implementation beforehand
• 💡 The contribution looks original and the contributor is presumably allowed to share it

Don't worry if you got something wrong. We like to think of a pull request as the start of a conversation, we're happy to provide guidance on improving your contribution.

If you realize that you might want to make some changes then you can do that by adding new commits to the branch you created for this work and pushing new commits. They should then automatically show up as updates to this pull request.

Thanks, from your friendly Umbraco GitHub bot 🤖 🙂

[Copilot]

Pull Request Overview

This PR modifies Umbraco's installer to prioritize storing connection strings in appsettings.Development.json over appsettings.json for better development practices. The change addresses the issue where connection strings were always placed in the base configuration file, which could cause deployment issues when local SQLite databases aren't available in production environments.

Key changes:

• Installer now checks for appsettings.Development.json first and uses it for connection string storage if available
• Falls back to appsettings.json if the development-specific file doesn't exist
• Updated the configuration provider selection logic to filter by environment-specific file names

[Matthew-Wise]

Hi Callum, thank you for the well thought out PR, I agree with your frustrations here, and have raised it with the HQ team to get some answers :)

[prjseal]

I agree with this idea totally and suggested solution looks great. The only time I can see it being an issue is maybe on Cloud when there is just a live environment, so the ASPNETCORE_ENVIRONMENT usage maybe needed there as you mentioned

[ronaldbarendse]

The database connection string should indeed be environment-specific, but I would argue it shouldn't be limited to the Development environment indeed. Using the current environment from IHostEnvironment.EnvironmentName should avoid having to directly read it from the environment variable.

There's also the appsettings.Local.json file that's currently only added when Umbraco is built in debug mode (so that's only when running from source, since we don't ship debug builds in NuGet packages):

Umbraco-CMS/src/Umbraco.Web.Common/Hosting/HostBuilderExtensions.cs

Lines 24 to 31 in 16c0de8

	#if DEBUG
	builder.ConfigureAppConfiguration(config
	=> config.AddJsonFile(
	"appsettings.Local.json",
	true,
	true));
	#endif

If this part is moved to the Program.cs file (just below WebApplication.CreateBuilder(args)), it would get shipped in the default Umbraco template and also used when your own site runs in debug mode. This will also prevent your local SQLite connection string to be stored in appsettings.Development.json and potentially used in a hosted dev environment. Since this file is conditionally added, it can be used whenever it's present (overriding the environment specific one).