diff --git a/aspnetcore/fundamentals/index.md b/aspnetcore/fundamentals/index.md index 515d419359..164a5df166 100644 --- a/aspnetcore/fundamentals/index.md +++ b/aspnetcore/fundamentals/index.md @@ -12,7 +12,7 @@ uid: fundamentals/index [!INCLUDE[](~/includes/not-latest-version.md)] -:::moniker range=">= aspnetcore-8.0" +:::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. @@ -232,3 +232,4 @@ For more information, see . :::moniker-end [!INCLUDE[](~/fundamentals/index/includes/index3-7.md)] +[!INCLUDE[](~/fundamentals/index/includes/index8.md)] diff --git a/aspnetcore/fundamentals/index/includes/index8.md b/aspnetcore/fundamentals/index/includes/index8.md new file mode 100644 index 0000000000..30a71cf072 --- /dev/null +++ b/aspnetcore/fundamentals/index/includes/index8.md @@ -0,0 +1,218 @@ +:::moniker range="= aspnetcore-8.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