與 ASP.NET Core 搭配運作的 IIS 模組IIS 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.

ModuleModule 對 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
No
設定驗證Configuration Validation
ConfigurationValidationModule
Yes
HTTP 錯誤HTTP Errors
CustomErrorModule
No 狀態碼頁面中介軟體Status Code Pages Middleware
自訂記錄Custom Logging
CustomLoggingModule
Yes
預設文件Default Document
DefaultDocumentModule
No 預設檔案中介軟體Default Files Middleware
摘要式驗證Digest Authentication
DigestAuthenticationModule
Yes
目錄瀏覽Directory Browsing
DirectoryListingModule
No 目錄瀏覽中介軟體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
No 回應快取中介軟體Response Caching Middleware
HTTP 快取HTTP Caching
HttpCacheModule
No 回應快取中介軟體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
No
靜態壓縮Static Compression
StaticCompressionModule
No 回應壓縮中介軟體Response Compression Middleware
靜態內容Static Content
StaticFileModule
No 靜態檔案中介軟體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 版本已設定為 [沒有 Managed 程式碼] 時,受控模組對所裝載的 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.

ModuleModule 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,則所部署的 web.config 檔案會覆寫使用「IIS 管理員」來進行的所有變更。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> 區段的情況下部署應用程式。如果在 web.config 包含 <modules> 區段的情況下部署應用程式,但未先在「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. <modules> 區段新增至具有 <remove> 元素的應用程式本機 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.configOpen {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.

您也可以使用 Appcmd.exe 來移除 IIS 模組。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. 如果沒有此模組,IIS 就必須針對每個要求都讀取並剖析設定,即使是重複要求相同的 URL 時也一樣。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. 雖然不一定要有「URI 快取模組」,所裝載的 ASP.NET Core 應用程式就能執行,但建議您為所有 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. 雖然不一定要有「HTTP 快取模組」,所裝載的 ASP.NET Core 應用程式就能執行,但建議您為所有 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