Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 52 ยท Getting Started

Anatomy of a Project

Tour an ASP.NET Core project file by file: Program.cs, the csproj and Web SDK, appsettings, launchSettings, wwwroot, plus the dotnet CLI commands you use daily.

So far our programs were single files. A real ASP.NET Core project is a small folder with a few well-known files, and each has a specific job. Knowing what lives where saves hours of confusion: why does the port change, why does a setting not apply, where do images go, what does that Sdk="Microsoft.NET.Sdk.Web" line really do.

This lesson is a guided tour. The project files themselves are read-only here because they need the dotnet command-line tool, but the two ideas that matter most, layered appsettings and launchSettings, are things we can demonstrate live with ordinary C# code.

Creating a project

The dotnet new command generates projects from templates. These are the ones you will use most often:

Terminal
dotnet new web      -o Shop      # empty project: Program.cs with one endpoint
dotnet new webapi   -o ShopApi   # API project: sample endpoint, OpenAPI document support
dotnet new mvc      -o ShopSite  # MVC with controllers and views
dotnet new razor    -o ShopPages # Razor Pages
dotnet new blazor   -o ShopUi    # Blazor web app

For this tutorial the web template is the best starting point: it contains almost nothing, so you can see every file. After dotnet new web -o Shop the folder looks like this:

TEXT
Shop/
  Shop.csproj                      project file (SDK, target framework, options)
  Program.cs                       the whole application
  appsettings.json                 default configuration
  appsettings.Development.json     overrides used in the Development environment
  Properties/
    launchSettings.json            how "dotnet run" starts the app locally
  wwwroot/                         static files (only if you add it)

bin/ and obj/ folders appear after the first build. They hold compiled output and intermediate files. They are generated, so they belong in .gitignore, not in source control.

The project file: Shop.csproj

A .csproj file is a small XML document that tells MSBuild how to compile the project.

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

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

</Project>

Every line carries meaning:

Line What it does
Sdk="Microsoft.NET.Sdk.Web" Selects the Web SDK. It adds a reference to the whole ASP.NET Core shared framework, enables web-specific build targets (publishing wwwroot, copying appsettings*.json) and turns on the web implicit usings. A plain console project uses Microsoft.NET.Sdk instead.
TargetFramework net10.0 Compile against .NET 10.
Nullable enable Turn on nullable reference type warnings; see the C# nullable lesson.
ImplicitUsings enable Add common global using directives automatically.

Because the SDK references the shared framework, you do not list packages for Kestrel, routing, minimal APIs, authentication or SignalR. You add <PackageReference> entries only for things outside it, such as Microsoft.EntityFrameworkCore.SqlServer or a third-party library.

What do the implicit usings add? For the Web SDK, roughly these namespaces:

  • System, System.Collections.Generic, System.IO, System.Linq, System.Net.Http, System.Threading, System.Threading.Tasks
  • Microsoft.AspNetCore.Builder, Microsoft.AspNetCore.Hosting, Microsoft.AspNetCore.Http, Microsoft.AspNetCore.Routing
  • Microsoft.Extensions.Configuration, Microsoft.Extensions.DependencyInjection, Microsoft.Extensions.Hosting, Microsoft.Extensions.Logging

That is exactly why Program.cs has no using lines, while our runner examples list them explicitly.

Program.cs and top-level statements

The template's entire application is:

C#
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

This uses top-level statements: the compiler wraps the code in a hidden Main method, and args is the command-line array. You can still declare types (records, classes, interfaces) below the statements, which is how our examples define helper classes.

Top-level statements must come before any type declarations in the file. If you put a class above the statements, the compiler reports an error. Keep the executable code on top and the types at the bottom.

appsettings.json and layering

appsettings.json holds default configuration. The template includes logging levels and an AllowedHosts entry:

JSON
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*"
}

The host reads appsettings.json first, then appsettings.{Environment}.json, then environment variables, then command-line arguments. Later sources win. Environment variables use a double underscore for nesting: Logging__LogLevel__Default=Debug. This layering lets you keep safe defaults in the file and override them per machine without editing code.

flowchart LR
    A["appsettings.json"] --> B["appsettings.Environment.json"]
    B --> C["Environment<br/>variables"]
    C --> D["Command-line<br/>arguments"]
    D --> E["Final value<br/>seen by your app"]

