Using IIS Modules with ASP.NET Core

By Luke Latham

ASP.NET Core applications are hosted by IIS in a reverse-proxy configuration. Some of the native IIS modules and all of the IIS managed modules are not available to process requests for ASP.NET Core apps. In many cases, ASP.NET Core offers an alternative to the features of IIS native and managed modules.

Native Modules

Module	.NET Core Active	ASP.NET Core Option
Anonymous Authentication `AnonymousAuthenticationModule`	Yes
Basic Authentication `BasicAuthenticationModule`	Yes
Client Certification Mapping Authentication `CertificateMappingAuthenticationModule`	Yes
CGI `CgiModule`	No
Configuration Validation `ConfigurationValidationModule`	Yes
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
Tracing `FailedRequestsTracingModule`	Yes	ASP.NET Core Logging
File Caching `FileCacheModule`	No	Response Caching Middleware
HTTP Caching `HttpCacheModule`	No	Response Caching Middleware
HTTP Logging `HttpLoggingModule`	Yes	ASP.NET Core Logging Implementations: elmah.io, Loggr, NLog, Serilog
HTTP Redirection `HttpRedirectionModule`	Yes	URL Rewriting Middleware
IIS Client Certificate Mapping Authentication `IISCertificateMappingAuthenticationModule`	Yes
IP and Domain Restrictions `IpRestrictionModule`	Yes
ISAPI Filters `IsapiFilterModule`	Yes	Middleware
ISAPI `IsapiModule`	Yes	Middleware
Protocol Support `ProtocolSupportModule`	Yes
Request Filtering `RequestFilteringModule`	Yes	URL Rewriting Middleware `IRule`
Request Monitor `RequestMonitorModule`	Yes
URL Rewriting `RewriteModule`	Yes†	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 Caching `UriCacheModule`	Yes
URL Authorization `UrlAuthorizationModule`	Yes	ASP.NET Core Identity
Windows Authentication `WindowsAuthenticationModule`	Yes

†The URL Rewrite Module's isFile and isDirectory do not work with ASP.NET Core applications due to the changes in directory structure.

Managed Modules

Module	.NET Core Active	ASP.NET Core Option
AnonymousIdentification	No
DefaultAuthentication	No
FileAuthorization	No
FormsAuthentication	No	Cookie Authentication Middleware
OutputCache	No	Response Caching Middleware
Profile	No
RoleManager	No
ScriptModule-4.0	No
Session	No	Session Middleware
UrlAuthorization	No
UrlMappingsModule	No	URL Rewriting Middleware
UrlRoutingModule-4.0	No	ASP.NET Core Identity
WindowsAuthentication	No

IIS Manager application changes

When you use IIS Manager to configure settings, you're directly changing the web.config file of the app. If you deploy your app and include web.config, any changes you made with IIS Manger will be overwritten by the deployed web.config file. Therefore if you make changes to the server's web.config file, copy the updated web.config file to your local project immediately.

Disabling IIS modules

If you have an IIS module configured at the server level that you would like to disable for an application, you can do so with an addition to your web.config file. 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 will allow you to disable them without removing them from the application. This is the simplest and quickest way to deactivate a module. For example if you wish to disable the IIS URL Rewrite Module, use the <httpRedirect> element as shown below. For more information on disabling modules with configuration settings, follow the links in the Child Elements section of IIS <system.webServer>.

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

Module removal

If you opt to remove a module with a setting in web.config, you must unlock the module and unlock the <modules> section of web.config first. The steps are outlined below:

Unlock the module at the server level. Click on the IIS server in the IIS Manager Connections sidebar. Open the Modules in the IIS area. Click on the module in the list. In the Actions sidebar on the right, click Unlock. Unlock as many modules as you plan to remove with web.config later.
Deploy your application without a <modules> section in web.config. If you deploy an app with a web.config containing the <modules> section without having unlocked the section first in the IIS Manager, the Configuration Manager will throw an exception when you try to unlock the section. Therefore, deploy your application without a <modules> section.
Unlock the <modules> section of web.config. In the Connections sidebar, click the website in Sites. In the Management area, open the Configuration Editor. Use the navigation controls to select the system.webServer/modules section. In the Actions sidebar on the right, click to Unlock the section.
At this point, you will be able to add a <modules> section to your web.config file with a <remove> element to remove the module from the application. You can add multiple <remove> elements to remove multiple modules. Don't forget that if you make web.config changes on the server to make them immediately in the project locally. Removing a module this way won't affect your use of the module with other apps on the server.
```
<configuration> 
 <system.webServer> 
   <modules> 
     <remove name="MODULE_NAME" /> 
   </modules> 
 </system.webServer> 
</configuration>
```

For an IIS installation with the default modules installed, you can use the following <module> section to remove the default modules.

<modules>
  <remove name="CustomErrorModule" />
  <remove name="DefaultDocumentModule" />
  <remove name="DirectoryListingModule" />
  <remove name="HttpCacheModule" />
  <remove name="HttpLoggingModule" />
  <remove name="ProtocolSupportModule" />
  <remove name="RequestFilteringModule" />
  <remove name="StaticCompressionModule" /> 
  <remove name="StaticFileModule" /> 
</modules>

You can also remove an IIS module with Appcmd.exe. Provide the MODULE_NAME and APPLICATION_NAME in the command shown below:

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

Here's how to remove the DynamicCompressionModule from the Default Web Site:

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

Minimal module configuration

The only modules required to run an ASP.NET Core application are the Anonymous Authentication Module and the ASP.NET Core Module.

IIS Manager open to Modules with the minimum module configuration shown