ASP.NET Core Startup类 Configure()方法 | ASP.NET Core 中间件详细说明

时间:2024-01-22 10:46:30

ASP.NET Core 程序启动过程如下

 

 微软官方说明:

Startup 类

ASP.NET Core 应用使用 Startup 类,按照约定命名为 Startup  Startup 类:

  • 可选择性地包括 ConfigureServices 方法以配置应用的服务。
  • 必须包括 Configure 方法以创建应用的请求处理管道。

当应用启动时,运行时调用 ConfigureServices 和 Configure 。

Startup 方法体如下

public class Startup
{
    // 使用此方法向容器添加服务
    public void ConfigureServices(IServiceCollection services)
    {
        ...
    }

    // 使用此方法配置HTTP请求管道
    public void Configure(IApplicationBuilder app)
    {
        ...
    }
}

这篇文章只说 Configure


Configure() 方法

Configure 是一个在

  • 命名空间 Microsoft.AspNetCore.Hosting 定义的
  • 抽象类 ↓↓↓
public abstract void Configure (Microsoft.AspNetCore.Builder.IApplicationBuilder app);

IApplicationBuilder

IApplicationBuilder 定义用于配置应用请求管道的类,ASP.NET Core 请求管道包含一系列请求委托,依次调用。

不清楚 Asp.Net Core 请求管道、中间件的读者,对这一部分的内容可以参考

https://www.cnblogs.com/stulzq/p/7760648.html

https://www.cnblogs.com/JNLightGade/p/5737485.html

 

常见中间件顺序

  1. 异常/错误处理
  2. HTTP 严格传输安全协议
  3. HTTPS 重定向
  4. 静态文件服务器
  5. Cookie 策略实施
  6. 身份验证
  7. 会话
  8. MVC

你可以添加其它参数 对 Configure 方法 进行重写,如 IHostingEnvironment  、ILoggerFactory

    public void Configure(IApplicationBuilder app, IHostingEnvironment env, ... ... , ... ...)
        {
        ... ...
        }

中间件

Configure 方法 使用 IApplicationBuilder 来使用中间件

UseMapRun 三种使用方式

  • Use 使用中间件配置请求管道
  • Map 管道分支
  • Run 管道短路

对这一部分的内容可以参考

https://www.cnblogs.com/stulzq/p/7760648.html

https://www.cnblogs.com/JNLightGade/p/5737485.html

Asp.Net Core 内置很多中间件,用户可以直接使用,将在文章后面介绍


使用中间件

默认创建 Asp.Net Core Mvc 程序时,会生成如下模板(Asp.Net Core 2.1)

在文章后面或详细列出所有中间件并加以说明

       public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();    //是否开发环境
            }
            else
            {
                app.UseExceptionHandler("/Home/Error");  //出现错误跳转到 /Error 页面
                app.UseHsts();    //在文章后面的第39行可以看到解释
            }

            app.UseHttpsRedirection();    //把 HTTP 重定向到 HTTPS
            app.UseStaticFiles();       //使用静态文件
            app.UseCookiePolicy();      //与 Cookie 有关

            app.UseMvc(routes =>       //使用 MVP 页面
            {
                routes.MapRoute(
                    name: "default",
                    template: "{controller=Home}/{action=Index}/{id?}");
            });
        }

可以直接使用 app.Use_______ 形式,直接使用内置中间件


 

Configure 方法 的参数 IApplicationBuilder

Configure 方法配置请求管道使用了 IApplicationBuilder,下面将详细列出 IApplicationBuilder 默认的方法、参数、特性等。

Properties(性质)

ApplicationServices

获取或设置提供对应用程序服务容器的访问的 IServiceProvider 提供程序

IServiceProvider : 定义用于检索服务对象的机制,即为其他对象提供自定义支持的对象

可以参考 https://www.cnblogs.com/watermoon2/p/5075002.html

Properties

获取可用于在中间件之间共享数据的 键/值 集合

Properties 是类型为 IDictionary<string,object>

ServerFeatures

获取应用程序服务器提供的HTTP特性集

点击 IFeatureCollection 详细了解


Methods(方法)

Build()

建立此应用程序使用的委托来处理HTTP请求

Build 是一个 AspNetCore.Http.RequestDelegate 类型的委托

New()

创建一个 IApplicationBuilder 共享 Properties 的 IApplicationBuilder

Use(Func<RequestDelegate,RequestDelegate>)

将中间件委托添加到应用程序的请求管道中,对与自定义的中间件,使用此方法。

 


 

Extension Methods(拓展方法)--微软提供的中间件

 使用方法 app._______

以下将列出 所有中间件及其重载方法、说明

注意 IApplicationBuilder 范围很广,包括应用启动、依赖关系注入、路由、环境、配置、选项、日志记录、处理错误等。

