IIS 模块与 ASP.NET CoreIIS modules with ASP.NET Core

作者:Luke LathamBy Luke Latham

某些本机 IIS 模块和所有 IIS 托管模块无法处理 ASP.NET Core 应用的请求。Some of the native IIS modules and all of the IIS managed modules aren't able to process requests for ASP.NET Core apps. 在许多情况下,ASP.NET Core 提供了 IIS 本机和托管模块解决的方案的替代方案。In many cases, ASP.NET Core offers an alternative to the scenarios addressed by IIS native and managed modules.

本机模块Native modules

该表指示在使用 ASP.NET Core 应用和 ASP.NET Core 模块时正常工作的本机 IIS 模块。The table indicates native IIS modules that are functional with ASP.NET Core apps and the ASP.NET Core Module.

模块Module 在 ASP.NET Core 应用内可用Functional with ASP.NET Core apps ASP.NET Core 选项ASP.NET Core Option
匿名身份验证Anonymous Authentication
AnonymousAuthenticationModule
Yes
基本身份验证Basic Authentication
BasicAuthenticationModule
Yes
客户端证书映射身份验证Client Certification Mapping Authentication
CertificateMappingAuthenticationModule
Yes
CGICGI
CgiModule
NoNo
配置验证Configuration Validation
ConfigurationValidationModule
Yes
HTTP 错误HTTP Errors
CustomErrorModule
NoNo 状态代码页中间件Status Code Pages Middleware
自定义日志记录Custom Logging
CustomLoggingModule
Yes
默认文档Default Document
DefaultDocumentModule
NoNo 默认文件中间件Default Files Middleware
摘要式身份验证Digest Authentication
DigestAuthenticationModule
Yes
目录浏览Directory Browsing
DirectoryListingModule
NoNo 目录浏览中间件Directory Browsing Middleware
动态压缩Dynamic Compression
DynamicCompressionModule
Yes 响应压缩中间件Response Compression Middleware
请求跟踪失败Failed Requests Tracing
FailedRequestsTracingModule
Yes ASP.NET Core 日志记录ASP.NET Core Logging
文件缓存File Caching
FileCacheModule
NoNo 响应缓存中间件Response Caching Middleware
HTTP 缓存HTTP Caching
HttpCacheModule
NoNo 响应缓存中间件Response Caching Middleware
HTTP 日志记录HTTP Logging
HttpLoggingModule
Yes ASP.NET Core 日志记录ASP.NET Core Logging
HTTP 重定向HTTP Redirection
HttpRedirectionModule
Yes URL 重写中间件URL Rewriting Middleware
HTTP 跟踪HTTP Tracing
TracingModule
Yes
IIS 客户端证书映射身份验证IIS Client Certificate Mapping Authentication
IISCertificateMappingAuthenticationModule
Yes
IP 和域限制IP and Domain Restrictions
IpRestrictionModule
Yes
ISAPI 筛选器ISAPI Filters
IsapiFilterModule
Yes 中间件Middleware
ISAPIISAPI
IsapiModule
Yes 中间件Middleware
协议支持Protocol Support
ProtocolSupportModule
Yes
请求筛选Request Filtering
RequestFilteringModule
Yes URL 重写中间件IRuleURL Rewriting Middleware IRule
请求监视器Request Monitor
RequestMonitorModule
Yes
URL 重写†URL Rewriting
RewriteModule
Yes URL 重写中间件URL Rewriting Middleware
服务器端包括Server-Side Includes
ServerSideIncludeModule
NoNo
静态压缩Static Compression
StaticCompressionModule
NoNo 响应压缩中间件Response Compression Middleware
静态内容Static Content
StaticFileModule
NoNo 静态文件中间件Static File Middleware
令牌缓存Token Caching
TokenCacheModule
Yes
URI 缓存URI Caching
UriCacheModule
Yes
URL 授权URL Authorization
UrlAuthorizationModule
Yes ASP.NET Core 标识ASP.NET Core Identity
Windows 身份验证Windows Authentication
WindowsAuthenticationModule
Yes

†由于目录结构中的更改,URL 重写模块的 isFileisDirectory 匹配类型不适用于 ASP.NET Core 应用。†The URL Rewrite Module's isFile and isDirectory match types don't work with ASP.NET Core apps due to the changes in directory structure.

托管模块Managed modules

当应用池的 .NET CLR 版本设置为“无托管代码”时,托管 ASP.NET Core 应用的托管模块无法使用。Managed modules are not functional with hosted ASP.NET Core apps when the app pool's .NET CLR version is set to No Managed Code. ASP.NET Core 在几种情况下提供了中间件替代方案。ASP.NET Core offers middleware alternatives in several cases.

