> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/umbraco-cloud/build-and-customize-your-solution/set-up-your-project/project-settings/environment-naming-and-appsettings.md).

# Environment Naming and Appsettings

Learn how an environment's name sets its DOTNET\_ENVIRONMENT value, and how to avoid issues when you name an environment Development.

Umbraco Cloud sets each environment's `DOTNET_ENVIRONMENT` value based on its name. The value decides which `appsettings.{Name}.json` file the environment loads. Naming an environment `Development` has side effects worth knowing before you create or rename one.

## How the Environment Name Affects Configuration

ASP.NET Core loads `appsettings.json` first, then layers `appsettings.{DOTNET_ENVIRONMENT}.json` on top of it. The values in the second file win wherever the two overlap.

Umbraco Cloud sets the environment variable `DOTNET_ENVIRONMENT` to the environment's alias. The alias is a lowercase version of the environment name with spaces replaced by dashes. Live is the exception and always uses `Production`, even after a rename. You can view or override the value under [Project Settings](/umbraco-cloud/build-and-customize-your-solution/set-up-your-project/project-settings.md#advanced) > Advanced.

Naming an environment `QA`, for example, applies `appsettings.QA.json` if that file exists in your project.

{% hint style="info" %}
Umbraco Cloud only sets `DOTNET_ENVIRONMENT`. On projects using `WebApplication`, the default from ASP.NET Core 7.0 (Umbraco 14), it takes precedence over `ASPNETCORE_ENVIRONMENT`. On upgraded projects that keep the older hosting model, `ASPNETCORE_ENVIRONMENT` takes precedence.
{% endhint %}

## Why the Name Development Is Different

.NET and Umbraco project templates use `Development` for local development, set in `launchSettings.json`. The name also switches on development behavior, because `env.IsDevelopment()` returns `true`.

On older projects, Umbraco Cloud named the [left-most mainline environment](/umbraco-cloud/begin-your-cloud-journey/project-features/environments.md) `Development` by default. Your project can use the name even if nobody on your team chose it.

When you name a Cloud environment `Development`, that environment takes over `appsettings.Development.json`, the same file your team uses for local development. The environment then runs in development mode.

The resulting issues tend to show up later, and they can look unrelated to the cause:

* Local connection strings or Umbraco Deploy settings apply in the cloud, or the other way around.
* Local development breaks after someone edits `appsettings.Development.json` for the cloud environment.
* Models Builder generates models on the cloud environment, even though you configured model generation for local use only.

{% hint style="warning" %}
An environment that runs as `Development` shows the developer exception page and keeps the Swagger UI enabled. Both can expose details about your implementation on a public URL. To limit this, enable [Public Access](/umbraco-cloud/build-and-customize-your-solution/set-up-your-project/project-settings/public-access.md) on the environment, or change its `DOTNET_ENVIRONMENT` value as described in [Option B](#option-b-override-the-variable-on-the-cloud-environment).
{% endhint %}

## File Name Casing

The appsettings file name must match `DOTNET_ENVIRONMENT` exactly, including casing. Umbraco Cloud sets this to the environment's lowercase alias. For example, an environment named `UAT` uses `appsettings.uat.json`. Live always uses `appsettings.Production.json`.

To confirm or override the value, go to [Project Settings](/umbraco-cloud/build-and-customize-your-solution/set-up-your-project/project-settings.md#advanced) > **Advanced**.

## Two Ways to Keep the Name Development

There is nothing wrong with the name `Development` itself. Some teams develop on the hosted environment and share settings with local development on purpose. Otherwise, decide who owns the name: your local machines or the cloud environment.

Option B is the smaller change, but you need to set the custom value again after every rename. Option A suits teams that want the portal name to match the configuration file name.

### Option A: Move Local Development to Its Own Name

Keep the cloud environment named `Development`, and give local development a new name, for example `Local`. The cloud environment keeps running in development mode, so consider enabling [Public Access](/umbraco-cloud/build-and-customize-your-solution/set-up-your-project/project-settings/public-access.md) on it.

1. Add an `appsettings.Local.json` file to your project, and move your local-only settings into it, such as connection strings, Umbraco Deploy local settings, and logging verbosity.

From Umbraco 17.7.0 and 18.2.0, the installer writes the connection string to `appsettings.Local.json` when you run the site as `Local`.

2. Add the file to `.gitignore` if it contains secrets.
3. Update `launchSettings.json` so your run profiles use the new name. .NET project templates set the name with `ASPNETCORE_ENVIRONMENT`, as shown below.

{% code title="Properties/launchSettings.json" %}

```json
{
  "profiles": {
    "MyProject": {
      "commandName": "Project",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Local"
      }
    }
  }
}
```

{% endcode %}

4. Update any code that checks `env.IsDevelopment()` to also check `env.IsEnvironment("Local")`. `Local` isn't `Development`, so `env.IsDevelopment()` returns `false` on your machine.

### Option B: Override the Variable on the Cloud Environment

Keep local development on `Development`, as the templates expect. Give the cloud environment a different configuration name, even though the portal still displays it as `Development`.

1. Go to **Configuration** > **Advanced** > **Runtime Settings** in the Cloud Portal, and select the environment.

![Runtime Settings panel with the Development environment selected and DOTNET\_ENVIRONMENT set to Development](https://3739769070-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPzKn70Piyd2fd5UkYZGf%2Fuploads%2Fgit-blob-002cae150458b4150d70509f257383994f95f060%2Fcloud-runtime-settings.png?alt=media)

2. Edit `DOTNET_ENVIRONMENT` to a value such as `CloudDev`. Changing the value restarts the site.
3. Add a matching `appsettings.CloudDev.json` file to your project with the settings that environment should use.

{% hint style="warning" %}
Renaming the environment resets `DOTNET_ENVIRONMENT` to the new alias, and overwrites your custom value. Set the custom value again after you rename the environment.
{% endhint %}

## Naming Checklist

Check the following before you create or rename an environment:

* [ ] Confirm whether an `appsettings.{Name}.json` file already exists in your project, and whether you want its values applied to this cloud environment.
* [ ] Check whether the name is `Development`. If it is, apply Option A or Option B above before you deploy.
* [ ] Match the casing of the name to the casing of the appsettings file exactly.
* [ ] Verify the value under **Configuration** > **Advanced** > **Runtime Settings** matches what you expect, after you create or rename the environment. A rename overwrites any custom value.

## Supported Umbraco Versions

This article applies to Umbraco 9 and later. Umbraco 7 and 8 projects run on .NET Framework instead of ASP.NET Core, so this guidance doesn't apply to them.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.umbraco.com/umbraco-cloud/build-and-customize-your-solution/set-up-your-project/project-settings/environment-naming-and-appsettings.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.