Chapter 3: Your first application

Introduction

This chapter introduces the workflow of creating, running, inspecting, and lightly extending a template-based ASP.NET Core application.

• Template-based application starting point: Explain that an ASP.NET Core template provides the basic code required to build an application and serves as the starting point for most new apps.
  Why it matters: Starting from a template lets you focus on understanding and customizing an application instead of creating its basic structure from scratch.
• Initial application workflow: Describe the chapter's initial application-building sequence: create an app from a template, restore its dependencies, compile it, run it, and view its simple Hello World response.
  Why it matters: This is the basic path from a generated project to a running ASP.NET Core application.
• Application structure and extensions: Summarize the chapter's later exploration: inspect the files and minimal C# code in the generated application, then extend it to serve static files and expose a simple JSON API.
  Why it matters: Recognizing the project structure and these small extensions provides a foundation for understanding how an app runs and produces responses.

Key terms: template, ASP.NET Core application, dependencies, compile, run, Hello World, project layout, Program.cs, static files, API

3.1 A brief overview of an ASP.NET Core application

This section outlines how an ASP.NET Core application turns an incoming HTTP request into a response through Kestrel, HttpContext, middleware, and an endpoint.

• ASP.NET Core request flow: Trace the path of a request through the ASP.NET Core application: a reverse proxy can forward it to Kestrel, Kestrel creates an HttpContext, middleware processes it, and endpoint code generates the final response. Describe middleware as a pipeline of components that can perform common work before the endpoint runs.
  Why it matters: This request flow is the foundation for understanding where application code runs and how ASP.NET Core handles web requests.
• HttpContext request container: Describe HttpContext as the .NET object Kestrel creates for a single request and its associated response. Explain that it begins with HTTP request and configuration details and can hold request-specific services, loaded data, properties, and errors as the request moves through the application.
  Why it matters: HttpContext is the shared request-specific object that application components use while processing a request.

Key terms: reverse proxy, Kestrel, HttpContext, middleware pipeline, endpoint middleware, MVC, request-specific services, HTTP request

3.2 Creating your first ASP.NET Core application

This section introduces the first minimal API application, the basic local application workflow, and the main ASP.NET Core template types.

• First minimal API purpose: Describe the first application as a minimal API that returns "Hello World!" when its HTTP API is called, and explain that it illustrates fundamental .NET application-building and running concepts.
  Why it matters: This small application provides the concrete starting point for learning how an ASP.NET Core app is created and executed.
• Local application workflow: Trace the four basic steps for getting an ASP.NET Core application running locally: generate a base project from a template, restore NuGet packages and dependencies, build the application into compiled artifacts, and run the compiled application.
  Why it matters: These steps are the recurring workflow for turning an ASP.NET Core template into a running local application.
• ASP.NET Core template choices: Distinguish the main ASP.NET Core template categories described here by their output and typical consumers: minimal APIs and web APIs provide data for SPAs or mobile apps, while Razor Pages and MVC applications generate server-side HTML for users viewing pages in a browser.
  Why it matters: Choosing a template aligned with the intended client helps you begin with the appropriate application style.

Key terms: minimal API, HTTP API, Hello World!, Generate, Restore, Build, Run, NuGet, template, Minimal API applications

3.2.1 Using a template to get started

This section creates a first minimal API project from the ASP.NET Core Empty template using Visual Studio or the .NET CLI and clarifies the resulting project and solution structure.

• Template-based project creation: Describe how an ASP.NET Core template quickly creates a minimal API application and configures many of its fundamental pieces. State that both Visual Studio and the .NET CLI provide templates for web applications, console applications, and class libraries.
  Why it matters: Templates provide the ready-made starting point you will build and run in the following sections.
• Visual Studio template settings: Trace the Visual Studio workflow for creating the application: choose the C# ASP.NET Core Empty template, provide the project location and names, and create it with the specified additional settings. State the relevant settings: .NET 7.0, HTTPS enabled, Docker disabled, and top-level statements enabled by leaving “Do not use top-level statements” unchecked.
  Why it matters: Selecting these options produces the same basic application configuration used by the chapter.
