web.config file (2024)

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

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>

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

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

• IIS <system.webServer>
• IIS modules with ASP.NET Core
• Transform web.config