Introduction to ASP.NET Core

ASP.NET Core is the modern, cross-platform framework for building web applications and APIs on .NET. It runs on Windows, Linux, and macOS, handles incoming HTTP requests, and sends back responses such as HTML pages or JSON data. It is open source, fast, and the standard way to build web backends in C# today. Note that the old ASP.NET (4.x) and Web Forms are legacy and Windows-only — new projects should use ASP.NET Core on modern .NET. This guide shows the big picture and a first working web API.

What ASP.NET Core does

When a browser or mobile app sends a request like GET /students, ASP.NET Core:

1. Receives the HTTP request.
2. Routes it to the right piece of your code based on the URL and method.
3. Runs your logic (maybe reading a database).
4. Returns a response — HTML, JSON, a file, or a status code.

It supports several styles for organizing that code: Minimal APIs (compact, great for services), MVC controllers, and Razor Pages for server-rendered web pages. (See the companion article comparing them.)

Creating a web project

dotnet new web -o MyApi   # create a minimal web app
cd MyApi
dotnet run                # starts a local web server

The terminal prints a local address such as http://localhost:5000 that you open in a browser.

A minimal web API

Here is a small but complete API that returns data as JSON:

// Program.cs — a Minimal API on ASP.NET Core.

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

// Map a GET request for "/" to a handler that returns text.
app.MapGet("/", () => "ASP.NET Core is running!");

// Map "/students" to return a list — ASP.NET Core converts it to JSON automatically.
app.MapGet("/students", () => new[]
{
    new { Id = 1, Name = "Asha" },
    new { Id = 2, Name = "Rohan" }
});

// A route with a parameter taken from the URL, e.g. /greet/Meera
app.MapGet("/greet/{name}", (string name) => $"Hello, {name}!");

app.Run(); // start listening for requests

Visiting /students returns JSON; visiting /greet/Meera returns Hello, Meera!. ASP.NET Core handles the conversion to JSON for you.

Handling input and POST requests

APIs often accept data. ASP.NET Core can bind the request body straight into a C# type:

// A simple type representing the data we expect to receive.
record NewStudent(string Name, int Marks);

app.MapPost("/students", (NewStudent student) =>
{
    // 'student' is filled from the JSON the client sent.
    return Results.Created($"/students/{student.Name}",
                           new { message = $"Added {student.Name}" });
});

Results.Created(...) returns the correct HTTP 201 Created status. ASP.NET Core gives you helpers for common responses: Results.Ok, Results.NotFound, Results.BadRequest, and more.

Dependency injection, built in

ASP.NET Core has dependency injection (DI) baked in. You register services once and the framework hands them to your handlers:

builder.Services.AddSingleton<IClock, SystemClock>(); // register a service

app.MapGet("/time", (IClock clock) => clock.Now()); // clock is provided automatically

DI keeps code testable and loosely coupled — a core reason ASP.NET Core scales well to large apps.

Middleware

Requests pass through a pipeline of middleware components before reaching your handler — for logging, authentication, HTTPS redirection, and so on:

app.UseHttpsRedirection(); // every component inspects/modifies the request as it flows through

Common mistakes

• Starting with legacy ASP.NET / Web Forms. Those are Windows-only and no longer the path forward. Use ASP.NET Core on modern .NET.
• Confusing the order of middleware. Middleware runs top to bottom; put things like authentication before the endpoints that need it.
• Returning raw strings when JSON is expected. Return an object and let ASP.NET Core serialize it, or use Results.Json.
• Forgetting app.Run(). Without it, the server never starts listening.

FAQ

Minimal API or MVC controllers? Minimal APIs are great for small services and learning. MVC suits larger apps with many endpoints and shared conventions. See the next article.

Can ASP.NET Core serve HTML pages too? Yes — use Razor Pages or MVC views for server-rendered HTML, or pair it with a front-end framework.

Keep learning

• Hub: Learn .NET
• Next: ASP.NET: Web Forms vs MVC vs Razor Pages
• Related: Data Access with ADO.NET

Build real web APIs with a mentor in Jalgaon — join the waitlist for the Infoplanet .NET course at /courses/dotnet.