Each source is read in order; a later source replaces the value of an earlier one.

The next program builds the same layering with in-memory JSON so you can watch it work. The two JSON strings stand in for appsettings.json and appsettings.Production.json, and a dictionary stands in for environment variables.

C# Layered configuration, simulated

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Notice that every key is addressed with colons (Shop:Currency) regardless of the source. In a real app, WebApplication.CreateBuilder has already added all of these providers; you only read builder.Configuration. The configuration lesson goes deep, and environments and secrets covers what to do with passwords.

Never put passwords, API keys or connection strings with credentials into appsettings.json and commit them. Use environment variables, user secrets in development, or a secret manager in production.

launchSettings.json

Properties/launchSettings.json tells dotnet run (and your IDE) how to start the app on your machine:

JSON
{
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "applicationUrl": "http://localhost:5127",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Two settings matter: applicationUrl is the address Kestrel listens on, and ASPNETCORE_ENVIRONMENT is set to Development. The file is used only for local development. It is not part of a published app, so a deployed app takes its URLs and environment from the server (environment variables such as ASPNETCORE_URLS and ASPNETCORE_ENVIRONMENT, or container settings). A common beginner surprise: "it works on my machine in Development but behaves differently in production". The cause is often exactly this file.

Because launchSettings is plain JSON, we can read one with the same JSON tools your app uses:

C# Reading a launch profile

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

A semicolon separates multiple URLs. You choose a profile with dotnet run --launch-profile <name>.

wwwroot and static files

wwwroot/ is the web root: files inside it (CSS, JavaScript, images) can be served directly to browsers. They are served only if you add the static files middleware (app.UseStaticFiles()), and the web template does not enable it. Anything outside wwwroot is never served, which protects your source and configuration files. Static files, default documents and CORS covers this in detail.

The commands you will use daily

Terminal
dotnet run                 # build and start (uses launchSettings.json)
dotnet watch               # rebuild and restart whenever a file changes
dotnet build               # compile only
dotnet test                # run tests in a test project
dotnet publish -c Release  # produce a deployable folder
dotnet add package <name>  # add a NuGet package to the csproj
dotnet new gitignore       # add a standard .gitignore
dotnet dev-certs https --trust   # trust the local HTTPS development certificate

dotnet watch with hot reload is the most productive way to work: save a file, and the running app updates.

Where things go as the project grows

A small project fits in Program.cs. When it grows, a common layout is:

TEXT
Shop/
  Program.cs                  only wiring: builder, services, middleware, Map calls
  Endpoints/                  one file per feature with MapXxx extension methods
  Models/                     records and classes for requests, responses and domain
  Services/                   business logic, registered in DI
  Data/                       data access

Keep Program.cs short and move feature code into extension methods and services. Route groups and organizing endpoints shows how.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does Sdk="Microsoft.NET.Sdk.Web" in a csproj do?

    The Web SDK brings in the whole ASP.NET Core shared framework, so you do not add packages for Kestrel, routing or minimal APIs.
  2. 2. An appsettings.json value is Currency: USD, appsettings.Production.json says EUR and an environment variable says GBP. Which value does the app see?

    Later configuration sources override earlier ones. Environment variables come after the JSON files.
  3. 3. When is launchSettings.json used?

    It is a development-time file and is not part of a published app. Production gets URLs and environment from the host.
  4. 4. Where must top-level statements appear relative to type declarations in Program.cs?

    The compiler requires executable top-level statements before type declarations in the file.
  5. 5. Which files are served to browsers by default in a web project?

    Static file serving is opt-in via middleware, and it is limited to the web root.

Summary

  • A web project is small: .csproj, Program.cs, appsettings*.json, Properties/launchSettings.json and optionally wwwroot/.
  • The Web SDK references the whole ASP.NET Core shared framework and adds implicit usings.
  • Top-level statements hold the app; declare types after them.
  • Configuration is layered: appsettings.json, then the environment file, then environment variables, then the command line. Later wins.
  • launchSettings.json is for local runs only; production sets URLs and environment through the host.
  • dotnet run, dotnet watch, dotnet publish and dotnet new are the daily commands.

Next: The Host and the Builder