`web.config` file

Article
07/31/2024

Note

This isn't the latest version of this article. For the current release, see the .NET 9 version of this article.

Warning

This version of ASP.NET Core is no longer supported. For more information, see .NET and .NET Core Support Policy. For the current release, see the .NET 8 version of this article.

Important

This information relates to a pre-release product that may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

For the current release, see the .NET 9 version of this article.

The web.config is a file that is read by IIS and the ASP.NET Core Module to configure an app hosted with IIS.

`web.config` file location

In order to set up the ASP.NET Core Module correctly, the web.config file must be present at the content root path (typically the app base path) of the deployed app. This is the same location as the website physical path provided to IIS. The web.config file is required at the root of the app to enable the publishing of multiple apps using Web Deploy.

Sensitive files exist on the app's physical path, such as {ASSEMBLY}.runtimeconfig.json, {ASSEMBLY}.xml (XML Documentation comments), and {ASSEMBLY}.deps.json, where the placeholder {ASSEMBLY} is the assembly name. When the web.config file is present and the site starts normally, IIS doesn't serve these sensitive files if they're requested. If the web.config file is missing, incorrectly named, or unable to configure the site for normal startup, IIS may serve sensitive files publicly.

The web.config file must be present in the deployment at all times, correctly named, and able to configure the site for normal start up. Never remove the web.config file from a production deployment.

If a web.config file isn't present in the project, the file is created with the correct processPath and arguments to configure the ASP.NET Core Module and moved to published output.

If a web.config file is present in the project, the file is transformed with the correct processPath and arguments to configure the ASP.NET Core Module and moved to published output. The transformation doesn't modify IIS configuration settings in the file.

The web.config file may provide additional IIS configuration settings that control active IIS modules. For information on IIS modules that are capable of processing requests with ASP.NET Core apps, see the IIS modules topic.

Creating, transforming, and publishing the web.config file is handled by an MSBuild target (_TransformWebConfig) when the project is published. This target is present in the Web SDK targets (Microsoft.NET.Sdk.Web). The SDK is set at the top of the project file:

<Project Sdk="Microsoft.NET.Sdk.Web">

To prevent the Web SDK from transforming the web.config file, use the <IsTransformWebConfigDisabled> property in the project file:

<PropertyGroup>
  <IsTransformWebConfigDisabled>true</IsTransformWebConfigDisabled>
</PropertyGroup>

When disabling the Web SDK from transforming the file, the processPath and arguments should be manually set by the developer. For more information, see ASP.NET Core Module (ANCM) for IIS.

Configuration of ASP.NET Core Module with `web.config`

The ASP.NET Core Module is configured with the aspNetCore section of the system.webServer node in the site's web.config file.

The following web.config file is published for a framework-dependent deployment and configures the ASP.NET Core Module to handle site requests:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet"
                  arguments=".\MyApp.dll"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

The following web.config is published for a self-contained deployment:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath=".\MyApp.exe"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

The InheritInChildApplications property is set to false to indicate that the settings specified within the <location> element aren't inherited by apps that reside in a subdirectory of the app.

When an app is deployed to Azure App Service, the stdoutLogFile path is set to \\?\%home%\LogFiles\stdout. The path saves stdout logs to the LogFiles folder, which is a location automatically created by the service.

For information on IIS sub-application configuration, see Advanced configuration.

Attributes of the `aspNetCore` element

