10 KiB

Raw Blame History

title	author	description	keywords	ms.author	manager	ms.date	ms.topic	ms.assetid	ms.technology	ms.prod	uid
ASP.NET Core Module Configuration Reference \| Microsoft Docs	rick-anderson		ASP.NET Core,	riande	wpickett	10/27/2016	article	5de0c8f7-50ce-4e2c-b3d4-a1bd9fdfcff5	aspnet	aspnet-core	hosting/aspnet-core-module

ASP.NET Core Module Configuration Reference

By Luke Latham, Rick Anderson and Sourabh Shirhatti

ASP.NET Core Module is an IIS module that lets Kestrel use IIS or IIS Express as a reverse proxy server. This document provides an overview of how to configure the ASP.NET Core Module for shared hosting of ASP.NET Core applications.

For an introduction to ASP.NET Core Module and information about how to install it, see ASP.NET Core Module.

The Web.config file

The ASP.NET Core Module is configured via a site or application web.config file and has its own aspNetCore configuration section within system.webServer. Here's an example from a Visual Studio project, with placeholders for settings that Visual Studio plugs in when you run or debug the project.

<configuration>
  <!--
    Configure your application settings in appsettings.json. Learn more at http://go.microsoft.com/fwlink/?LinkId=786380
  -->
  <system.webServer>
    <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
    </handlers>
    <aspNetCore processPath="%LAUNCHER_PATH%" arguments="%LAUNCHER_ARGS%" stdoutLogEnabled="true" stdoutLogFile=".\logs\stdout" forwardWindowsAuthToken="false" />
  </system.webServer>
</configuration>

When the project is published, Visual Studio automatically plugs in the values required for the destination environment, as shown in this example of a project that has been deployed to an Azure web app.

<configuration>
  <!--
    Configure your application settings in appsettings.json. Learn more at http://go.microsoft.com/fwlink/?LinkId=786380
  -->
  <system.webServer>
    <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
    </handlers>
    <aspNetCore processPath=".\sample.exe" arguments="" stdoutLogEnabled="true" stdoutLogFile="\\?\%home%\LogFiles\stdout" forwardWindowsAuthToken="false" />
  </system.webServer>
</configuration>
<!--ProjectGuid: c270f740-c62c-4f88-a2dc-c3f7e9dc61e8-->

Attributes of the aspNetCore element

Attribute	Description
processPath	Required string attribute. Path to the executable that will launch a process listening for HTTP requests. Relative paths are supported. If the path begins with '.', the path is considered to be relative to the site root. There is no default value.
arguments	Optional string attribute. Arguments to the executable specified in processPath. The default value is an empty string.
startupTimeLimit	Optional integer attribute. Duration in seconds for which the module will wait for the executable to start a process listening on the port. If this time limit is exceeded, the module will kill the process. The module will attempt to launch the process again when it receives a new request and will continue to attempt to restart the process on subsequent incoming requests unless the application fails to start rapidFailsPerMinute number of times in the last rolling minute. The default value is 120.
shutdownTimeLimit	Optional integer attribute. Duration in seconds for which the module will wait for the executable to gracefully shutdown when the app_offline.htm file is detected. The default value is 10.
rapidFailsPerMinute	Optional integer attribute. Specifies the number of times the process specified in processPath is allowed to crash per minute. If this limit is exceeded, the module will stop launching the process for the remainder of the minute. The default value is 10.
requestTimeout	Optional timespan attribute. Specifies the duration for which the ASP.NET Core Module will wait for a response from the process listening on %ASPNETCORE_PORT%. The default value is "00:02:00".
stdoutLogEnabled	Optional Boolean attribute. If true, stdout and stderr for the process specified in processPath will be redirected to the file specified in stdoutLogFile. The default value is false.
stdoutLogFile	Optional string attribute. Specifies the relative or absolute file path for which stdout and stderr from the process specified in processPath will be logged. Relative paths are relative to the root of the site. Any path starting with '.' will be relative to the site root and all other paths will be treated as absolute paths. A timestamp and the file extension will automatically be added to the filename provided. Any folders provided in the path must exist in order for the module to create the log file. The default value is `aspnetcore-stdout`.
forwardWindowsAuthToken	true or false. If true, the token will be forwarded to the child process listening on %ASPNETCORE_PORT% as a header 'MS-ASPNETCORE-WINAUTHTOKEN' per request. It is the responsibility of that process to call CloseHandle on this token per request. The default value is false.
disableStartUpErrorPage	true or false. If true, the 502.5 - Process Failure page will be suppressed, and the 502 status code page configured in your web.config will take precedence. The default value is false.

