Project Structure and Configuration

The environment name comes from ASPNETCORE_ENVIRONMENT (or DOTNET_ENVIRONMENT). Typical values are Development, Staging and Production; when nothing is set, the app runs as Production. appsettings.{Environment}.json is layered on top of appsettings.json, so it only needs the keys that differ.

The default builder reads configuration in this order, and later sources win:

1. appsettings.json
2. appsettings.{Environment}.json
3. User secrets (in Development only)
4. Environment variables
5. Command-line arguments

Nested keys use : in code and on the command line, and __ (double underscore) in environment variables:

export ASPNETCORE_ENVIRONMENT=Staging
export Todo__PageSize=50
dotnet run

# or pass the value as an argument to the app
dotnet run -- --Todo:PageSize=50

Keep secrets out of appsettings.json. During development, the Secret Manager stores them outside the project folder:

dotnet user-secrets init
dotnet user-secrets set "ConnectionStrings:Default" "Host=localhost;Database=todo;Username=dev;Password=dev"

Properties/launchSettings.json holds the local profiles (URLs and environment variables such as ASPNETCORE_ENVIRONMENT=Development). It is used only by dotnet run and IDEs and is not part of the published output, so production settings belong in environment variables or configuration files.

Organizing a growing app

ASP.NET Core does not enforce a folder layout. Common conventions:

• Endpoints/ or Controllers/: the HTTP surface, grouped by feature
• Services/: business logic registered in DI
• Data/: the EF Core DbContext and its Migrations/
• Models/ or Contracts/: entities and request/response types
• wwwroot/: static files served by the static file middleware

Larger solutions put the app under src/ and tests under tests/, tied together by a solution file (dotnet new sln, then dotnet sln add). Feature endpoints are often moved out of Program.cs into extension methods:

// Endpoints/TodoEndpoints.cs
public static class TodoEndpoints
{
    public static RouteGroupBuilder MapTodoEndpoints(this IEndpointRouteBuilder app)
    {
        var group = app.MapGroup("/todos");
        group.MapGet("/", () => Array.Empty<string>());
        return group;
    }
}

// Program.cs
app.MapTodoEndpoints();

Summary

• Program.cs registers services, then builds the middleware pipeline and endpoints.
• The .csproj file uses the Web SDK; packages come from dotnet add package.
• Configuration layers JSON files, user secrets, environment variables and arguments; the environment name selects appsettings.{Environment}.json.
• Folder layout is a team convention; extension methods keep Program.cs short.