Attribute	Description	Default
`arguments`	Optional string attribute. Arguments to the executable specified in `processPath`.
`disableStartUpErrorPage`	Optional Boolean attribute. If true, the 502.5 - Process Failure page is suppressed, and the 502 status code page configured in the `web.config` takes precedence.	`false`
`forwardWindowsAuthToken`	Optional Boolean attribute. If true, the token is forwarded to the child process listening on `%ASPNETCORE_PORT%` as a header 'MS-ASPNETCORE-WINAUTHTOKEN' per request. It's the responsibility of that process to call CloseHandle on this token per request.	`true`
`hostingModel`	Optional string attribute. Specifies the hosting model as in-process (`InProcess`/`inprocess`) or out-of-process (`OutOfProcess`/`outofprocess`).	`OutOfProcess`/`outofprocess` when not present
`processesPerApplication`	Optional integer attribute. Specifies the number of instances of the process specified in the `processPath` setting that can be spun up per app. †For in-process hosting, the value is limited to `1`. Setting `processesPerApplication` is discouraged. This attribute will be removed in a future release.	Default: `1` Min: `1` Max: `100`†
`processPath`	Required string attribute. Path to the executable that launches 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.
`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 stops launching the process for the remainder of the minute. Not supported with in-process hosting.	Default: `10` Min: `0` Max: `100`
`requestTimeout`	Optional timespan attribute. Specifies the duration for which the ASP.NET Core Module waits for a response from the process listening on %ASPNETCORE_PORT%. In versions of the ASP.NET Core Module that shipped with the release of ASP.NET Core 2.1 or later, the `requestTimeout` is specified in hours, minutes, and seconds. Doesn't apply to in-process hosting. For in-process hosting, the module waits for the app to process the request. Valid values for minutes and seconds segments of the string are in the range 0-59. Use of `60` in the value for minutes or seconds results in a 500 - Internal Server Error.	Default: `00:02:00` Min: `00:00:00` Max: `360:00:00`
`shutdownTimeLimit`	Optional integer attribute. Duration in seconds that the module waits for the executable to gracefully shutdown when the `app_offline.htm` file is detected.	Default: `10` Min: `0` Max: `600`
`startupTimeLimit`	Optional integer attribute. Duration in seconds that the module waits for the executable to start a process listening on the port. If this time limit is exceeded, the module kills the process. When hosting in-process: The process is not restarted and does not use the `rapidFailsPerMinute` setting. When hosting out-of-process: The module attempts to relaunch the process when it receives a new request and continues to attempt to restart the process on subsequent incoming requests unless the app fails to start `rapidFailsPerMinute` number of times in the last rolling minute. A value of 0 (zero) is not considered an infinite timeout.	Default: `120` Min: `0` Max: `3600`
`stdoutLogEnabled`	Optional Boolean attribute. If true, `stdout` and `stderr` for the process specified in `processPath` are redirected to the file specified in `stdoutLogFile`.	`false`
`stdoutLogFile`	Optional string attribute. Specifies the relative or absolute file path for which `stdout` and `stderr` from the process specified in `processPath` are logged. Relative paths are relative to the root of the site. Any path starting with `.` are relative to the site root and all other paths are treated as absolute paths. Any folders provided in the path are created by the module when the log file is created. Using underscore delimiters, a timestamp, process ID, and file extension (`.log`) are added to the last segment of the `stdoutLogFile` path. If `.\logs\stdout` is supplied as a value, an example stdout log is saved as `stdout_20180205194132_1934.log` in the `logs` folder when saved on February 5, 2018 at 19:41:32 with a process ID of 1934.	`aspnetcore-stdout`

Set environment variables

Environment variables can be specified for the process in the processPath attribute. Specify an environment variable with the <environmentVariable> child element of an <environmentVariables> collection element. Environment variables set in this section take precedence over system environment variables.

The following example sets two environment variables in web.config. ASPNETCORE_ENVIRONMENT configures the app's environment to Development. A developer may temporarily set this value in the web.config file in order to force the Developer Exception Page to load when debugging an app exception. CONFIG_DIR is an example of a user-defined environment variable, where the developer has written code that reads the value on startup to form a path for loading the app's configuration file.

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile=".\logs\stdout"
      hostingModel="inprocess">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
    <environmentVariable name="CONFIG_DIR" value="f:\application_config" />
  </environmentVariables>
</aspNetCore>

Note

An alternative to setting the environment directly in web.config is to include the <EnvironmentName> property in the publish profile (.pubxml) or project file. This approach sets the environment in web.config when the project is published:

<PropertyGroup>
  <EnvironmentName>Development</EnvironmentName>
</PropertyGroup>

Warning

Only set the ASPNETCORE_ENVIRONMENT environment variable to Development on staging and testing servers that aren't accessible to untrusted networks, such as the Internet.

Configuration of IIS with `web.config`

IIS configuration is influenced by the <system.webServer> section of web.config for IIS scenarios that are functional for ASP.NET Core apps with the ASP.NET Core Module. For example, IIS configuration is functional for dynamic compression. If IIS is configured at the server level to use dynamic compression, the <urlCompression> element in the app's web.config file can disable it for an ASP.NET Core app.

For more information, see the following topics:

To set environment variables for individual apps running in isolated app pools (supported for IIS 10.0 or later), see the AppCmd.exe command section of the Environment Variables <environmentVariables> topic in the IIS reference documentation.

Configuration sections of `web.config`

Configuration sections of ASP.NET 4.x apps in web.config aren't used by ASP.NET Core apps for configuration:

<system.web>
<appSettings>
<connectionStrings>
<location>

ASP.NET Core apps are configured using other configuration providers. For more information, see Configuration.

Transform web.config

If you need to transform web.config on publish, see Transform web.config. You might need to transform web.config on publish to set environment variables based on the configuration, profile, or environment.

Share via

`web.config` file

`web.config` file location

Configuration of ASP.NET Core Module with `web.config`

Attributes of the `aspNetCore` element

Set environment variables

Configuration of IIS with `web.config`

Configuration sections of `web.config`

Transform web.config

Additional resources

Additional resources

Share via

web.config file

web.config file location

Configuration of ASP.NET Core Module with web.config

Attributes of the aspNetCore element

Set environment variables

Configuration of IIS with web.config

Configuration sections of web.config

Transform web.config

Additional resources

Additional resources

`web.config` file

`web.config` file location

Configuration of ASP.NET Core Module with `web.config`

Attributes of the `aspNetCore` element

Configuration of IIS with `web.config`

Configuration sections of `web.config`