Events
Nov 19, 11 PM - Nov 21, 11 PM
Join online sessions at Microsoft Ignite created to expand your skills and help you tackle today's complex issues.
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
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 the .NET and .NET Core Support Policy. For the current release, see the .NET 9 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.
Transformations to the web.config file can be applied automatically when an app is published based on:
These transformations occur for either of the following web.config generation scenarios:
Microsoft.NET.Sdk.Web
SDK.Build configuration transforms are run first.
Include a web.{CONFIGURATION}.config file for each build configuration (Debug|Release) requiring a web.config transformation.
In the following example, a configuration-specific environment variable is set in web.Release.config:
<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
<location>
<system.webServer>
<aspNetCore>
<environmentVariables xdt:Transform="InsertIfMissing">
<environmentVariable name="Configuration_Specific"
value="Configuration_Specific_Value"
xdt:Locator="Match(name)"
xdt:Transform="InsertIfMissing" />
</environmentVariables>
</aspNetCore>
</system.webServer>
</location>
</configuration>
The transform is applied when the configuration is set to Release:
dotnet publish --configuration Release
The MSBuild property for the configuration is $(Configuration)
.
Profile transformations are run second, after Build configuration transforms.
Include a web.{PROFILE}.config file for each profile configuration requiring a web.config transformation.
In the following example, a profile-specific environment variable is set in web.FolderProfile.config for a folder publish profile:
<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
<location>
<system.webServer>
<aspNetCore>
<environmentVariables xdt:Transform="InsertIfMissing">
<environmentVariable name="Profile_Specific"
value="Profile_Specific_Value"
xdt:Locator="Match(name)"
xdt:Transform="InsertIfMissing" />
</environmentVariables>
</aspNetCore>
</system.webServer>
</location>
</configuration>
The transform is applied when the profile is FolderProfile:
dotnet publish --configuration Release /p:PublishProfile=FolderProfile
The MSBuild property for the profile name is $(PublishProfile)
.
If no profile is passed, the default profile name is FileSystem and web.FileSystem.config is applied if the file is present in the app's content root.
Environment transformations are run third, after Build configuration and Profile transforms.
Include a web.{ENVIRONMENT}.config file for each environment requiring a web.config transformation.
In the following example, an environment-specific environment variable is set in web.Production.config for the Production environment:
<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
<location>
<system.webServer>
<aspNetCore>
<environmentVariables xdt:Transform="InsertIfMissing">
<environmentVariable name="Environment_Specific"
value="Environment_Specific_Value"
xdt:Locator="Match(name)"
xdt:Transform="InsertIfMissing" />
</environmentVariables>
</aspNetCore>
</system.webServer>
</location>
</configuration>
The transform is applied when the environment is Production:
dotnet publish --configuration Release /p:EnvironmentName=Production
The MSBuild property for the environment is $(EnvironmentName)
.
When publishing from Visual Studio and using a publish profile, see Visual Studio publish profiles (.pubxml) for ASP.NET Core app deployment.
The ASPNETCORE_ENVIRONMENT
environment variable is automatically added to the web.config file when the environment name is specified.
Custom transformations are run last, after Build configuration, Profile, and Environment transforms.
Include a {CUSTOM_NAME}.transform file for each custom configuration requiring a web.config transformation.
In the following example, a custom transform environment variable is set in custom.transform:
<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
<location>
<system.webServer>
<aspNetCore>
<environmentVariables xdt:Transform="InsertIfMissing">
<environmentVariable name="Custom_Specific"
value="Custom_Specific_Value"
xdt:Locator="Match(name)"
xdt:Transform="InsertIfMissing" />
</environmentVariables>
</aspNetCore>
</system.webServer>
</location>
</configuration>
The transform is applied when the CustomTransformFileName
property is passed to the dotnet publish command:
dotnet publish --configuration Release /p:CustomTransformFileName=custom.transform
The MSBuild property for the profile name is $(CustomTransformFileName)
.
To prevent transformations of the web.config file, set the MSBuild property $(IsWebConfigTransformDisabled)
:
dotnet publish /p:IsWebConfigTransformDisabled=true
ASP.NET Core feedback
ASP.NET Core is an open source project. Select a link to provide feedback:
Events
Nov 19, 11 PM - Nov 21, 11 PM
Join online sessions at Microsoft Ignite created to expand your skills and help you tackle today's complex issues.
Register now