configuration-and-environments · git:20261102.5ba4ece · 2026-11-02 · sha256 a35dd534d5467d10

configuration-and-environments git:20261102.5ba4eceA

Immutable. This exact content never changes and is served at /api/v1/blob/a35dd534d5467d10.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_3tcuhuflfsd2g2sq/a35dd534d5467d10411e501b0227d36ae8f20cad7a16d3a9124601e957f33362.json

Then /plugin install configuration-and-environments@markdownregistry-3tcuhuflfsd2g2sq in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: configuration-and-environments
description: How settings are layered with appsettings files and environment variables, what the local and docker environments are, and how to add a new setting. Use when adding configuration, a connection string or environment-specific behaviour.
metadata:
  scope: shared
---

# Configuration and environments

## The rule

Settings come from `appsettings.json`, then `appsettings.<environment>.json`, then environment variables (`Section__Key`). The base file holds safe defaults for anywhere; the environment files hold what's only true for that environment.

| Environment | Set by | Used for |
| --- | --- | --- |
| `local` | `launchSettings.json` (`DOTNET_ENVIRONMENT=local`) | `dotnet run` on a developer machine: console logs, sample data on |
| `docker` | `docker-compose.yml` and the Dockerfile | `docker compose up`: logs to Seq, database in `/app/data`, sample data on |
| anything else | the host | Real deployments: base settings only, sample data off, HSTS on |

Settings that exist today:

| Key | Meaning |
| --- | --- |
| `ConnectionStrings:MovieReviews` | SQLite connection string. `Data Source=Name;Mode=Memory;Cache=Shared` keeps everything in memory. |
| `Database:SeedSampleData` | Seed sample data into an empty database (`sample-data`). |
| `Authentication:Authority`, `Authentication:Audience` | Turn on token authentication (`optional-token-auth`). |
| `Serilog:*` | Logging (`serilog`). |

## Steps

1. Put the safe default in `appsettings.json`. If the default is "off" or empty, still write the key so people can find it.
2. Override it only in the environment files that need a different value.
3. Read a single value with `configuration.GetValue<T>("Section:Key")`; read a group into a settings class with a `SectionName` constant and a `FromConfiguration(IConfiguration)` method, like `AuthenticationSettings`.
4. Document the key in `docs/RUN.md` if someone running the app might change it.
5. Tests override settings in memory (`integration-tests`), never by editing the JSON.

## Don't

- Put secrets, passwords or tokens in any `appsettings*.json` file. Use environment variables or user secrets.
- Check `IsEnvironment("local")` for behaviour that should be a setting. Add a setting instead.
- Read `Environment.GetEnvironmentVariable` directly. Go through `IConfiguration`.

## Check

``` bash
dotnet test
```