daohualiuxiang
/
AspNetCore.Docs
mirror of https://github.com/dotnet/AspNetCore.Docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
AspNetCore.Docs/aspnetcore/fundamentals/startup.md

13 KiB
Raw Blame History

title author description monikerRange ms.author ms.custom ms.date uid
App startup in ASP.NET Core rick-anderson Learn how the Startup class in ASP.NET Core configures services and the app's request pipeline. >= aspnetcore-2.1 riande mvc 11/02/2019 fundamentals/startup

App startup in ASP.NET Core

By Rick Anderson, Tom Dykstra, Luke Latham, and Steve Smith

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:

ConfigureServices and Configure are called by the ASP.NET Core runtime when the app starts:

::: moniker range=">= aspnetcore-3.0"

[!code-csharp]

The preceding sample is for Razor Pages; the MVC version is similar.

::: moniker-end

::: moniker range="< aspnetcore-3.0"

[!code-csharp]

::: moniker-end

The Startup class is specified when the app's host is built. The Startup class is typically specified by calling the WebHostBuilderExtensions.UseStartup<TStartup> method on the host builder:

::: moniker range="< aspnetcore-3.0"

[!code-csharp]

::: moniker-end

::: moniker range=">= aspnetcore-3.0"

[!code-csharp]

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:Microsoft.Extensions.Hosting.IHostBuilder):

[!code-csharp]

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 into the Startup class is to inject:

[!code-csharp]

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.

See The host for more information on the host. For information on handling errors during startup, see 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 are set by convention.

The host may configure some services before Startup methods are called. For more information, see The host.

For features that require substantial setup, there are Add{Service} extension methods on xref:Microsoft.Extensions.DependencyInjection.IServiceCollection. For example, AddDbContext, AddDefaultIdentity, AddEntityFrameworkStores, and AddRazorPages:

::: moniker range=">= aspnetcore-3.0"

[!code-csharp]

::: moniker-end

::: moniker range="< aspnetcore-3.0"

[!code-csharp]

::: 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 or from xref:Microsoft.AspNetCore.Builder.IApplicationBuilder.ApplicationServices*.

::: moniker range="< aspnetcore-3.0"

See SetCompatibilityVersion 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 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 configure the pipeline with support for:

::: moniker range="< aspnetcore-3.0"

::: moniker-end

::: moniker range=">= aspnetcore-3.0"

[!code-csharp]

The preceding sample is for Razor Pages; the MVC version is similar.

::: moniker-end

::: moniker range="< aspnetcore-3.0"

[!code-csharp]

::: 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 to serve 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.

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]

::: moniker-end

::: moniker range="< aspnetcore-3.0"

[!code-csharp]

::: 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 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 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.

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]

The RequestSetOptionsMiddleware is configured in the RequestSetOptionsStartupFilter class:

[!code-csharp]

::: moniker-end

::: moniker range="< aspnetcore-3.0"

[!code-csharp]

The RequestSetOptionsMiddleware is configured in the RequestSetOptionsStartupFilter class:

[!code-csharp]

::: moniker-end

The IStartupFilter is registered in the service container in xref:Microsoft.AspNetCore.Hosting.StartupBase.ConfigureServices*.

::: moniker range=">= aspnetcore-3.0"

[!code-csharp]

::: moniker-end

::: moniker range="< aspnetcore-3.0"

[!code-csharp]

::: 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