Project Structure and Configuration

This chapter walks through the files of a new project, explains how configuration and environments work, and shows common ways to organize code as the app grows.

Files in a new project

dotnet new webapi -o TodoApi produces:

TodoApi/
├── Program.cs
├── TodoApi.csproj
├── TodoApi.http
├── appsettings.json
├── appsettings.Development.json
├── Properties/
│   └── launchSettings.json
├── bin/
└── obj/

The project file

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

</Project>

Microsoft.NET.Sdk.Web makes this an ASP.NET Core project: it references the shared ASP.NET Core framework and adds web-specific implicit usings. TargetFramework follows the SDK that created the project. Packages are added with the CLI, which writes a PackageReference into this file:

dotnet add package Microsoft.EntityFrameworkCore.Sqlite
dotnet list package

Program.cs in two halves

Every Program.cs has the same shape: register services on the builder, then build the app and describe the pipeline. Services must be registered before Build(); after that the container is read-only.

var builder = WebApplication.CreateBuilder(args);

// 1. Services for the dependency injection container
builder.Services.AddOpenApi();

var app = builder.Build();

// 2. Middleware pipeline and endpoints
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();
app.MapGet("/health", () => "ok");

app.Run();

appsettings.json and environments

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ConnectionStrings": {
    "Default": "Data Source=todo.db"
  },
  "Todo": {
    "PageSize": 20
  }
}

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.