web.config
file
Note
This isn't the latest version of this article. For the current release, see the .NET 8 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 8 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 |
|
disableStartUpErrorPage |
Optional Boolean attribute. If true, the 502.5 - Process Failure page is suppressed, and the 502 status code page configured in the |
false |
forwardWindowsAuthToken |
Optional Boolean attribute. If true, the token is forwarded to the child process listening on |
true |
hostingModel |
Optional string attribute. Specifies the hosting model as in-process ( |
OutOfProcess /outofprocess when not present |
processesPerApplication |
Optional integer attribute. Specifies the number of instances of the process specified in the †For in-process hosting, the value is limited to Setting |
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 |
|
rapidFailsPerMinute |
Optional integer attribute. Specifies the number of times the process specified in 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 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 |
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 |
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 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 A value of 0 (zero) is not considered an infinite timeout. |
Default: 120 Min: 0 Max: 3600 |
stdoutLogEnabled |
Optional Boolean attribute. If true, |
false |
stdoutLogFile |
Optional string attribute. Specifies the relative or absolute file path for which |
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:
- Configuration reference for
<system.webServer>
- ASP.NET Core Module (ANCM) for IIS
- IIS modules with ASP.NET Core
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.
Additional resources
ASP.NET Core
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for