UseRequestLocalization(IApplicationBuilder)

添加 RequestLocalizationMiddleware 以基于客户端提供的信息自动设置请求的区域性信息

UseRequestLocalization(IApplicationBuilder, RequestLocalizationOptions)

添加 RequestLocalizationMiddleware 以基于客户端提供的信息自动设置请求的区域性信息

UseRequestLocalization(IApplicationBuilder, Action<RequestLocalizationOptions>)

添加 RequestLocalizationMiddleware 以基于客户端提供的信息自动设置请求的区域性信息

UseRequestLocalization(IApplicationBuilder, String[])

添加 RequestLocalizationMiddleware 以基于客户端提供的信息自动设置请求的区域性信息

UseAuthentication(IApplicationBuilder)

将 AuthenticationMiddleware 添加到指定的 IApplicationBuilder ,它支持身份验证功能

UseBrowserLink(IApplicationBuilder)

此方法被调用以在应用程序中启用浏览器链接。它注册了一个方法工厂,为每个请求创建 BrowserLinkMiddleware。

笔者注:

浏览器链接是Visual Studio中的一项功能,可在开发环境和一个或多个Web浏览器之间创建通信通道。您可以使用浏览器链接一次在多个浏览器中刷新Web应用程序,这对于跨浏览器测试很有用

UseIdentity(IApplicationBuilder)

此方法已过时,将在将来的版本中删除。推荐的替代方案是使用 UseAuthentication (在列表的第5行)

UseConnections(IApplicationBuilder, Action<ConnectionsRouteBuilder>)

向 IApplicationBuilder 请求执行管道添加对 ASP.NET Core 连接处理程序的支持

UseCookieAuthentication(IApplicationBuilder)

已经过时,不再推荐使用。官方建议使用 identity 配置(在列表的第5行)

UseCookieAuthentication(IApplicationBuilder, CookieAuthenticationOptions)

已经过时,不再推荐使用。官方建议使用 identity 配置(在列表的第5行)

UseCookiePolicy(IApplicationBuilder)

将 CookiePolicyMiddleware 处理程序添加到指定的 IApplicationBuilder,它支持 cookie 策略功能

UseCookiePolicy(IApplicationBuilder, CookiePolicyOptions)

将 CookiePolicyMiddleware 处理程序添加到指定的 IApplicationBuilder,它支持 cookie 策略功能

UseCors(IApplicationBuilder)

将CORS中间件添加到Web应用程序管道以允许跨域请求

这是一个静态方法,类型为 Microsoft.AspNetCore.Builder.IApplicationBuilder

UseCors(IApplicationBuilder, Action<CorsPolicyBuilder>)

将CORS中间件添加到Web应用程序管道以允许跨域请求

这是一个静态方法,类型为 Microsoft.AspNetCore.Builder.IApplicationBuilder

UseCors(IApplicationBuilder, String)

将CORS中间件添加到Web应用程序管道以允许跨域请求

这是一个静态方法,类型为 Microsoft.AspNetCore.Builder.IApplicationBuilder

UseDefaultFiles(IApplicationBuilder)

为给定的请求路径启用默认文件映射

UseDefaultFiles(IApplicationBuilder, DefaultFilesOptions)

为给定的请求路径启用默认文件映射

  笔者注:

    参数 DefaultFilesOptions 选择默认文件名的选项,类型为 DefaultFilesOptions

    返回 IApplicationBuilder

UseDefaultFiles(IApplicationBuilder, String)

为给定的请求路径启用默认文件映射

  笔者注:

    参数 String为 相对请求路径

    返回 IApplicationBuilder

UseDeveloperExceptionPage(IApplicationBuilder)

从管道捕获同步和异步异常实例,并生成HTML错误响应

UseDeveloperExceptionPage(IApplicationBuilder, DeveloperExceptionPageOptions)

从管道捕获同步和异步异常实例,并生成HTML错误响应

UseDirectoryBrowser(IApplicationBuilder)

在当前路径上启用目录浏览

笔者注:

对于非程序运行目录或特殊目录,用户通过浏览器打开该目录时,会列出目录内容。

UseDirectoryBrowser(IApplicationBuilder, DirectoryBrowserOptions)

在当前路径上启用目录浏览,同上

UseDirectoryBrowser(IApplicationBuilder, String)

在当前路径上启用目录浏览,同上

UseExceptionHandler(IApplicationBuilder)

向管道添加中间件,该中间件将捕获异常、记录异常并在备用管道中重新执行请求。如果响应已经启动,请求将不被重新执行

UseExceptionHandler(IApplicationBuilder, ExceptionHandlerOptions)

向管道添加中间件,该中间件将捕获异常、记录异常并在备用管道中重新执行请求。如果响应已经启动,请求将不被重新执行