• Projects and solutions: Explain that a .NET project is a unit of deployment compiled into a DLL or executable, whereas a solution is a Visual Studio container for developing multiple projects together. State that the example solution has one project and that a CLI-created project has no .sln file unless one is explicitly generated with additional CLI templates.
  Why it matters: This distinction helps you understand why Visual Studio shows a solution file while a command-line-created project may not.

Key terms: template, minimal API application, Visual Studio, .NET CLI, ASP.NET Core Empty, C#, NET 7.0, Configure for HTTPS, Enable Docker, Do not use top-level statements

3.2.2 Building the application

This section explains how the .NET CLI restores NuGet dependencies and builds an ASP.NET Core project into runnable binaries.

• NuGet dependency restoration: Explain that ASP.NET Core projects declare external NuGet dependencies in the .csproj file and that dotnet restore downloads local copies and references them for the project.
  Why it matters: Your project cannot reliably build or run until its declared package dependencies are available locally.
• Application build process: Describe how dotnet build compiles the application, checks for errors, and produces runnable output binaries when no problems are found.
  Why it matters: Building turns the source project into the binaries that dotnet run can execute.
• CLI command automation: State that dotnet restore, dotnet build, and dotnet run are normally run from the project folder and that build and run implicitly perform earlier required steps, while Visual Studio also performs these actions automatically.
  Why it matters: Knowing which steps are automatic helps you choose when an explicit restore or build is actually needed.

Key terms: NuGet package manager, NuGet dependencies, dotnet restore, .csproj, PackageReference, dotnet build, compile, output binaries, dotnet run, .NET CLI

3.3 Running the web application

This section shows how to run the new ASP.NET Core app from Visual Studio or the .NET CLI and verify its Hello World response.

• Application launch methods: Describe how to run the application either from Visual Studio or from the command line, including the Visual Studio green arrow/F5 option and the dotnet run command.
  Why it matters: You need to be able to start the application before you can test its endpoints or change its behavior.
• Browser URL and response: Explain how the browser reaches the running app: Visual Studio opens the appropriate URL automatically, whereas after dotnet run you manually open the URL printed on the command line. State that requesting / returns the plain-text Hello World response.
  Why it matters: Seeing the response in a browser confirms that the app is running and that its endpoint handled a request.
• Development certificate prompt: State that the first Visual Studio run may ask to install a development certificate, and explain that installing it prevents browser warnings about an invalid certificate.
  Why it matters: Recognizing this prompt helps you run the local app without mistaking a certificate warning for an application failure.

Key terms: Visual Studio, F5, dotnet run, .NET CLI, URL, endpoint, path /, Hello World!, plain-text response, development certificate

3.4 Understanding the project layout

This section orients you to the files, folders, and Visual Studio nodes in a newly created ASP.NET Core web application.

• Solution and project structure: Describe the relationship between the top-level solution folder, the solution (.sln) file, and the nested project folder in a new ASP.NET Core application.
  Why it matters: Knowing which level is the solution and which is the project helps you find and manage the files that define your application.
• Project file responsibilities: Explain that the .csproj file describes how to build the project and declares additional NuGet package dependencies, and state how Visual Studio lets you open it.
  Why it matters: The project file is the central place where the project’s build definition and package requirements are declared.
• Visual Studio special nodes: Describe the roles of launchSettings.json, Dependencies, and Connected Services in Visual Studio’s project view, including which items do not correspond to physical folders on disk.
  Why it matters: This prevents you from confusing Visual Studio’s organizational nodes with files and folders that physically exist in the project.
• Runtime configuration and entry point: State that appsettings.json and appsettings.Development.json provide runtime configuration settings, while Program.cs is the C# file that configures and runs the application.
  Why it matters: These files separate runtime settings from the code that sets up and starts the ASP.NET Core application.

Key terms: solution folder, solution (.sln) file, project folder, Solution Explorer, .csproj, WebApplication1.csproj, NuGet packages, Dependencies, Properties, launchSettings.json

