Skip to content
Tutorials Center
My learning

Topics

Lesson 1 of 52 ยท Getting Started

What Is ASP.NET Core?

Find out what ASP.NET Core is, how Kestrel and the request pipeline turn HTTP bytes into C# code, what ships with .NET 10, and how the examples here run.

ASP.NET Core is Microsoft's open-source framework for building web servers with C#. When a browser, a phone app or another program sends an HTTP request, ASP.NET Core receives it, runs your code and sends back a response. That response can be a JSON document, an HTML page, an image, a stream of live events or just a status code.

This tutorial teaches the framework from the first line of Program.cs to deployment. It assumes you know C# basics, so we link to the C# tutorial wherever a language feature appears and we do not repeat it. If a word like lambda, async or dependency injection is new, a short detour to the lambdas, async/await and dependency injection lessons will pay off quickly.

By the end of this lesson you will know the moving parts of a web app, what comes in the box with .NET 10, and how every example on this site runs a real server and talks to it, without a browser.

The big picture

Every ASP.NET Core application is made of the same four layers. Learn them once and every later lesson is just a closer look at one of them.

flowchart LR
    C["Client<br/>(browser, app, curl)"] --> K["Kestrel<br/>web server"]
    K --> M["Middleware<br/>pipeline"]
    M --> R["Routing"]
    R --> E["Endpoint<br/>(your code)"]
    E -.response.-> C

A request enters through Kestrel, passes through middleware and routing, and ends in your endpoint; the response returns the same way.

  1. Kestrel is the web server. It listens on a port, parses HTTP/1.1, HTTP/2 or HTTP/3 and builds an HttpContext object for each request.
  2. Middleware are small components in a chain. Each one can inspect or change the request, call the next one, and then inspect or change the response. Logging, error handling, authentication and compression are all middleware.
  3. Routing looks at the method and path (GET /products/7) and picks the matching endpoint.
  4. Endpoints are the code you write: a lambda in a minimal API, a controller action, a Razor Page, a Blazor component.

Because Kestrel runs inside your own process, an ASP.NET Core app is just a console program that happens to listen on a port. There is no separate server to install: dotnet run starts the whole thing.

One framework, several styles

ASP.NET Core is a family of programming models that share the layers above. You can mix them in one project.

Style You write Typical use
Minimal APIs Lambdas mapped to URLs JSON APIs, microservices
MVC / API controllers Classes with action methods Large APIs and server-rendered sites
Razor Pages A template plus a page class Form-driven websites
Blazor Components in C# and Razor Interactive web UI without JavaScript
SignalR, WebSockets, SSE Hubs or handlers Real-time updates
gRPC Contract-first services Fast service-to-service calls

This tutorial starts with minimal APIs because they show the framework with the least ceremony, then adds controllers, Razor and Blazor, data access, security and deployment.

What ships with .NET 10

You do not download ASP.NET Core separately. It is part of the .NET SDK, and the runtime ships a shared framework called Microsoft.AspNetCore.App. A project that uses the web SDK can use all of the following without installing a single NuGet package:

  • Kestrel, routing, minimal APIs, MVC, Razor Pages, Blazor
  • Authentication and authorization middleware, cookie and JWT handlers, antiforgery
  • Dependency injection, configuration, logging, options, health checks
  • Rate limiting, response compression, output caching, CORS, WebSockets
  • HttpClient and IHttpClientFactory
  • The built-in OpenAPI document generator

.NET 10 is a long-term-support (LTS) release, so it is a sensible target for new projects. A few things you meet later in the tutorial are newer additions: built-in validation for minimal APIs, server-sent events as a result type and a first-party OpenAPI generator.

Things that are not in the box: Entity Framework Core (a separate package, covered in EF Core overview), most database drivers, the xUnit test framework and third-party libraries such as Dapper or Polly.

How the examples on this site work

Most web tutorials ask you to open a browser tab. Our code runner has no browser, but it can do something equally useful: a program may start Kestrel on the loopback address and call it with HttpClient, all inside one process. The server code is exactly what you would write in a real project; only the startup and shutdown lines differ.

Here are the two differences to keep in mind:

In a real project In our examples
app.Run() blocks until you press Ctrl+C await app.StartAsync() returns once the server listens
The address comes from launchSettings.json or --urls builder.WebHost.UseUrls("http://127.0.0.1:0") asks the OS for a free port
A browser or a tool like curl is the client HttpClient plays the client
Logs print to the console builder.Logging.ClearProviders() keeps our output clean

Port 0 means "pick any free port". After the server starts, app.Urls lists the real address, so no two runs ever collide. Run this first example and read the output:

C# A server and a client in one program

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.

You see the status line, the Content-Type that ASP.NET Core chose for a returned string (text/plain), the Server: Kestrel header and the body. That is a full HTTP exchange, produced by a few lines of C#.

The using lines are explicit because the runner compiles a single plain C# file. In a real web project the SDK adds them for you through implicit usings, and the next two lessons show what a real Program.cs looks like.

What happens during one request

Let us make the pipeline visible. The next program adds two middleware components and an endpoint, records every step in a list and prints it afterwards. Notice the order: down through the layers, then back up.

C# The request journey, step by step

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.

Steps 1 and 2 happen on the way in, step 3 is the endpoint, and steps 4 and 5 run on the way out, in reverse order. This "onion" shape is the most important idea in the framework. The middleware pipeline lesson explores it fully.

