C# Reference ยท .NET, Tools and Concepts
ASP.NET Core overview
Reference overview of ASP.NET Core: WebApplication, the request pipeline and middleware, dependency injection, endpoints, configuration and app models.
ASP.NET Core is the web framework of .NET. It is cross-platform, open source and built around a small idea: an HTTP request travels through a pipeline of middleware components, and at the end an endpoint produces the response. Everything else (routing, authentication, static files, JSON, compression, logging) is a piece you add to that pipeline or to the dependency injection container.
A modern app starts with WebApplication.CreateBuilder(), registers services on the builder, calls Build(), adds middleware and endpoints on the resulting WebApplication, and runs it. The same host also runs Kestrel, the built-in cross-platform web server.
var builder = WebApplication.CreateBuilder(args); builder.Services.AddSingleton<Clock>(); // register services var app = builder.Build(); // freeze the service container app.MapGet("/", () => "Hello"); // add endpoints app.Run(); // start Kestrel and block
Try it
The editors on this site have no Web SDK implicit usings, so web programs name their namespaces. The demo starts Kestrel on the loopback address, calls itself with HttpClient and shuts down.
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.
Order matters: middleware runs in the order you add it, and each one decides whether to call next. A middleware that does not call next ends the request ("short-circuits").
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.
Syntax
The pieces of a typical Program.cs, in the order they must appear:
var builder = WebApplication.CreateBuilder(args); // 1. Services (before Build) builder.Services.AddControllers(); builder.Services.AddScoped<IOrderService, OrderService>(); var app = builder.Build(); // 2. Middleware pipeline (order matters) app.UseExceptionHandler("/error"); app.UseHttpsRedirection(); app.UseStaticFiles(); app.UseRouting(); app.UseAuthentication(); app.UseAuthorization(); // 3. Endpoints app.MapControllers(); app.MapGet("/health", () => "ok"); app.Run();
| Part | Role |
|---|---|
WebApplicationBuilder |
Collects configuration, logging, services and the web host settings. |
builder.Services |
The DI container's registrations (AddSingleton, AddScoped, AddTransient). |
WebApplication |
Both the middleware pipeline builder (Use...) and the endpoint route builder (Map...). |
HttpContext |
Everything about one request: Request, Response, User, RequestServices. |
| Endpoint | The code that finally handles a request: minimal API handler, controller action, Razor Page, Blazor component, SignalR hub, gRPC service. |
Application models you can mix in one app:
| Model | Best for |
|---|---|
| Minimal APIs | HTTP APIs with little ceremony. |
| MVC controllers | Larger APIs and server-rendered views, with filters and conventions. |
| Razor Pages | Page-focused server-rendered sites. |
| Blazor | Interactive UI written in C# (server or WebAssembly). |
| gRPC, SignalR | Binary RPC and real-time connections. |
Usage notes
- Order of
Usecalls is the behavior. Authentication must run before authorization, exception handling goes first, and static files usually come early so they skip the rest. - Services are frozen at
Build(). Registering a service afterbuilder.Build()is not possible; the container is built once. - Lifetimes: singleton lives for the whole app, scoped lives for one request, transient is created on each resolve. Injecting a scoped service into a singleton is a classic bug.
- Dependency injection is built in. Handlers and controllers receive services through parameters or constructors (Options and configuration).
- Environment:
ASPNETCORE_ENVIRONMENT(Development,Staging,Production) switches behavior such as the developer exception page and whichappsettings.{Environment}.jsonis loaded. - Kestrel is production-ready and usually sits behind a reverse proxy or load balancer that terminates TLS and compression.
- Everything is async. Handlers return
TaskorValueTask; blocking calls waste thread-pool threads under load. - Never trust request data. Bind to typed models, validate, and encode output; see Secure C#.
- Hosting model:
WebApplicationis a specialization of the generic host, so background services and the same logging/config stack work in web apps too.