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:

  1. 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.

  2. 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.

  3. 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.

  4. 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

Resources