UseExceptionHandler(IApplicationBuilder, Action<IApplicationBuilder>)

向管道添加中间件,该中间件将捕获异常、记录异常并在备用管道中重新执行请求。如果响应已经启动,请求将不被重新执行

UseExceptionHandler(IApplicationBuilder, String)

向管道添加中间件,该中间件将捕获异常、记录异常并在备用管道中重新执行请求。如果响应已经启动,请求将不被重新执行

UseFacebookAuthentication(IApplicationBuilder)

使用FaceBook身份认证

UseFacebookAuthentication(IApplicationBuilder, FacebookOptions)

使用FaceBook身份认证

UseFileServer(IApplicationBuilder)

为当前目录中的当前请求路径启用所有静态文件中间件(目录浏览除外)  --注意四者不同点

UseFileServer(IApplicationBuilder, FileServerOptions)

使给定的选项所有静态文件中间件                    --注意四者不同点

UseFileServer(IApplicationBuilder, Boolean)

是否为当前目录中的当前请求路径启用所有静态文件中间件(目录浏览除外)  --注意四者不同点

UseFileServer(IApplicationBuilder, String)

为来自同名目录的给定请求路径启用所有静态文件中间件(目录浏览除外    --注意四者不同点

UseForwardedHeaders(IApplicationBuilder)

转发代理到当前请求报头

UseForwardedHeaders(IApplicationBuilder, ForwardedHeadersOptions)

转发代理到当前请求报头

UseGoogleAuthentication(IApplicationBuilder)

使用 Google 进行身份认证

UseGoogleAuthentication(IApplicationBuilder, GoogleOptions)

使用 Google 进行身份认证

UseHostFiltering(IApplicationBuilder)

增加了过滤请求允许主机头的中间件,无效的请求将被拒绝并返回 400 状态代码

UseHsts(IApplicationBuilder)

添加了使用HSTS的中间件,它添加了严格的传输安全标头

UseHttpMethodOverride(IApplicationBuilder)

允许传入的POST请求以头文件中指定的类型重写方法类型

UseHttpMethodOverride(IApplicationBuilder, HttpMethodOverrideOptions)

允许传入POST请求以表单指定的类型重写方法类型

UseHttpsRedirection(IApplicationBuilder)

添加用于将HTTP请求重定向到HTTPS的中间件。

UseJwtBearerAuthentication(IApplicationBuilder)

UseJwtBearerAuthentication 是过时的认证方案,官方已经不推荐使用

UseJwtBearerAuthentication(IApplicationBuilder, JwtBearerOptions)

UseJwtBearerAuthentication 是过时的认证方案,官方已经不推荐使用

Map(IApplicationBuilder, PathString, Action<IApplicationBuilder>)

根据给定的请求路径的匹配来分支请求管道。如果请求路径从给定路径开始,则执行分支

MapWhen(IApplicationBuilder, Func<HttpContext,Boolean>, Action<IApplicationBuilder>)

根据给定的预测结果对请求流水线进行分支

UseMicrosoftAccountAuthentication(IApplicationBuilder)

UseMicrosoftAccountAuthentication 过时,官方不再推荐使用

UseMicrosoftAccountAuthentication(IApplicationBuilder, MicrosoftAccountOptions)

UseMicrosoftAccountAuthentication 过时,官方不再推荐使用

UseMvc(IApplicationBuilder)

将 MVC 添加到 请求执行管道中

UseMvc(IApplicationBuilder, Action<IRouteBuilder>)

将 MVC 添加到请求执行管道中,并配置路由,使用示例

app.UseMvc(routes =>
            {
                routes.MapRoute(
                    name: "default",
                    template: "{controller=Home}/{action=Index}/{id?}");
            });
UseMvcWithDefaultRoute(IApplicationBuilder)

使用默认的路由模板

笔者注:

在你创建Mvc应用时,就已经默认生成

默认的路由模板格式 {controller=Home}/{action=Index}/{id?} 

使用此中间件的效果等同上一个表格的示例

UseOAuthAuthentication(IApplicationBuilder)

UseOAuthAuthentication 过时,官方不推荐使用

UseOAuthAuthentication(IApplicationBuilder, OAuthOptions)

UseOAuthAuthentication 过时,官方不推荐使用

UseOpenIdConnectAuthentication(IApplicationBuilder)

UseOpenIdConnectAuthentication  过时,官方不推荐使用

UseOpenIdConnectAuthentication(IApplicationBuilder, OpenIdConnectOptions)

UseOpenIdConnectAuthentication  过时,官方不推荐使用

UseResponseCompression(IApplicationBuilder)

添加用于动态压缩HTTP响应的中间件

UseRewriter(IApplicationBuilder)

检查给定URL是否匹配规则和条件(正则表达式),并修改匹配的HTTP语境。

UseRewriter(IApplicationBuilder, RewriteOptions)

检查给定URL是否匹配规则和条件(正则表达式),并修改匹配的HTTP语境

UseRouter(IApplicationBuilder, IRouter)

创建路由规则并添加到路由表中

UseRouter(IApplicationBuilder, Action<IRouteBuilder>)

创建路由规则并添加到路由表中

Run(IApplicationBuilder, RequestDelegate)

使管道短路

笔者注:

当管道碰到Run使,无论后面是否还有其它中间件,都会忽略

UseSession(IApplicationBuilder)

添加 Session 以自动启用应用程序的会话状态

UseSession(IApplicationBuilder, SessionOptions)

添加 Session 以自动启用应用程序的会话状态

UseSignalR(IApplicationBuilder, Action<HubRouteBuilder>)

添加 SignalR 到请求管道中

UseSpa(IApplicationBuilder, Action<ISpaBuilder>)

通过返回单页应用程序(SPA)的默认页面,处理从中间件链中此点开始的所有请求。这个中间件应该放在链的末尾,以便其他提供静态文件、MVC操作等的中间件优先

UseStaticFiles(IApplicationBuilder)

为当前请求路径启用静态文件服务

UseStaticFiles(IApplicationBuilder, StaticFileOptions)

为当前请求路径启用静态文件服务

UseStaticFiles(IApplicationBuilder, String)

为当前请求路径启用静态文件服务

UseStatusCodePages(IApplicationBuilder)

添加具有默认响应处理程序的中间件,该处理程序检查400和599之间没有主体时的状态代码,以进行响应

UseStatusCodePages(IApplicationBuilder, StatusCodePagesOptions)

同上

UseStatusCodePages(IApplicationBuilder, Action<IApplicationBuilder>)

同上

UseStatusCodePages(IApplicationBuilder, Func<StatusCodeContext,Task>)

同上

UseStatusCodePages(IApplicationBuilder, String, String)

同上

UseStatusCodePagesWithRedirects(IApplicationBuilder, String)

同上

UseStatusCodePagesWithReExecute(IApplicationBuilder, String, String)

同上

UseTwitterAuthentication(IApplicationBuilder)

使用 Twitter 进行身份认证,官方不再推荐这种过时用法

UseTwitterAuthentication(IApplicationBuilder, TwitterOptions)

使用 Twitter 进行身份认证,官方不再推荐这种过时用法

Use(IApplicationBuilder, Func<HttpContext,Func<Task>,Task>)

将一个中间件委托添加到应用程序的请求管道中

UseMiddleware(IApplicationBuilder, Type, Object[])

将一个中间件添加到应用程序的请求管道中,注意与上面的区别

UseMiddleware<TMiddleware>(IApplicationBuilder, Object[])

将一个中间件添加到应用程序的请求管道中,注意与上面的区别

UsePathBase(IApplicationBuilder, PathString)

加中间件,从中间件从请求路径中提取指定的路径库并将其附加到请求路径库

UseWhen(IApplicationBuilder, Func<HttpContext,Boolean>, Action<IApplicationBuilder>)

有条件地在请求管道中创建一个分支,并将其重新连接到主管道

UseWebpackDevMiddleware(IApplicationBuilder, WebpackDevMiddlewareOptions)

英文原文如下

Enables Webpack dev middleware support. This hosts an instance of the Webpack compiler in memory in your application so that you can always serve up-to-date Webpack-built resources without having to run the compiler manually. Since the Webpack compiler instance is retained in memory, incremental compilation is vastly faster that re-running the compiler from scratch.

Incoming requests that match Webpack-built files will be handled by returning the Webpack compiler output directly, regardless of files on disk. If compilation is in progress when the request arrives, the response will pause until updated compiler output is ready.

UseWebSockets(IApplicationBuilder)

WebSockets服务

UseWebSockets(IApplicationBuilder, WebSocketOptions)

WebSockets服务

UseWelcomePage(IApplicationBuilder)

添加一个欢迎页面到请求管道中

UseWelcomePage(IApplicationBuilder, WelcomePageOptions)

添加一个欢迎页面到请求管道中,可以自己配置欢迎页面

UseWelcomePage(IApplicationBuilder, PathString)

添加一个欢迎页面到请求管道中,自定义欢迎页面的路径

UseWelcomePage(IApplicationBuilder, String)

添加一个欢迎页面到请求管道中

UseSpaStaticFiles(IApplicationBuilder)

将应用程序配置为为单页应用程序(SPA)提供静态文件

UseSpaStaticFiles(IApplicationBuilder, StaticFileOptions)

将应用程序配置为为单页应用程序(SPA)提供静态