使用 IIS 和 ASP.NET Core 进行进程外托管Out-of-process hosting with IIS and ASP.NET Core

由于运行 ASP.NET Core 的进程与 IIS 工作进程分开,因此 ASP.NET Core 模块会负责进程管理。Because ASP.NET Core apps run in a process separate from the IIS worker process, the ASP.NET Core Module handles process management. 该模块在第一个请求到达时启动 ASP.NET Core 应用的进程,并在应用关闭或崩溃时重新启动该应用。The module starts the process for the ASP.NET Core app when the first request arrives and restarts the app if it shuts down or crashes. 这基本上与在 Windows 进程激活服务 (WAS) 托管的进程内运行的应用中出现的行为相同。This is essentially the same behavior as seen with apps that run in-process that are managed by the Windows Process Activation Service (WAS).

下图说明了 IIS、ASP.NET Core 模块和进程外托管的应用之间的关系:The following diagram illustrates the relationship between IIS, the ASP.NET Core Module, and an app hosted out-of-process:

进程外托管方案中的 ASP.NET Core 模块

  1. 请求从 Web 到达内核模式 HTTP.sys 驱动程序。Requests arrive from the web to the kernel-mode HTTP.sys driver.
  2. 驱动程序将请求路由到网站的配置端口上的 IIS。The driver routes the requests to IIS on the website's configured port. 配置的端口通常是 80 (HTTP) 或 443 (HTTPS)。The configured port is usually 80 (HTTP) or 443 (HTTPS).
  3. 此模块将该请求转发到应用的随机端口上的 Kestrel。The module forwards the requests to Kestrel on a random port for the app. 随机端口不是 80 或 443。The random port isn't 80 or 443.

ASP.NET Core 模块在启动时通过环境变量指定端口。The ASP.NET Core Module specifies the port via an environment variable at startup. UseIISIntegration 扩展将服务器配置为侦听 http://localhost:{PORT}The UseIISIntegration extension configures the server to listen on http://localhost:{PORT}. 执行其他检查,拒绝不是来自该模块的请求。Additional checks are performed, and requests that don't originate from the module are rejected. 此模块不支持 HTTPS 转发。The module doesn't support HTTPS forwarding. 即使请求由 IIS 通过 HTTPS 接收,它们还是通过 HTTP 转发。Requests are forwarded over HTTP even if received by IIS over HTTPS.

Kestrel 从模块获取请求后,请求会被转发到 ASP.NET Core 中间件管道中。After Kestrel picks up the request from the module, the request is forwarded into the ASP.NET Core middleware pipeline. 中间件管道处理该请求并将其作为 HttpContext 实例传递给应用的逻辑。The middleware pipeline handles the request and passes it on as an HttpContext instance to the app's logic. IIS 集成添加的中间件会将方案、远程 IP 和 pathbase 更新到帐户以将请求转发到 Kestrel。Middleware added by IIS Integration updates the scheme, remote IP, and pathbase to account for forwarding the request to Kestrel. 应用的响应传递回 IIS,IIS 将响应转发回发起请求的 HTTP 客户端。The app's response is passed back to IIS, which forwards it back to the HTTP client that initiated the request.

有关 ASP.NET Core 模块配置指南,请参阅 ASP.NET Core 模块For ASP.NET Core Module configuration guidance, see ASP.NET Core 模块.

有关托管的详细信息,请参阅在 ASP.NET Core 中托管For more information on hosting, see Host in ASP.NET Core.

应用程序配置Application configuration

启用 IISIntegration 组件Enable the IISIntegration components

CreateHostBuilder 中生成主机 (Program.cs),请调用 CreateDefaultBuilder 以启用 IIS 集成:When building a host in CreateHostBuilder (Program.cs), call CreateDefaultBuilder to enable IIS integration:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        ...

有关 CreateDefaultBuilder 的详细信息,请参阅 ASP.NET Core 中的 .NET 通用主机For more information on CreateDefaultBuilder, see ASP.NET Core 中的 .NET 通用主机.

进程外承载模型Out-of-process hosting model

要配置 IIS 选项,请在 ConfigureServices 中包括 IISOptions 的服务配置。To configure IIS options, include a service configuration for IISOptions in ConfigureServices. 下面的示例阻止应用填充 HttpContext.Connection.ClientCertificateThe following example prevents the app from populating HttpContext.Connection.ClientCertificate:

services.Configure<IISOptions>(options => 
{
    options.ForwardClientCertificate = false;
});
选项Option 默认Default 设置Setting
AutomaticAuthentication true 若为 trueIIS 集成中间件将设置经过 Windows 身份验证进行身份验证的 HttpContext.UserIf true, IIS Integration Middleware sets the HttpContext.User authenticated by Windows Authentication. 若为 false,中间件仅提供 HttpContext.User 的标识并在 AuthenticationScheme 显式请求时响应质询。If false, the middleware only provides an identity for HttpContext.User and responds to challenges when explicitly requested by the AuthenticationScheme. 必须在 IIS 中启用 Windows 身份验证使 AutomaticAuthentication 得以运行。Windows Authentication must be enabled in IIS for AutomaticAuthentication to function. 有关详细信息,请参阅 Windows 身份验证主题。For more information, see the Windows Authentication topic.
AuthenticationDisplayName null 设置在登录页上向用户显示的显示名。Sets the display name shown to users on login pages.
ForwardClientCertificate true 若为 true,且存在 MS-ASPNETCORE-CLIENTCERT 请求头,则填充 HttpContext.Connection.ClientCertificateIf true and the MS-ASPNETCORE-CLIENTCERT request header is present, the HttpContext.Connection.ClientCertificate is populated.

代理服务器和负载均衡器方案Proxy server and load balancer scenarios

IIS 集成中间件和 ASP.NET Core 模块配置为转发:The IIS Integration Middleware and the ASP.NET Core Module are configured to forward the:

  • 方案 (HTTP/HTTPS)。Scheme (HTTP/HTTPS).
  • 发起请求的远程 IP 地址。Remote IP address where the request originated.

IIS 集成中间件配置转发的标头中间件。The IIS Integration Middleware configures Forwarded Headers Middleware.

对于托管在其他代理服务器和负载均衡器后方的应用,可能需要附加配置。Additional configuration might be required for apps hosted behind additional proxy servers and load balancers. 有关详细信息,请参阅配置 ASP.NET Core 以使用代理服务器和负载均衡器For more information, see Configure ASP.NET Core to work with proxy servers and load balancers.

进程外托管模型Out-of-process hosting model

若要配置进程外托管应用,请在项目文件 ( .csproj) 中将 <AspNetCoreHostingModel> 属性的值设置为 OutOfProcessTo configure an app for out-of-process hosting, set the value of the <AspNetCoreHostingModel> property to OutOfProcess in the project file (.csproj):

<PropertyGroup>
  <AspNetCoreHostingModel>OutOfProcess</AspNetCoreHostingModel>
</PropertyGroup>

进程内托管设为 InProcess,这是默认值。In-process hosting is set with InProcess, which is the default value.

<AspNetCoreHostingModel> 的值不区分大小写,因此 inprocessoutofprocess 均为有效值。The value of <AspNetCoreHostingModel> is case insensitive, so inprocess and outofprocess are valid values.

使用 Kestrel 服务器,而不是 IIS HTTP 服务器 (IISHttpServer)。Kestrel server is used instead of IIS HTTP Server (IISHttpServer).

对于进程外托管,CreateDefaultBuilder 会调用 UseIISIntegration 来进行以下操作:For out-of-process, CreateDefaultBuilder calls UseIISIntegration to:

  • 在 ASP.NET Core 模块后运行时,配置服务器应侦听的端口和基本路径。Configure the port and base path the server should listen on when running behind the ASP.NET Core Module.
  • 配置主机以捕获启动错误。Configure the host to capture startup errors.

进程名Process name

Process.GetCurrentProcess().ProcessName 报告 w3wp/iisexpress(进程内)或 dotnet(进程外)。Process.GetCurrentProcess().ProcessName reports w3wp/iisexpress (in-process) or dotnet (out-of-process).

许多本机模块(如 Windows 身份验证)仍处于活动状态。Many native modules, such as Windows Authentication, remain active. 要详细了解随 ASP.NET Core 模块活动的 IIS 模块,请参阅 IIS 模块与 ASP.NET CoreTo learn more about IIS modules active with the ASP.NET Core Module, see IIS 模块与 ASP.NET Core.

ASP.NET Core 模块还可以:The ASP.NET Core Module can also:

  • 为工作进程设置环境变量。Set environment variables for the worker process.
  • 将 stdout 输出记录到文件存储器,以解决启动问题。Log stdout output to file storage for troubleshooting startup issues.
  • 转发 Windows 身份验证令牌。Forward Windows authentication tokens.