The HttpContext object that travels through the chain holds the Request, the Response, the current user, the per-request service container and more. You will use it all the time, and HttpContext, Request and Response has a lesson of its own.

Hosting: a web app is a generic host

Behind WebApplication sits the generic host you may know from the C# hosting lesson. The host owns the things every long-running .NET program needs:

  • a dependency injection container (builder.Services)
  • configuration from JSON files, environment variables and the command line (builder.Configuration)
  • logging (builder.Logging)
  • lifetime: start-up, graceful shutdown on Ctrl+C or SIGTERM

ASP.NET Core adds Kestrel as one more hosted service plus the request pipeline. That is why the same patterns (constructor injection, options, ILogger<T>) work in controllers, middleware, background workers and your own classes. The host and builder lesson takes this apart.

In production, Kestrel is usually not the first thing the internet touches. A reverse proxy such as nginx, IIS, a cloud load balancer or YARP sits in front, terminates TLS, balances load and forwards requests to Kestrel. You will meet this in deployment.

Where the C# tutorial fits in

ASP.NET Core leans hard on modern C# features. This table points to the lessons that make the framework feel natural.

ASP.NET Core feature C# concept behind it
Endpoint lambdas Lambdas and delegates
Every handler touching I/O async/await, Task<T>
Services injected into handlers Dependency injection
Request and response shapes Records and classes
Nullable route and query values Nullable reference types
Cancelling work when the client leaves Cancellation tokens

If you have finished the C# tutorial, you already know the language side of everything in this tutorial. The older ASP.NET Core overview inside that tutorial is a short taster; this track goes much deeper.

A short history: from ASP to ASP.NET Core

Knowing where the framework came from explains many names you will meet in job ads and old Stack Overflow answers.

Era Product What it was
Late 1990s Classic ASP Scripts (VBScript) mixed with HTML, interpreted on every request, Windows and IIS only
2002 ASP.NET Web Forms Compiled C# or VB.NET, a page-and-controls model with server controls, view state and an event model that imitated desktop programming
2009 ASP.NET MVC Explicit controllers, views and routes with full control over HTML; Web API and SignalR followed as add-ons
2016 ASP.NET Core A rewrite: cross-platform, open source, modular, built on Kestrel, dependency injection and a middleware pipeline
2016 onward Yearly releases Core 1.0, 2.x, 3.x, then plain ".NET 5", 6, 7, 8, 9 and 10; MVC, Web API, Razor Pages and minimal APIs now share one stack

The classic products (Web Forms, MVC 5, Web API 2) ran on .NET Framework and the System.Web library, which ties them to Windows and IIS. They are in maintenance mode and receive security fixes only. Related Microsoft technologies of that period you may still see in legacy code are WCF (SOAP services; the modern replacement is gRPC or a plain HTTP API), ASP.NET AJAX and ASMX web services. Windows desktop frameworks such as WinForms and WPF also run on .NET Framework but are not web frameworks: see Windows desktop and MAUI.

.NET Framework itself is built from the CLR (the runtime that manages memory and runs compiled code), the Base Class Library and application models on top (Web Forms, WCF, WPF, WinForms). The modern .NET keeps the same ideas, but ships as a small cross-platform runtime. How .NET works explains CLR, assemblies and JIT in detail.

Migrating an old Web Forms or MVC 5 application is a rewrite of the web layer, not a recompile: the business logic in plain C# libraries moves over, the System.Web parts do not.

Common misunderstandings

  • "ASP.NET Core only runs on Windows." It runs on Windows, Linux, macOS and in containers. Linux containers are the most common production setup.
  • "I need IIS." No. Kestrel serves the app on its own. IIS is optional and, when used, forwards to Kestrel.
  • "ASP.NET is the same as ASP.NET Core." The old .NET Framework product (System.Web, Web Forms) is a different, Windows-only codebase. ASP.NET Core is the modern rewrite and the only one that gets new features.
  • "Minimal APIs are toys." They run on the same pipeline, router and serializer as controllers, and they scale to big services when you organize them well.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is Kestrel?

    Kestrel accepts connections, parses HTTP and hands each request to the middleware pipeline. It is part of your own process.
  2. 2. Two middleware components are registered, A first and then B. In what order do they see the response?

    The request travels A, B, endpoint. The response returns the opposite way: B, then A. Think of layers of an onion.
  3. 3. Why do our examples use UseUrls("http://127.0.0.1:0")?

    Binding to port 0 lets the OS choose a free port; afterwards app.Urls contains the real address.
  4. 4. Which of these is NOT part of the ASP.NET Core shared framework?

    EF Core is a separate package. Routing, authentication, and rate limiting all ship in Microsoft.AspNetCore.App.
  5. 5. In a real project, which call normally replaces await app.StartAsync() and StopAsync() in our examples?

    Run() starts the server and blocks until the app shuts down, for example after Ctrl+C.

Summary

  • ASP.NET Core is a cross-platform, open-source framework that turns HTTP requests into C# code.
  • Four layers matter: Kestrel (server), middleware (pipeline), routing, and endpoints (your code).
  • Minimal APIs, controllers, Razor Pages, Blazor, SignalR and gRPC share one foundation, so you can mix them.
  • .NET 10 ships the whole framework in the SDK; EF Core and test frameworks are separate packages.
  • A web app is a generic host with Kestrel added: DI, configuration, logging and lifetime come with it.
  • Our examples start Kestrel on 127.0.0.1:0, call it with HttpClient, then stop it with StopAsync().

Next: Your First Web App