| title | Configure ASP.NET Apps | ||||
|---|---|---|---|---|---|
| description | Learn how to configure an ASP.NET app in Azure App Service. This article shows the most common configuration tasks. | ||||
| ms.devlang | csharp | ||||
| ms.topic | concept-article | ||||
| ms.date | 07/07/2025 | ||||
| author | cephalin | ||||
| ms.author | cephalin | ||||
| ms.service | azure-app-service | ||||
| ms.custom |
|
Note
For ASP.NET Core, see Configure an ASP.NET Core app for Azure App Service. If your ASP.NET app runs in a custom Windows or Linux container, see Configure a custom container for Azure App Service.
ASP.NET apps must be deployed to Azure App Service as compiled binaries. The Visual Studio publishing tool builds the solution and then deploys the compiled binaries directly. The App Service deployment engine deploys the code repository first and then compiles the binaries.
This guide provides key concepts and instructions for ASP.NET developers. If this article is your first experience with Azure App Service, follow Deploy an ASP.NET web app and Deploy an ASP.NET app with Azure SQL database to Azure first.
In App Service, the Windows instances already have all the supported .NET Framework versions installed. To show the .NET Framework runtime and SDK versions available to you, go to your app in the Azure portal. Select Development Tools > Advanced Tools. Select Go. In Kudu, select Debug console for CMD or PowerShell. Run the appropriate command in the browser-based console:
For CLR 4 runtime versions (.NET Framework 4 and above):
ls "D:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework"Latest .NET Framework version might not be immediately available.
For CLR 2 runtime versions (.NET Framework 3.5 and below):
ls "D:\Program Files (x86)\Reference Assemblies\Microsoft\Framework"If the runtime your application requires isn't supported, you can deploy it with a custom container.
Run the following command in the Cloud Shell:
az webapp config show --resource-group <resource-group-name> --name <app-name> --query netFrameworkVersion
A value of v4.0 means the latest CLR 4 version (.NET Framework 4.x) is used. A value of v2.0 means a CLR 2 version (.NET Framework 3.5) is used.
By default, App Service uses the latest supported .NET Framework version to run your ASP.NET app. To run your app using .NET Framework 3.5 instead, run the following command in the Cloud Shell (v2.0 signifies CLR 2):
az webapp config set --resource-group <resource-group-name> --name <app-name> --net-framework-version v2.0
[!INCLUDE outdated-runtimes]
In App Service, you can set app settings and connection strings outside of your app code. Then you can access them in any class using the standard ASP.NET pattern:
using System.Configuration;
...
// Get an app setting
ConfigurationManager.AppSettings["MySetting"];
// Get a connection string
ConfigurationManager.ConnectionStrings["MyConnection"];
}If you configure an app setting with the same name in App Service and in web.config, the App Service value takes precedence over the web.config value. The local web.config value lets you debug the app locally. The App Service value lets your run the app in product with production settings. Connection strings work in the same way. This way, you can keep your application secrets outside of your code repository and access the appropriate values without changing your code.
Note
Consider more secure connectivity options that don't require connection secrets at all. For more information, see Secure connectivity to Azure services and databases from Azure App Service.
When a Visual Studio solution includes multiple projects, the Visual Studio publish process includes selecting the project to deploy. When you deploy to the App Service deployment engine, such as with Git, or with ZIP deploy with build automation enabled, the App Service deployment engine picks the first Web Site or Web Application Project it finds as the App Service app. You can specify which project App Service should use by specifying the PROJECT app setting. For example, run the following command in the Cloud Shell:
az webapp config appsettings set --resource-group <resource-group-name> --name <app-name> --settings PROJECT="<project-name>/<project-name>.csproj"
When your ASP.NET app generates an exception in the Visual Studio debugger, the browser displays a detailed exception page. A generic error message replaces that page in App Service. To display the detailed exception page in App Service, open the web.config file and add the <customErrors mode="Off"/> element under the <system.web> element. For example:
<system.web>
<customErrors mode="Off"/>
</system.web>Redeploy your app with the updated web.config. You should now see the same detailed exception page.
You can add diagnostic messages in your application code using System.Diagnostics.Trace. For example:
Trace.TraceError("Record not found!"); // Error trace
Trace.TraceWarning("Possible data loss"); // Warning trace
Trace.TraceInformation("GET /Home/Index"); // Information trace[!INCLUDE Access diagnostic logs]