Programmer's Picnic · Learn With Champak

Beginning ASP.NET Core

Lesson 1 · Create your first C# website and Web API from scratch

Prepared by Champak Roy

Now a step-by-step course!

This original combined introduction remains available, but new learners should follow the shorter numbered pages.

Open ASP.NET Core: 0 to Infinity — course index →

Beginner · 60–90 minutes

What you will learn

  1. Understand what ASP.NET Core is and where it fits in web development.
  2. Install the tools and start a working project.
  3. Understand Program.cs, endpoints, HTTP and routing.
  4. Create a simple HTML page and a JSON Web API.
  5. Explore Razor Pages and know what to learn next.

Prerequisites: Basic C# syntax helps, but is not mandatory. Windows, macOS or Linux can be used.

1. What is ASP.NET Core?

ASP.NET Core is Microsoft's modern, open-source, cross-platform framework for building websites, REST APIs and web applications using C# and .NET. The web browser sends an HTTP request; the server processes it and sends back HTML, JSON or another response.

.NET is the development platform, C# is the programming language and ASP.NET Core is its web framework. ASP.NET Core is different from classic ASP.NET Web Forms.

Common approaches include Minimal APIs for small endpoints, Razor Pages for server-rendered websites, MVC for controller-based applications and Blazor for interactive UI.

2. Install the required software

  1. Download a supported .NET SDK from dotnet.microsoft.com/download. Install the SDK, not just the runtime.
  2. Choose Visual Studio Code with C# Dev Kit or Visual Studio on Windows.
  3. Open your terminal (PowerShell, Command Prompt or a shell) and verify:
dotnet --version
dotnet --list-sdks

If the command is not found, restart the terminal after installation and check that the SDK was installed correctly.

3. Create your first ASP.NET Core app

Create an empty ASP.NET Core project with the SDK's built-in template:

dotnet new web -n FirstAspNetApp
cd FirstAspNetApp
dotnet run

The terminal will show a local URL such as http://localhost:5000 or another available port. Open the exact URL displayed in your browser. Press Ctrl+C to stop the server.

What are the files?

4. Understand Program.cs and routing

Replace Program.cs with the following complete example:

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

app.MapGet("/", () => "Hello from ASP.NET Core!");
app.MapGet("/hello/{name}", (string name) =>
    $"Hello, {name}! Welcome to Programmer's Picnic.");

app.MapGet("/api/course", () => new {
    title = "Beginning ASP.NET Core",
    teacher = "Champak Roy",
    level = "Beginner"
});

app.Run();

Run dotnet run again and visit these routes on the address displayed by the terminal:

Key idea: MapGet handles HTTP GET requests, WebApplication.CreateBuilder configures services and app.Run() starts serving requests.

5. Send an HTML response

Add the following endpoint before app.Run():

app.MapGet("/page", () =>
    Results.Content(
        "<h1>My First ASP.NET Core Website</h1><p>It works!</p>",
        "text/html"
    ));

Browse to /page. You have returned HTML from a server route. This is a simple demonstration only; production sites typically use Razor, Blazor, MVC views or separate frontend assets rather than assembling HTML as strings.

6. Your first POST API

Add this endpoint before app.Run():

app.MapPost("/api/greet", (GreetingRequest request) =>
    Results.Ok(new { message = $"Hello, {request.Name}!" }));

// Add this declaration after app.Run(), at file scope:
record GreetingRequest(string Name);

Send a request using a terminal or API client (replace the port with yours):

curl -X POST http://localhost:5000/api/greet -H "Content-Type: application/json" -d "{\"name\":\"Asha\"}"

On Windows PowerShell, use Invoke-RestMethod instead:

Invoke-RestMethod -Uri "http://localhost:5000/api/greet" -Method Post -ContentType "application/json" -Body '{"name":"Asha"}'

Expected JSON response: {"message":"Hello, Asha!"}. Unlike GET, POST usually sends data in a request body.

7. Next step: Razor Pages

Razor Pages lets you build server-rendered web pages using .cshtml files and C# page models. Start a new project:

dotnet new webapp -n MyRazorSite
cd MyRazorSite
dotnet run

Explore the Pages folder, especially Index.cshtml and its associated page model. The webapp template is different from the earlier empty web template.

Follow the official Razor Pages tutorial for creating a database-backed site.

8. Practice and self-check

  1. Create a route /about that displays your name.
  2. Create /square/{number:int} that returns the square of an integer.
  3. Create /api/students returning a JSON array of three students.
  4. Explain what happens when a user opens /hello/Asha.
  5. What is the difference between a .NET SDK, ASP.NET Core and C#?

Mini-project: Build a course-catalog API with GET /api/courses and GET /api/courses/{id:int}. Return a meaningful not-found response for unknown IDs.

9. Official resources and downloads