257 lines
13 KiB
Markdown
257 lines
13 KiB
Markdown
---
|
|
title: App startup in ASP.NET Core
|
|
author: rick-anderson
|
|
description: Learn how the Startup class in ASP.NET Core configures services and the app's request pipeline.
|
|
monikerRange: '>= aspnetcore-2.1'
|
|
ms.author: riande
|
|
ms.custom: mvc
|
|
ms.date: 11/02/2019
|
|
uid: fundamentals/startup
|
|
---
|
|
# App startup in ASP.NET Core
|
|
|
|
By [Rick Anderson](https://twitter.com/RickAndMSFT), [Tom Dykstra](https://github.com/tdykstra), [Luke Latham](https://github.com/guardrex), and [Steve Smith](https://ardalis.com)
|
|
|
|
The `Startup` class configures services and the app's request pipeline.
|
|
|
|
## The Startup class
|
|
|
|
ASP.NET Core apps use a `Startup` class, which is named `Startup` by convention. The `Startup` class:
|
|
|
|
* Optionally includes a <xref:Microsoft.AspNetCore.Hosting.StartupBase.ConfigureServices*> method to configure the app's *services*. A service is a reusable component that provides app functionality. Services are *registered* in `ConfigureServices` and consumed across the app via [dependency injection (DI)](xref:fundamentals/dependency-injection) or <xref:Microsoft.AspNetCore.Builder.IApplicationBuilder.ApplicationServices*>.
|
|
* Includes a <xref:Microsoft.AspNetCore.Hosting.StartupBase.Configure*> method to create the app's request processing pipeline.
|
|
|
|
`ConfigureServices` and `Configure` are called by the ASP.NET Core runtime when the app starts:
|
|
|
|
::: moniker range=">= aspnetcore-3.0"
|
|
|
|
[!code-csharp[](startup/3.0_samples/StartupFilterSample/Startup.cs?name=snippet)]
|
|
|
|
The preceding sample is for [Razor Pages](xref:razor-pages/index); the MVC version is similar.
|
|
|
|
::: moniker-end
|
|
|
|
::: moniker range="< aspnetcore-3.0"
|
|
|
|
[!code-csharp[](startup/sample_snapshot/Startup1.cs)]
|
|
|
|
::: moniker-end
|
|
|
|
The `Startup` class is specified when the app's [host](xref:fundamentals/index#host) is built. The `Startup` class is typically specified by calling the [`WebHostBuilderExtensions.UseStartup<TStartup>`](xref:Microsoft.AspNetCore.Hosting.WebHostBuilderExtensions.UseStartup*) method on the host builder:
|
|
|
|
::: moniker range="< aspnetcore-3.0"
|
|
|
|
[!code-csharp[](startup/sample_snapshot/Program3.cs?name=snippet_Program&highlight=12)]
|
|
|
|
::: moniker-end
|
|
|
|
::: moniker range=">= aspnetcore-3.0"
|
|
|
|
[!code-csharp[](startup/3.0_samples/Program3.cs?name=snippet_Program&highlight=12)]
|
|
|
|
The host provides services that are available to the `Startup` class constructor. The app adds additional services via `ConfigureServices`. Both the host and app services are available in `Configure` and throughout the app.
|
|
|
|
Only the following service types can be injected into the `Startup` constructor when using the [Generic Host](xref:fundamentals/host/generic-host) (<xref:Microsoft.Extensions.Hosting.IHostBuilder>):
|
|
|
|
* <xref:Microsoft.AspNetCore.Hosting.IWebHostEnvironment>
|
|
* <xref:Microsoft.Extensions.Hosting.IHostEnvironment>
|
|
* <xref:Microsoft.Extensions.Configuration.IConfiguration>
|
|
|
|
[!code-csharp[](startup/3.0_samples/StartupFilterSample/StartUp2.cs?name=snippet)]
|
|
|
|
Most services are not available until the `Configure` method is called.
|
|
|
|
::: moniker-end
|
|
|
|
::: moniker range="< aspnetcore-3.0"
|
|
|
|
The host provides services that are available to the `Startup` class constructor. The app adds additional services via `ConfigureServices`. Both the host and app services are then available in `Configure` and throughout the app.
|
|
|
|
A common use of [dependency injection](xref:fundamentals/dependency-injection) into the `Startup` class is to inject:
|
|
|
|
* <xref:Microsoft.AspNetCore.Hosting.IHostingEnvironment> to configure services by environment.
|
|
* <xref:Microsoft.Extensions.Configuration.IConfiguration> to read configuration.
|
|
* <xref:Microsoft.Extensions.Logging.ILoggerFactory> to create a logger in `Startup.ConfigureServices`.
|
|
|
|
[!code-csharp[](startup/sample_snapshot/Startup2.cs?highlight=7-8)]
|
|
|
|
Most services are not available until the `Configure` method is called.
|
|
|
|
::: moniker-end
|
|
|
|
### Multiple Startup
|
|
|
|
When the app defines separate `Startup` classes for different environments (for example, `StartupDevelopment`), the appropriate `Startup` class is selected at runtime. The class whose name suffix matches the current environment is prioritized. If the app is run in the Development environment and includes both a `Startup` class and a `StartupDevelopment` class, the `StartupDevelopment` class is used. For more information, see [Use multiple environments](xref:fundamentals/environments#environment-based-startup-class-and-methods).
|
|
|
|
See [The host](xref:fundamentals/index#host) for more information on the host. For information on handling errors during startup, see [Startup exception handling](xref:fundamentals/error-handling#startup-exception-handling).
|
|
|
|
## The ConfigureServices method
|
|
|
|
The <xref:Microsoft.AspNetCore.Hosting.StartupBase.ConfigureServices*> method is:
|
|
|
|
* Optional.
|
|
* Called by the host before the `Configure` method to configure the app's services.
|
|
* Where [configuration options](xref:fundamentals/configuration/index) are set by convention.
|
|
|
|
The host may configure some services before `Startup` methods are called. For more information, see [The host](xref:fundamentals/index#host).
|
|
|
|
For features that require substantial setup, there are `Add{Service}` extension methods on <xref:Microsoft.Extensions.DependencyInjection.IServiceCollection>. For example, **Add**DbContext, **Add**DefaultIdentity, **Add**EntityFrameworkStores, and **Add**RazorPages:
|
|
|
|
::: moniker range=">= aspnetcore-3.0"
|
|
|
|
[!code-csharp[](startup/3.0_samples/StartupFilterSample/StartupIdentity.cs?name=snippet)]
|
|
|
|
::: moniker-end
|
|
|
|
::: moniker range="< aspnetcore-3.0"
|
|
|
|
[!code-csharp[](startup/sample_snapshot/Startup3.cs)]
|
|
|
|
::: moniker-end
|
|
|
|
Adding services to the service container makes them available within the app and in the `Configure` method. The services are resolved via [dependency injection](xref:fundamentals/dependency-injection) or from <xref:Microsoft.AspNetCore.Builder.IApplicationBuilder.ApplicationServices*>.
|
|
|
|
::: moniker range="< aspnetcore-3.0"
|
|
|
|
See [SetCompatibilityVersion](xref:mvc/compatibility-version) for more information on `SetCompatibilityVersion`.
|
|
|
|
::: moniker-end
|
|
|
|
## The Configure method
|
|
|
|
The <xref:Microsoft.AspNetCore.Hosting.StartupBase.Configure*> method is used to specify how the app responds to HTTP requests. The request pipeline is configured by adding [middleware](xref:fundamentals/middleware/index) components to an <xref:Microsoft.AspNetCore.Builder.IApplicationBuilder> instance. `IApplicationBuilder` is available to the `Configure` method, but it isn't registered in the service container. Hosting creates an `IApplicationBuilder` and passes it directly to `Configure`.
|
|
|
|
The [ASP.NET Core templates](/dotnet/core/tools/dotnet-new) configure the pipeline with support for:
|
|
|
|
* [Developer Exception Page](xref:fundamentals/error-handling#developer-exception-page)
|
|
* [Exception handler](xref:fundamentals/error-handling#exception-handler-page)
|
|
* [HTTP Strict Transport Security (HSTS)](xref:security/enforcing-ssl#http-strict-transport-security-protocol-hsts)
|
|
* [HTTPS redirection](xref:security/enforcing-ssl)
|
|
* [Static files](xref:fundamentals/static-files)
|
|
* ASP.NET Core [MVC](xref:mvc/overview) and [Razor Pages](xref:razor-pages/index)
|
|
|
|
::: moniker range="< aspnetcore-3.0"
|
|
|
|
* [General Data Protection Regulation (GDPR)](xref:security/gdpr)
|
|
|
|
::: moniker-end
|
|
|
|
::: moniker range=">= aspnetcore-3.0"
|
|
|
|
[!code-csharp[](startup/3.0_samples/StartupFilterSample/Startup.cs?name=snippet)]
|
|
|
|
The preceding sample is for [Razor Pages](xref:razor-pages/index); the MVC version is similar.
|
|
|
|
::: moniker-end
|
|
|
|
::: moniker range="< aspnetcore-3.0"
|
|
|
|
[!code-csharp[](startup/sample_snapshot/Startup4.cs)]
|
|
|
|
::: moniker-end
|
|
|
|
Each `Use` extension method adds one or more middleware components to the request pipeline. For instance, <xref:Microsoft.AspNetCore.Builder.StaticFileExtensions.UseStaticFiles*> configures [middleware](xref:fundamentals/middleware/index) to serve [static files](xref:fundamentals/static-files).
|
|
|
|
Each middleware component in the request pipeline is responsible for invoking the next component in the pipeline or short-circuiting the chain, if appropriate.
|
|
|
|
::: moniker range=">= aspnetcore-3.0"
|
|
|
|
Additional services, such as `IWebHostEnvironment`, `ILoggerFactory`, or anything defined in `ConfigureServices`, can be specified in the `Configure` method signature. These services are injected if they're available.
|
|
|
|
::: moniker-end
|
|
|
|
::: moniker range="< aspnetcore-3.0"
|
|
|
|
Additional services, such as `IHostingEnvironment` and `ILoggerFactory`, or anything defined in `ConfigureServices`, can be specified in the `Configure` method signature. These services are injected if they're available.
|
|
|
|
::: moniker-end
|
|
|
|
For more information on how to use `IApplicationBuilder` and the order of middleware processing, see <xref:fundamentals/middleware/index>.
|
|
|
|
<a name="convenience-methods"></a>
|
|
|
|
## Configure services without Startup
|
|
|
|
To configure services and the request processing pipeline without using a `Startup` class, call `ConfigureServices` and `Configure` convenience methods on the host builder. Multiple calls to `ConfigureServices` append to one another. If multiple `Configure` method calls exist, the last `Configure` call is used.
|
|
|
|
::: moniker range=">= aspnetcore-3.0"
|
|
|
|
[!code-csharp[](startup/3.0_samples/StartupFilterSample/Program1.cs?name=snippet)]
|
|
|
|
::: moniker-end
|
|
|
|
::: moniker range="< aspnetcore-3.0"
|
|
|
|
[!code-csharp[](startup/sample_snapshot/Program1.cs?highlight=16,20)]
|
|
|
|
::: moniker-end
|
|
|
|
## Extend Startup with startup filters
|
|
|
|
Use <xref:Microsoft.AspNetCore.Hosting.IStartupFilter>:
|
|
|
|
* To configure middleware at the beginning or end of an app's [Configure](#the-configure-method) middleware pipeline without an explicit call to `Use{Middleware}`. `IStartupFilter` is used by ASP.NET Core to add defaults to the beginning of the pipeline without having to make the app author explicitly register the default middleware. `IStartupFilter` allows a different component call `Use{Middleware}` on behalf of the app author.
|
|
* To create a pipeline of `Configure` methods. [IStartupFilter.Configure](xref:Microsoft.AspNetCore.Hosting.IStartupFilter.Configure*) can set a middleware to run before or after middleware added by libraries.
|
|
|
|
`IStartupFilter` implements <xref:Microsoft.AspNetCore.Hosting.StartupBase.Configure*>, which receives and returns an `Action<IApplicationBuilder>`. An <xref:Microsoft.AspNetCore.Builder.IApplicationBuilder> defines a class to configure an app's request pipeline. For more information, see [Create a middleware pipeline with IApplicationBuilder](xref:fundamentals/middleware/index#create-a-middleware-pipeline-with-iapplicationbuilder).
|
|
|
|
Each `IStartupFilter` can add one or more middlewares in the request pipeline. The filters are invoked in the order they were added to the service container. Filters may add middleware before or after passing control to the next filter, thus they append to the beginning or end of the app pipeline.
|
|
|
|
The following example demonstrates how to register a middleware with `IStartupFilter`. The `RequestSetOptionsMiddleware` middleware sets an options value from a query string parameter:
|
|
|
|
::: moniker range=">= aspnetcore-3.0"
|
|
|
|
[!code-csharp[](startup/3.0_samples/StartupFilterSample/RequestSetOptionsMiddleware.cs?name=snippet1)]
|
|
|
|
The `RequestSetOptionsMiddleware` is configured in the `RequestSetOptionsStartupFilter` class:
|
|
|
|
[!code-csharp[](startup/3.0_samples/StartupFilterSample/RequestSetOptionsStartupFilter.cs?name=snippet1&highlight=7)]
|
|
|
|
::: moniker-end
|
|
|
|
::: moniker range="< aspnetcore-3.0"
|
|
|
|
[!code-csharp[](startup/sample_snapshot/RequestSetOptionsMiddleware.cs?name=snippet1&highlight=21)]
|
|
|
|
The `RequestSetOptionsMiddleware` is configured in the `RequestSetOptionsStartupFilter` class:
|
|
|
|
[!code-csharp[](startup/sample_snapshot/RequestSetOptionsStartupFilter.cs?name=snippet1&highlight=7)]
|
|
|
|
::: moniker-end
|
|
|
|
The `IStartupFilter` is registered in the service container in <xref:Microsoft.AspNetCore.Hosting.StartupBase.ConfigureServices*>.
|
|
|
|
::: moniker range=">= aspnetcore-3.0"
|
|
|
|
[!code-csharp[](startup/3.0_samples/StartupFilterSample/Program.cs?name=snippet&highlight=19-20)]
|
|
|
|
::: moniker-end
|
|
|
|
::: moniker range="< aspnetcore-3.0"
|
|
|
|
[!code-csharp[](startup/sample_snapshot/Program2.cs?name=snippet1&highlight=4-5)]
|
|
|
|
::: moniker-end
|
|
|
|
When a query string parameter for `option` is provided, the middleware processes the value assignment before the ASP.NET Core middleware renders the response.
|
|
|
|
Middleware execution order is set by the order of `IStartupFilter` registrations:
|
|
|
|
* Multiple `IStartupFilter` implementations may interact with the same objects. If ordering is important, order their `IStartupFilter` service registrations to match the order that their middlewares should run.
|
|
* Libraries may add middleware with one or more `IStartupFilter` implementations that run before or after other app middleware registered with `IStartupFilter`. To invoke an `IStartupFilter` middleware before a middleware added by a library's `IStartupFilter`:
|
|
|
|
* Position the service registration before the library is added to the service container.
|
|
* To invoke afterward, position the service registration after the library is added.
|
|
|
|
## Add configuration at startup from an external assembly
|
|
|
|
An <xref:Microsoft.AspNetCore.Hosting.IHostingStartup> implementation allows adding enhancements to an app at startup from an external assembly outside of the app's `Startup` class. For more information, see <xref:fundamentals/configuration/platform-specific-configuration>.
|
|
|
|
## Additional resources
|
|
|
|
* [The host](xref:fundamentals/index#host)
|
|
* <xref:fundamentals/environments>
|
|
* <xref:fundamentals/middleware/index>
|
|
* <xref:fundamentals/logging/index>
|
|
* <xref:fundamentals/configuration/index>
|