模块Module ASP.NET Core 选项ASP.NET Core Option
AnonymousIdentificationAnonymousIdentification
DefaultAuthenticationDefaultAuthentication
FileAuthorizationFileAuthorization
FormsAuthenticationFormsAuthentication Cookie 身份验证中间件Cookie Authentication Middleware
OutputCacheOutputCache 响应缓存中间件Response Caching Middleware
配置文件Profile
RoleManagerRoleManager
ScriptModule-4.0ScriptModule-4.0
会话Session 会话中间件Session Middleware
UrlAuthorizationUrlAuthorization
UrlMappingsModuleUrlMappingsModule URL 重写中间件URL Rewriting Middleware
UrlRoutingModule-4.0UrlRoutingModule-4.0 ASP.NET Core 标识ASP.NET Core Identity
WindowsAuthenticationWindowsAuthentication

IIS 管理器应用程序更改IIS Manager application changes

使用 IIS 管理器配置设置时,应用的 web.config 文件已更改。When using IIS Manager to configure settings, the web.config file of the app is changed. 如果部署应用并包括 web.config,则使用 IIS 管理器所做的任何更改都会被部署的 web.config 文件覆盖。If deploying an app and including web.config, any changes made with IIS Manager are overwritten by the deployed web.config file. 如果更改服务器的 web.config 文件,请立即将服务器上已更新的 web.config 文件复制到本地项目。If changes are made to the server's web.config file, copy the updated web.config file on the server to the local project immediately.

禁用 IIS 模块Disabling IIS modules

如果在服务器级别配置了必须为应用禁用的 IIS 模块,则应用 web.config 文件还可以禁用该模块。If an IIS module is configured at the server level that must be disabled for an app, an addition to the app's web.config file can disable the module. 将模块留在原位并使用配置设置(如果可用)将其停用或从应用中移除模块。Either leave the module in place and deactivate it using a configuration setting (if available) or remove the module from the app.

模块停用Module deactivation

许多模块提供一个配置设置,允许在不从应用中删除模块的情况下禁用它们。Many modules offer a configuration setting that allows them to be disabled without removing the module from the app. 这是停用模块最简单、快捷的方式。This is the simplest and quickest way to deactivate a module. 例如,可使用 web.config 中的 <httpRedirect> 元素禁用 HTTP 重定向模块:For example, the HTTP Redirection Module can be disabled with the <httpRedirect> element in web.config:

<configuration>
  <system.webServer>
    <httpRedirect enabled="false" />
  </system.webServer>
</configuration>

有关通过配置设置禁用模块的详细信息,请按照 IIS <system.webServer> 的子元素部分中的链接进行操作。For more information on disabling modules with configuration settings, follow the links in the Child Elements section of IIS <system.webServer>.

模块删除Module removal

如果选择使用 web.config 中的设置删除模块,请先解锁此模块和 web.config 的 <modules> 部分:If opting to remove a module with a setting in web.config, unlock the module and unlock the <modules> section of web.config first:

  1. 解锁服务器级别的模块。Unlock the module at the server level. 在 IIS 管理器“连接”边栏中选择 IIS 服务器。Select the IIS server in the IIS Manager Connections sidebar. 打开 IIS 区域中的模块。Open the Modules in the IIS area. 在列表中选择该模块。Select the module in the list. 在右侧的“操作”边栏中,选择“解锁”。In the Actions sidebar on the right, select Unlock. 如果该模块的操作条目显示为“锁定”,则该模块已被解锁,且无需任何操作。If the action entry for the module appears as Lock, the module is already unlocked, and no action is required. 解锁尽可能多稍后计划从 web.config 中删除的模块。Unlock as many modules as you plan to remove from web.config later.

  2. 在不使用 web.config 的 <modules> 部分的情况下部署应用。如果使用包含 <modules> 部分的 web.config 部署应用,但未先在 IIS 管理器中解锁该部分,则配置管理器会在尝试解锁该部分时引发异常。Deploy the app without a <modules> section in web.config. If an app is deployed with a web.config containing the <modules> section without having unlocked the section first in the IIS Manager, the Configuration Manager throws an exception when attempting to unlock the section. 因此,请在不使用 <modules> 部分的情况下部署该应用。Therefore, deploy the app without a <modules> section.

  3. 解锁 web.config 的 <modules> 部分。在“连接”边栏中,选择“站点”中的网站。Unlock the <modules> section of web.config. In the Connections sidebar, select the website in Sites. 在“管理”区域中,打开“配置编辑器”。In the Management area, open the Configuration Editor. 使用导航控件选择 system.webServer/modules 部分。Use the navigation controls to select the system.webServer/modules section. 在右侧的“操作”边栏中,选择“解锁”该部分。In the Actions sidebar on the right, select to Unlock the section. 如果该模块的操作条目显示为“锁定部分”,则该模块已被解锁,且无需任何操作。If the action entry for the module section appears as Lock Section, the module section is already unlocked, and no action is required.

  4. 可使用 <remove> 元素将 <modules> 部分添加到应用的本地 web.config 文件,从应用中删除模块。Add a <modules> section to the app's local web.config file with a <remove> element to remove the module from the app. 可添加多个 <remove> 元素来删除多个模块。Add multiple <remove> elements to remove multiple modules. 如果在服务器上更改 web.config,请立即在本地对项目的 web.config 文件执行相同的更改。If web.config changes are made on the server, immediately make the same changes to the project's web.config file locally. 以这种方式删除模块不会影响模块的使用与服务器上的其他应用。Removing a module using this approach doesn't affect the use of the module with other apps on the server.

    <configuration>
     <system.webServer>
       <modules>
         <remove name="MODULE_NAME" />
       </modules>
     </system.webServer>
    </configuration>
    

