--- title: ASP.NET Core fundamentals overview author: tdykstra description: Learn the fundamental concepts for building ASP.NET Core apps, including dependency injection (DI), configuration, middleware, and more. monikerRange: '>= aspnetcore-3.1' ms.author: tdykstra ms.custom: mvc ms.date: 08/01/2024 uid: fundamentals/index --- # ASP.NET Core fundamentals overview [!INCLUDE[](~/includes/not-latest-version.md)] :::moniker range=">= aspnetcore-9.0" This article provides an overview of the fundamentals for building ASP.NET Core apps, including dependency injection (DI), configuration, middleware, and more. For Blazor fundamentals guidance, which adds to or supersedes the guidance in this node, see . ## Program.cs ASP.NET Core apps created with the web templates contain the application startup code in the `Program.cs` file. The `Program.cs` file is where: * Services required by the app are configured. * The app's request handling pipeline is defined as a series of [middleware components](xref:fundamentals/middleware/index). The following app startup code supports: * [Razor Pages](xref:tutorials/razor-pages/razor-pages-start) * [MVC controllers with views](xref:tutorials/first-mvc-app/start-mvc) * [Web API with controllers](xref:tutorials/first-web-api) * [Minimal web APIs](xref:tutorials/min-web-api) [!code-csharp[](~/fundamentals/startup/6.0_samples/WebAll/Program.cs?name=snippet)] ## Dependency injection (services) ASP.NET Core includes [dependency injection (DI)](xref:fundamentals/dependency-injection) that makes configured services available throughout an app. Services are added to the DI container with [WebApplicationBuilder.Services](xref:Microsoft.AspNetCore.Builder.WebApplicationBuilder.Services), `builder.Services` in the preceding code. When the is instantiated, many [framework-provided services](xref:fundamentals/dependency-injection#framework-provided-services) are added. `builder` is a `WebApplicationBuilder` in the following code: [!code-csharp[](~/fundamentals/startup/6.0_samples/WebAll/Program.cs?name=snippet2&highlight=1)] In the preceding highlighted code, `builder` has configuration, logging, and [many other services](xref:fundamentals/dependency-injection#framework-provided-services) added to the DI container. The following code adds Razor Pages, MVC controllers with views, and a custom to the DI container: [!code-csharp[](~/fundamentals/index/samples/6.0/RazorPagesMovie/Program.cs?name=snippet2&highlight=6-10)] Services are typically resolved from DI using constructor injection. The DI framework provides an instance of this service at runtime. The following code uses constructor injection to resolve the database context and logger from DI: [!code-csharp[](~/fundamentals/index/samples/6.0/RazorPagesMovie/Pages/Movies/Index.cshtml.cs?name=snippet&highlight=3-10, 16-17)] ## Middleware The request handling pipeline is composed as a series of middleware components. Each component performs operations on an [`HttpContext`](xref:fundamentals/httpcontext) and either invokes the next middleware in the pipeline or terminates the request. By convention, a middleware component is added to the pipeline by invoking a `Use{Feature}` extension method. Middleware added to the app is highlighted in the following code: [!code-csharp[](~/fundamentals/startup/6.0_samples/WebAll/Program.cs?name=snippet&highlight=12-19)] For more information, see . ## Host On startup, an ASP.NET Core app builds a *host*. The host encapsulates all of the app's resources, such as: * An HTTP server implementation * Middleware components * Logging * Dependency injection (DI) services * Configuration There are three different hosts capable of running an ASP.NET Core app: * [ASP.NET Core WebApplication](xref:fundamentals/minimal-apis/webapplication), also known as the [Minimal Host](xref:migration/50-to-60#new-hosting-model) * [.NET Generic Host](xref:fundamentals/host/generic-host) combined with ASP.NET Core's * [ASP.NET Core WebHost](xref:fundamentals/host/web-host) The ASP.NET Core and types are recommended and used in all the ASP.NET Core templates. `WebApplication` behaves similarly to the .NET Generic Host and exposes many of the same interfaces but requires less callbacks to configure. The ASP.NET Core is available only for backward compatibility. The following example instantiates a `WebApplication`: [!code-csharp[](~/fundamentals/startup/6.0_samples/WebAll/Program.cs?name=snippet2&highlight=7)] The [WebApplicationBuilder.Build](xref:Microsoft.AspNetCore.Builder.WebApplicationBuilder.Build%2A) method configures a host with a set of default options, such as: * Use [Kestrel](#servers) as the web server and enable IIS integration. * Load [configuration](xref:fundamentals/configuration/index) from `appsettings.json`, environment variables, command line arguments, and other configuration sources. * Send logging output to the console and debug providers. ### Non-web scenarios The Generic Host allows other types of apps to use cross-cutting framework extensions, such as logging, dependency injection (DI), configuration, and app lifetime management. For more information, see and . ## Servers An ASP.NET Core app uses an HTTP server implementation to listen for HTTP requests. The server surfaces requests to the app as a set of [request features](xref:fundamentals/request-features) composed into an `HttpContext`. # [Windows](#tab/windows) ASP.NET Core provides the following server implementations: * *Kestrel* is a cross-platform web server. Kestrel is often run in a reverse proxy configuration using [IIS](https://www.iis.net/). In ASP.NET Core 2.0 or later, Kestrel can be run as a public-facing edge server exposed directly to the Internet. * *IIS HTTP Server* is a server for Windows that uses IIS. With this server, the ASP.NET Core app and IIS run in the same process. * *HTTP.sys* is a server for Windows that isn't used with IIS. # [macOS](#tab/macos) ASP.NET Core provides the *Kestrel* cross-platform server implementation. In ASP.NET Core 2.0 or later, Kestrel can run as a public-facing edge server exposed directly to the Internet. Kestrel is often run in a reverse proxy configuration with [Nginx](https://nginx.org) or [Apache](https://httpd.apache.org/). # [Linux](#tab/linux) ASP.NET Core provides the *Kestrel* cross-platform server implementation. In ASP.NET Core 2.0 or later, Kestrel can run as a public-facing edge server exposed directly to the Internet. Kestrel is often run in a reverse proxy configuration with [Nginx](https://nginx.org) or [Apache](https://httpd.apache.org/). --- For more information, see . ## Configuration ASP.NET Core provides a [configuration](xref:fundamentals/configuration/index) framework that gets settings as name-value pairs from an ordered set of configuration providers. Built-in configuration providers are available for a variety of sources, such as `.json` files, `.xml` files, environment variables, and command-line arguments. Write custom configuration providers to support other sources. By [default](xref:fundamentals/configuration/index#default), ASP.NET Core apps are configured to read from `appsettings.json`, environment variables, the command line, and more. When the app's configuration is loaded, values from environment variables override values from `appsettings.json`. For managing confidential configuration data such as passwords, .NET Core provides the [Secret Manager](xref:security/app-secrets#secret-manager). For production secrets, we recommend [Azure Key Vault](xref:security/key-vault-configuration). For more information, see . ## Environments Execution environments, such as `Development`, `Staging`, and `Production`, are available in ASP.NET Core. Specify the environment an app is running in by setting the `ASPNETCORE_ENVIRONMENT` environment variable. ASP.NET Core reads that environment variable at app startup and stores the value in an `IWebHostEnvironment` implementation. This implementation is available anywhere in an app via dependency injection (DI). The following example configures the exception handler and [HTTP Strict Transport Security Protocol (HSTS)](xref:security/enforcing-ssl#http-strict-transport-security-protocol-hsts) middleware when ***not*** running in the `Development` environment: [!code-csharp[](~/fundamentals/startup/6.0_samples/WebAll/Program.cs?name=snippet&highlight=10-14)] For more information, see . ## Logging ASP.NET Core supports a logging API that works with a variety of built-in and third-party logging providers. Available providers include: * Console * Debug * Event Tracing on Windows * Windows Event Log * TraceSource * Azure App Service * Azure Application Insights To create logs, resolve an service from dependency injection (DI) and call logging methods such as . For example: [!code-csharp[](~/fundamentals/index/samples/6.0/RazorPagesMovie/Pages/Movies/Index.cshtml.cs?name=snippet&highlight=3-10, 16-17)] For more information, see . ## Routing A *route* is a URL pattern that is mapped to a handler. The handler is typically a Razor page, an action method in an MVC controller, or a middleware. ASP.NET Core routing gives you control over the URLs used by your app. The following code, generated by the ASP.NET Core web application template, calls : [!code-csharp[](~/fundamentals/startup/6.0_samples/WebAll/Program.cs?name=snippet4&highlight=17)] For more information, see . ## Error handling ASP.NET Core has built-in features for handling errors, such as: * A developer exception page * Custom error pages * Static status code pages * Startup exception handling For more information, see . ## Make HTTP requests An implementation of `IHttpClientFactory` is available for creating `HttpClient` instances. The factory: * Provides a central location for naming and configuring logical `HttpClient` instances. For example, register and configure a *github* client for accessing GitHub. Register and configure a default client for other purposes. * Supports registration and chaining of multiple delegating handlers to build an outgoing request middleware pipeline. This pattern is similar to ASP.NET Core's inbound middleware pipeline. The pattern provides a mechanism to manage cross-cutting concerns for HTTP requests, including caching, error handling, serialization, and logging. * Integrates with *Polly*, a popular third-party library for transient fault handling. * Manages the pooling and lifetime of underlying `HttpClientHandler` instances to avoid common DNS problems that occur when managing `HttpClient` lifetimes manually. * Adds a configurable logging experience via for all requests sent through clients created by the factory. For more information, see . ## Content root The content root is the base path for: * The executable hosting the app (*.exe*). * Compiled assemblies that make up the app (*.dll*). * Content files used by the app, such as: * Razor files (`.cshtml`, `.razor`) * Configuration files (`.json`, `.xml`) * Data files (`.db`) * The [Web root](#web-root), typically the *wwwroot* folder. During development, the content root defaults to the project's root directory. This directory is also the base path for both the app's content files and the [Web root](#web-root). Specify a different content root by setting its path when [building the host](#host). For more information, see [Content root](xref:fundamentals/host/generic-host#contentroot). ## Web root The web root is the base path for public, static resource files, such as: * Stylesheets (`.css`) * JavaScript (`.js`) * Images (`.png`, `.jpg`) By default, static files are served only from the web root directory and its sub-directories. The web root path defaults to *{content root}/wwwroot*. Specify a different web root by setting its path when [building the host](#host). For more information, see [Web root](xref:fundamentals/host/generic-host#webroot). Prevent publishing files in *wwwroot* with the [\ project item](/visualstudio/msbuild/common-msbuild-project-items#content) in the project file. The following example prevents publishing content in *wwwroot/local* and its sub-directories: ```xml ``` In Razor `.cshtml` files, `~/` points to the web root. A path beginning with `~/` is referred to as a *virtual path*. For more information, see . ## Additional resources * [WebApplicationBuilder source code](https://github.com/dotnet/aspnetcore/blob/v6.0.1/src/DefaultBuilder/src/WebApplicationBuilder.cs) :::moniker-end [!INCLUDE[](~/fundamentals/index/includes/index3-7.md)] [!INCLUDE[](~/fundamentals/index/includes/index8.md)]