Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
This article explains how to configure common settings for web apps, a mobile back end, or an API app. For Azure Functions, see App settings reference for Azure Functions.
Note
Starting June 1, 2024, newly created App Service apps can generate a unique default hostname that uses the naming convention <app-name>-<random-hash>.<region>.chinacloudsites.cn
. Existing app names remain unchanged. For example:
myapp-ds27dh7271aah175.chinanorth3-01.chinacloudsites.cn
In Azure App Service, app settings are variables passed as environment variables to the application code. The following conditions apply to app settings:
- App setting names can contain only letters, numbers (0-9), periods (.), and underscores (_).
- Special characters in the value of an app setting must be escaped as needed by the target operating system.
For example, to set an environment variable in App Service for Linux with the value "pa$$w0rd\"
, the string for the app setting should be "pa\$\$w0rd\\"
.
For Linux apps and custom containers, App Service passes app settings to the container by using the --env
flag to set the environment variable in the container. In either case, they're injected into your app environment at app startup. When you add, remove, or edit app settings, App Service triggers an app restart.
For ASP.NET and ASP.NET Core developers, configuring app settings in App Service is like configuring them in <appSettings>
in Web.config
or appsettings.json
. The values in App Service override the ones in Web.config
or appsettings.json
. You can keep development settings, such as local MySQL password, in Web.config
or appsettings.json
. You can keep production secrets, such as Azure MySQL database password, safely in App Service. The same code uses your development settings when you debug locally. It uses your production secrets when you deploy it to Azure.
Other language stacks get the app settings as environment variables at runtime. For steps that are specific to each language stack, see:
App settings are always encrypted when they're stored (encrypted at rest).
Note
If you store secrets in app settings, consider using Azure Key Vault references. If your secrets are for connectivity to back-end resources, consider connectivity options that are more secure and that don't require secrets. For more information, see Secure connectivity to Azure services and databases from Azure App Service.
Add or edit an app setting by using az webapp config app settings set:
az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings <setting-name>="<value>"
Replace <setting-name>
with the name of the setting. Replace <value>
with the value to assign to the setting.
Show all settings and their values by using az webapp config appsettings list:
az webapp config appsettings list --resource-group <group-name> --name <app-name>
Remove one or more settings by using az webapp config app settings delete:
az webapp config appsettings delete --resource-group <group-name> --name <app-name> --setting-names {<setting-name1>,<setting-name2>,...}
Run az webapp config app settings set with the name of the JSON file:
az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings "@fileName.json"
Tip
Wrapping the file name with quotation marks is required only in PowerShell.
The necessary file format is a JSON array of settings where the slot setting field is optional. For example:
[
{
"name": "key1",
"slotSetting": false,
"value": "value1"
},
{
"name": "key2",
"value": "value2"
}
]
For convenience, you can save existing settings in a JSON file by using az webapp config appsettings list.
# Save the settings
az webapp config appsettings list --resource-group <group-name> --name <app-name> > settings.json
# Edit the JSON file
...
# Update the app with the JSON file
az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings @settings.json
This section describes how to configure connection strings.
Note
Consider connectivity options that are more secure and that don't require connection secrets. For more information, see Secure connectivity to Azure services and databases from Azure App Service.
For ASP.NET and ASP.NET Core developers, setting connection strings in App Service is like setting them in <connectionStrings>
in Web.config
. The values that you set in App Service override the ones in Web.config
. You can keep development settings, such as a database file, in Web.config
. You can keep production secrets, such as SQL database credentials, safely in App Service. The same code uses your development settings when you debug locally. It uses your production secrets when you deploy it to Azure.
For other language stacks, it's better to use app settings instead. Connection strings require special formatting in the variable keys to access the values.
There's one case where you might want to use connection strings instead of app settings for non-.NET languages. Certain Azure database types are backed up along with the app only if you configure a connection string for the database in your App Service app. For more information, see Create a custom backup. If you don't need this automated backup, use app settings.
At runtime, connection strings are available as environment variables, prefixed with the following connection types:
- SQL Server:
SQLCONNSTR_
- MySQL:
MYSQLCONNSTR_
- Azure SQL:
SQLAZURECONNSTR_
- Custom:
CUSTOMCONNSTR_
- PostgreSQL:
POSTGRESQLCONNSTR_
- Azure Notification Hubs:
NOTIFICATIONHUBCONNSTR_
- Azure Service Bus:
SERVICEBUSCONNSTR_
- Azure Event Hubs:
EVENTHUBCONNSTR_
- Azure Cosmos DB:
DOCDBCONNSTR_
- Redis cache:
REDISCACHECONNSTR_
Note
.NET apps that target PostgreSQL, Notification Hubs, Service Bus, Event Hubs, Azure Cosmos DB, and Redis cache should set the connection string to Custom as a workaround for a known issue in .NET EnvironmentVariablesConfigurationProvider.
For example, a MySQL connection string named connectionstring1 can be accessed as the environment variable MYSQLCONNSTR_connectionString1
. For steps that are specific to each language stack, see:
Connection strings are always encrypted when they're stored (encrypted at rest).
Note
You can also resolve connection strings from Key Vault by using Key Vault references.
Add or edit an app setting by using az webapp config connection-string set:
az webapp config connection-string set --resource-group <group-name> --name <app-name> --connection-string-type <type> --settings <string-name>='<value>'
Replace <string-name>
with the name of the connection string. Replace <value>
with the value to assign to the connection string. For possible values of <type>
such as SQLAzure
, see the CLI command documentation.
Show all connection strings and their values by using az webapp config connection-string list:
az webapp config connection-string list --resource-group <group-name> --name <app-name>
Remove one or more connection strings by using az webapp config connection-string delete:
az webapp config connection-string delete --resource-group <group-name> --name <app-name>--setting-names {<string-name1>,<string-name2>,...}
Run az webapp config connection-string set with the name of the JSON file:
az webapp config connection-string set --resource-group <group-name> --name <app-name> --settings "@fileName.json"
Tip
Wrapping the file name with quotation marks is required only in PowerShell.
The necessary file format is a JSON array of connection strings where the slot setting field is optional. For example:
[
{
"name": "name-1",
"value": "conn-string-1",
"type": "SQLServer",
"slotSetting": false
},
{
"name": "name-2",
"value": "conn-string-2",
"type": "PostgreSQL",
},
...
]
For convenience, you can save existing connection strings in a JSON file by using az webapp config connection-string list.
# Save the connection strings
az webapp config connection-string list --resource-group <group-name> --name <app-name> > settings.json
# Edit the JSON file
...
# Update the app with the JSON file
az webapp config connection-string set --resource-group <group-name> --name <app-name> --settings @settings.json
To configure language stack settings, see these resources:
To configure general settings, follow the steps for your preferred tools.
You can set many of the common configurable options by using az webapp config set. The following example shows a subset of the configurable options:
az webapp config set --resource-group <group-name> --name <app-name> --use-32bit-worker-process [true|false] --web-sockets-enabled [true|false] --always-on [true|false]--http20-enabled --auto-heal-enabled [true|false] --remote-debugging-enabled [true|false] --number-of-workers
To show the existing settings, use the az webapp config show command.
The default document is the webpage that appears at the root URL of an App Service app. The first matching file in the list is used. If the app uses modules that route based on URL instead of serving static content, there's no need for default documents.
The setting to configure default documents is only for Windows apps.
Add a default document by using az resource update:
az resource update --resource-group <group-name> --resource-type "Microsoft.Web/sites/config" --name <app-name>/config/web --add properties.defaultDocuments <filename>
By default, App Service starts your app from the root directory of your app code. But certain web frameworks don't start in the root directory. For example, Laravel starts in the public
subdirectory. Such an app would be accessible at http://contoso.com/public
, for example, but you typically want to direct http://contoso.com
to the public
directory instead. If your app's startup file is in a different folder, or if your repository has more than one application, you can edit or add virtual applications and directories.
The feature of mapping a virtual directory to a physical path is available only on Windows apps.
The following example sets the root path /
to the public
subdirectory, which works for Laravel. It also adds a second virtual application at the /app2
path. To run it, create a file called json.txt
with the following contents:
[
{
"physicalPath"':' "site\\wwwroot\\public",
"preloadEnabled"':' false,
"virtualDirectories"':' null,
"virtualPath"':' "/"
},
{
"physicalPath"':' "site\\wwwroot\\app2",
"preloadEnabled"':' false,
"virtualDirectories"':' null,
"virtualPath"':' "/app2"
}
]
Change <group-name>
and <app-name>
for your resources and run the following command. Be aware of escape characters when you run this command. For more information on escape characters, see Tips for using the Azure CLI successfully.
az resource update --resource-group <group-name> --resource-type Microsoft.Web/sites/config --name <app-name>/config/web --set properties.virtualApplications="@json.txt"
For Windows apps, you can customize the IIS handler mappings and virtual applications and directories. Handler mappings let you add custom script processors to handle requests for specific file extensions.
To add a custom handler:
In the Azure portal, search for and select App Services, and then select your app.
On the app's left menu, select Settings > Configuration. Then select Path mappings.
Select New handler mapping. Configure the handler as follows:
- Extension. The file extension that you want to handle, such as
*.php
orhandler.fcgi
. - Script processor. The absolute path of the script processor to you. The script processor processes requests to files that match the file extension. Use the path
D:\home\site\wwwroot
to refer to your app's root directory. - Arguments. Optional command-line arguments for the script processor.
- Extension. The file extension that you want to handle, such as
Select Ok. Then select Save on the Configuration page.
- Configure a custom container for Azure App Service
- Mount Azure Storage as a local share in App Service
- Environment variables and app settings in Azure App Service
- Set up an existing custom domain in Azure App Service
- Set up staging environments in Azure App Service
- Enable HTTPS for a custom domain in Azure App Service
- Enable diagnostics logging for apps in Azure App Service
- Scale up an app in Azure App Service
- Azure App Service quotas and alerts
- Change applicationHost.config settings with applicationHost.xdt