要使用 web.config 为 IIS Express 添加或删除模块,请修改 applicationHost.config 以解锁 <modules> 部分:In order to add or remove modules for IIS Express using web.config, modify applicationHost.config to unlock the <modules> section:

  1. 打开 {APPLICATION ROOT}\.vs\config\applicationhost.config。Open {APPLICATION ROOT}\.vs\config\applicationhost.config.

  2. 找到 IIS 模块的 <section> 元素,并将 overrideModeDefaultDeny 更改为 AllowLocate the <section> element for IIS modules and change overrideModeDefault from Deny to Allow:

    <section name="modules"
             allowDefinition="MachineToApplication"
             overrideModeDefault="Allow" />
    
  3. 找到 <location path="" overrideMode="Allow"><system.webServer><modules> 部分。Locate the <location path="" overrideMode="Allow"><system.webServer><modules> section. 对于任何要删除的模块,请将 lockItemtrue 设置为 falseFor any modules that you wish to remove, set lockItem from true to false. 在以下示例中,已解锁 CGI 模块:In the following example, the CGI Module is unlocked:

    <add name="CgiModule" lockItem="false" />
    
  4. 解锁 <modules> 部分和单个模块后,可使用应用的 web.config 文件添加或删除 IIS 模块,以便在 IIS Express 上运行应用。After the <modules> section and individual modules are unlocked, you're free to add or remove IIS modules using the app's web.config file for running the app on IIS Express.

IIS 模块还可以使用 Appcmd.exe 删除。An IIS module can also be removed with Appcmd.exe. 该命令中提供 MODULE_NAMEAPPLICATION_NAMEProvide the MODULE_NAME and APPLICATION_NAME in the command:

Appcmd.exe delete module MODULE_NAME /app.name:APPLICATION_NAME

例如,从默认网站中删除 DynamicCompressionModuleFor example, remove the DynamicCompressionModule from the Default Web Site:

%windir%\system32\inetsrv\appcmd.exe delete module DynamicCompressionModule /app.name:"Default Web Site"

最小模块配置Minimum module configuration

要求运行 ASP.NET Core 应用的模块只有匿名身份验证模块和 ASP.NET Core 模块。The only modules required to run an ASP.NET Core app are the Anonymous Authentication Module and the ASP.NET Core Module.

URI 缓存模块 (UriCacheModule) 允许 IIS 在 URL 级别缓存网站配置。The URI Caching Module (UriCacheModule) allows IIS to cache website configuration at the URL level. 不使用此模块的话,即使重复请求相同的 URL,IIS 也必须读取并分析每个请求的配置。Without this module, IIS must read and parse configuration on every request, even when the same URL is repeatedly requested. 分析每个请求的配置会导致严重的性能损失。Parsing the configuration every request results in a significant performance penalty. 虽然托管的 ASP.NET Core 应用并非严格要求运行 URI 缓存模块,但我们建议为所有 ASP.NET Core 部署启用 URI 缓存模块。Although the URI Caching Module isn't strictly required for a hosted ASP.NET Core app to run, we recommend that the URI Caching Module be enabled for all ASP.NET Core deployments.

HTTP 缓存模块 (HttpCacheModule) 实现 IIS 输出缓存以及用于在 HTTP.sys 缓存中缓存项目的逻辑。The HTTP Caching Module (HttpCacheModule) implements the IIS output cache and also the logic for caching items in the HTTP.sys cache. 如果不使用此模块,内容不再以内核模式缓存,并且缓存配置文件将被忽略。Without this module, content is no longer cached in kernel mode, and cache profiles are ignored. 删除 HTTP 缓存模块通常会对性能和资源使用情况产生不利影响。Removing the HTTP Caching Module usually has adverse effects on performance and resource usage. 虽然托管的 ASP.NET Core 应用程序并非严格要求运行 HTTP 缓存模块,但我们建议为所有 ASP.NET Core 部署启用 HTTP 缓存模块。Although the HTTP Caching Module isn't strictly required for a hosted ASP.NET Core app to run, we recommend that the HTTP Caching Module be enabled for all ASP.NET Core deployments.

其他资源Additional resources