environmentVariables child element of aspNetCore

The ASP.NET Core Module allows you specify environment variables for the process specified in the processPath attribute by specifying them in one or more environmentVariable child elements of an environmentVariables collection element under the aspNetCore element. Environment variables set in this section take precedence over system environment variables for the process.

Here's an example that sets two environment variables.

<aspNetCore processPath="dotnet"
        arguments=".\MyApp.dll"
        stdoutLogEnabled="false"
        stdoutLogFile="\\?\%home%\LogFiles\stdout">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Staging" />
    <environmentVariable name="ENV_VAR_1" value="VALUE_1" />
    <environmentVariable name="ENV_VAR_2" value="VALUE_2" />
  </environmentVariables>
</aspNetCore>

app_offline.htm

If you place a file with the name app_offline.htm at the root of a web application directory, the ASP.NET Core Module will attempt to gracefully shut-down the application and stop processing any new incoming requests. If the application is still running after shutdownTimeLimit number of seconds, the ASP.NET Core Module will kill the running process.

While the app_offline.htm file is present, the ASP.NET Core Module will respond to all requests by sending back the contents of the app_offline.htm file. Once the app_offline.htm file is removed, the next request loads the application, which then responds to requests.

Start-up error page

If the ASP.NET Core Module fails to launch the backend process or the backend process starts but fails to listen on the configured port, you will see an HTTP 502.5 status code page.

To suppress this page and revert to the default IIS 502 status code page, use the disableStartUpErrorPage attribute. Look at the HTTP Errors attribute to override this page with a custom error page.

Log creation and redirection

The ASP.NET Core Module redirects stdout and stderr logs to disk if you set the stdoutLogEnabled and stdoutLogFile attributes of the aspNetCore element. Any folders in the stdoutLogFile path must exist in order for the module to create the log file. A timestamp and file extension will be added automatically when the log file is created. Logs are not rotated (unless process recycling/restart occurs). It is the responsibility of the hoster to limit the disk space the logs consume. Using the stdout log is only recommended for troubleshooting application startup issues and not for general application logging purposes.

Here's a sample aspNetCore element that configures stdout logging:

<aspNetCore processPath="dotnet"
        arguments=".\MyApp.dll"
        stdoutLogEnabled="true"
        stdoutLogFile="\\?\%home%\LogFiles\stdout">
</aspNetCore>

ASP.NET Core Module with IIS Shared Configuration

The ASP.NET Core Module installer runs with the privileges of the SYSTEM account. Because the local system account does not have modify permission for the share path which is used by the IIS Shared Configuration, the installer will hit an access denied error when attempting to configure the module settings in applicationHost.config on the share.

The unsupported workaround is to disable the IIS Shared Configuration, run the installer, export the updated applicationHost.config file to the share, and re-enable the IIS Shared Configuration.

Module, schema, and configuration file locations

Module

IIS (x86/amd64):

%windir%\System32\inetsrv\aspnetcore.dll
%windir%\SysWOW64\inetsrv\aspnetcore.dll

IIS Express (x86/amd64):

%ProgramFiles%\IIS Express\aspnetcore.dll
%ProgramFiles(x86)%\IIS Express\aspnetcore.dll

Schema

IIS

%windir%\System32\inetsrv\config\schema\aspnetcore_schema.xml

IIS Express

%ProgramFiles%\IIS Express\config\schema\aspnetcore_schema.xml

Configuration