Getting Started with ASP.NET Core

This chapter installs the .NET SDK, creates a web project with dotnet new, runs it with dotnet run and dotnet watch, and sets up an editor and the HTTPS development certificate.

Install the .NET SDK

ASP.NET Core is not a separate download: it ships with the .NET SDK. One SDK install gives you the C# compiler, the dotnet command-line tool, the ASP.NET Core runtime and the project templates.

• Windows: run the installer from dotnet.microsoft.com, or select the "ASP.NET and web development" workload in Visual Studio.
• macOS: use the official .pkg installer or Homebrew.
• Linux: use your distribution's package manager or Microsoft's dotnet-install.sh script.

Open a new terminal and check the installation:

dotnet --version        # SDK used by default in this folder
dotnet --list-sdks      # every installed SDK
dotnet --list-runtimes  # look for Microsoft.AspNetCore.App

.NET alternates long-term support (LTS) and standard-term support (STS) releases. For a new project, pick the latest LTS or the latest stable release.

Create a project from a template

dotnet new scaffolds projects from templates. The ones you will use most for web work:

# Empty web app
dotnet new web -o HelloWeb

# Web API using minimal APIs
dotnet new webapi -o TodoApi
cd TodoApi

# All installed templates
dotnet new list

-o sets the output folder, which also becomes the project name. The Program.cs of the web template is only a few lines:

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

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

app.Run();

WebApplication.CreateBuilder prepares configuration, logging, dependency injection and the Kestrel web server with sensible defaults. MapGet registers a handler for GET requests to /, and app.Run() starts the server and blocks until the app shuts down. There is no Main method because the file uses C# top-level statements, and common namespaces come from implicit usings.

Run and reload

dotnet run                          # build, then run
dotnet run --launch-profile https   # use the https profile
dotnet watch                        # run and watch for file changes

dotnet run uses the first profile in Properties/launchSettings.json and prints the listening address, such as Now listening on: http://localhost:5123. Templates choose a random port per project, so read the address from the console.

dotnet watch applies edits to the running app with Hot Reload. Changes such as editing a method body are applied without a restart; for edits that cannot be applied in place, it offers to restart the app. Press Ctrl+R to force a restart.

Try the app from another terminal. The webapi template also creates a TodoApi.http file that Visual Studio and VS Code can send requests from.

# use the port printed by dotnet run
curl http://localhost:5123/weatherforecast

HTTPS development certificate

The https profile needs a trusted local certificate. The SDK creates and trusts one for you:

dotnet dev-certs https --trust
dotnet dev-certs https --check

On Windows and macOS this adds the certificate to the system trust store. On Linux, trusting it may need extra, distribution-specific steps.

Editor setup

• Visual Studio (Windows): the most complete experience, with debugging, profiling and a built-in HTTP client. Install the "ASP.NET and web development" workload.
• Visual Studio Code: install the C# Dev Kit extension for project management, IntelliSense, debugging and a test explorer. Works on Windows, macOS and Linux.
• JetBrains Rider: a cross-platform IDE with strong refactoring and built-in ASP.NET Core support.

Whatever the editor, the dotnet CLI stays the source of truth: projects build and run the same way in the terminal, in the IDE and in CI.

Summary

• Install the .NET SDK; ASP.NET Core is included.
• Create projects with dotnet new web or dotnet new webapi.
• Run with dotnet run and iterate with dotnet watch.
• Trust the development certificate with dotnet dev-certs https --trust to use HTTPS locally.