3.5 The .csproj project file: Declaring your dependencies

This section explains how the .csproj project file tells .NET how to build an application and how to add reusable NuGet package dependencies.

• Project file build declarations: Describe the role of a .csproj file in a .NET application, including that it declares the project type, target framework, and package dependencies required by .NET tooling to build the project.
  Why it matters: The project file is where the build tools learn what application they are building and what it needs.
• Simplified SDK project format: Explain how the modern ASP.NET Core project-file format is simplified: the SDK attribute supplies default build settings, source files are included implicitly, and package references no longer require DLL paths, explicit file lists, or the older packages.config approach.
  Why it matters: The compact format makes project files easier to read and edit, especially when working across platforms.
• NuGet package references: Explain that NuGet provides reusable .NET libraries and describe adding one with dotnet add package <packagename>, which adds a PackageReference to the .csproj, restores the package, and makes its namespaces and classes available to project code.
  Why it matters: NuGet lets an application reuse common capabilities such as database access or JSON handling instead of rebuilding them from scratch.

Key terms: .csproj, project file, TargetFramework, NuGet packages, .NET CLI, Sdk, Project element, implicit file includes, PackageReference, packages.config

3.6 Program.cs file: Defining your application

This section explains how Program.cs uses top-level statements, WebApplicationBuilder, WebApplication, endpoints, and Run() to configure and start a minimal ASP.NET Core application.

• Top-level statement entry point: Explain how top-level statements replace an explicitly declared Main method in modern ASP.NET Core templates. State that the compiler generates the application entry point and that command-line arguments remain available through the implicit args variable.
  Why it matters: This explains why Program.cs can contain startup code directly without a visible Program class or Main method.
• Builder and application construction: Describe the CreateBuilder-to-Build sequence: WebApplication.CreateBuilder creates a WebApplicationBuilder for configuration, and Build() creates the WebApplication. Explain that the builder pattern permits configuration to be completed before the complex application object is created.
  Why it matters: The builder-then-build pattern is the foundation for configuring an ASP.NET Core app before it begins serving requests.
• Default builder configuration: State the major capabilities configured by WebApplicationBuilder by default: configuration, logging, services, and hosting with the Kestrel web server. Describe these as defaults that can be used or extended even when the simple app does not explicitly configure them.
  Why it matters: Knowing the defaults helps explain why a small Program.cs still has configuration, dependency registration, logging, and a web server available.
• Middleware and endpoint roles: Distinguish middleware from endpoints in a WebApplication. Describe middleware as sequential request-processing components and endpoints as definitions of how to generate a response for a particular request URL.
  Why it matters: Middleware and endpoints are the two building blocks used to determine how an ASP.NET Core application processes requests.
• Minimal GET endpoint mapping: Explain how MapGet maps a GET request for a URL path to a delegate that generates the response. Apply the default example by stating that MapGet("/", ...) returns the plain-text string Hello World! for a GET request to the root path, and distinguish GET from POST at a basic level.
  Why it matters: Mapping endpoints is how a minimal API declares what requests it accepts and what responses it sends.
• Application startup with Run: Trace when the application begins accepting HTTP requests: configuring the builder and WebApplication does not handle requests, but calling Run() starts the HTTP server listening. State that the WebApplication contains application configuration and the Kestrel server that listens for requests and sends responses.
  Why it matters: This separates application setup from the moment the web server becomes operational.

Key terms: top-level statements, Main, args, implicit using statements, WebApplicationBuilder, WebApplication, CreateBuilder, Build, builder pattern, configuration

3.7 Adding functionality to your application

This section introduces the standard Program.cs setup sequence and previews how services, middleware, and endpoints add behavior to an ASP.NET Core application.

• Application setup sequence: Trace the six typical steps for setting up an ASP.NET Core application: create a WebApplicationBuilder, register services and configuration, build a WebApplication, add middleware, map endpoints, and call Run() to start handling requests.
  Why it matters: This sequence is the basic structure for configuring what an ASP.NET Core app can do before it begins serving requests.
• Services middleware and endpoints: Describe how the expanded example adds functionality: services enable HTTP request logging in Development through HttpLoggingMiddleware, middleware logs request details, and the /person endpoint creates a Person record and returns its JSON serialization.
  Why it matters: These are the main building blocks used to configure application behavior and generate responses for requests.

Key terms: WebApplicationBuilder, WebApplication, Build(), middleware, endpoints, Run(), HttpLoggingMiddleware, Development environment, endpoint, /person

3.7.1 Adding and configuring services

This section explains why ASP.NET Core applications register modular framework and custom services with the WebApplicationBuilder before building the app, including HTTP logging and logging configuration.

• Service modularity and dependencies: Explain what a service means in ASP.NET Core and why an application splits features into small, independent services. Describe why directly constructing dependencies with new creates tight coupling, and how dependency injection lets a service declare what it needs instead.
  Why it matters: Registering and injecting services lets application components focus on their own responsibilities instead of constructing and configuring collaborators.
• Service registration before build: Describe how WebApplicationBuilder.Services is used to register framework and custom application services with the IoC container. State that Services is an IServiceCollection containing the services the application needs, and that services must be registered before calling Build().
  Why it matters: The container can provide a dependency only when the application has registered how to supply it before the WebApplication is built.
• HTTP logging service setup: Describe how AddHttpLogging() registers and configures the services required by HTTP logging middleware, and why it is called as an extension method on Services. State that logging filters can control which log messages reach output, such as allowing Information-level-or-higher HTTP logging messages to the console.
  Why it matters: ASP.NET Core commonly hides multi-step feature setup behind extension methods, while logging filters keep output focused on useful messages.

Key terms: service, single-responsibility principle, SRP, dependency injection, Inversion of Control, IoC, WebApplicationBuilder, Services, IServiceCollection, IoC container

3.7.2 Defining how requests are handled with middleware and endpoints

This section explains how a WebApplication uses ordered middleware and mapped endpoints to select, execute, and return responses for HTTP requests.

• WebApplication responsibilities: Describe the three main things done with a WebApplication instance: adding middleware to the pipeline, mapping response-generating endpoints, and starting the application with Run().
  Why it matters: These are the main application-level actions that turn configured services into a running web application.
• Middleware ordering constraints: Explain that middleware consists of sequential request-processing components, typically added with Use* extension methods, and that their Use* call order determines execution order. State that middleware can use objects created by earlier middleware but not objects created later in the pipeline.
  Why it matters: Correct middleware order is necessary because components depend on work performed earlier in the request pipeline.
• Environment-dependent middleware: Describe how WebApplication.Environment exposes an IWebHostEnvironment whose EnvironmentName can be used to vary behavior, such as adding HttpLoggingMiddleware only in Development. State that the environment is set when WebApplication is created and its name is typically supplied externally through an environment variable at startup.
  Why it matters: Environment checks let an app enable development-only behavior without applying it in production.
• Routing and endpoint execution: Trace how automatically added routing middleware at the start of the pipeline uses the request URL to select an endpoint, after which the request continues through middleware to endpoint middleware at the end. Explain that endpoint middleware invokes the selected endpoint to generate the final response, which then passes back through the middleware toward the web server.
  Why it matters: This request flow explains how a URL ultimately reaches the code that creates an HTTP response.
• Minimal API response serialization: Describe the two mapped sample endpoints: GET / executes the Hello World lambda and returns a string, while GET /person executes its lambda and automatically serializes the returned C# record to JSON in the response body.
  Why it matters: This shows that a minimal API endpoint can return either text or an object that ASP.NET Core converts to JSON.

Key terms: WebApplication, middleware pipeline, endpoints, Run(), middleware, Use* extension methods, UseHttpLogging(), WebApplication.Environment, IWebHostEnvironment, EnvironmentName

3.8 Summary

This summary recaps how an ASP.NET Core project declares dependencies and how Program.cs builds, configures, and runs a request-handling application.