Skip to content

Latest commit

 

History

History
626 lines (434 loc) · 29.9 KB

configure-common.md

File metadata and controls

626 lines (434 loc) · 29.9 KB
title description keywords ms.assetid ms.topic ms.date ms.custom ms.devlang author ms.author
Configure apps
Learn to configure common settings for an App Service app. App settings, app config, connection strings, platform, language stack, container, etc.
azure app service, web app, app settings, environment variables
9af8a367-7d39-4399-9941-b80cbc5f39a0
article
10/03/2024
devx-track-csharp, devx-track-azurecli, devx-track-azurepowershell, AppServiceConnectivity
azurecli
cephalin
cephalin

Configure an App Service app

[!INCLUDE regionalization-note]

This article explains how to configure common settings for web apps, mobile back end, or API app. For Azure Functions, see App settings reference for Azure Functions.

Configure app settings

Note

  • App settings names can only contain letters, numbers (0-9), periods ("."), and underscores ("_")
  • Special characters in the value of an App Setting must be escaped as needed by the target OS

For example to set an environment variable in App Service Linux with the value "pa$$w0rd\" the string for the app setting should be: "pa\$\$w0rd\\"

In App Service, app settings are variables passed as environment variables to the application code. For Linux apps and custom containers, App Service passes app settings to the container 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, setting app settings in App Service are like setting them in <appSettings> in Web.config or appsettings.json, but the values in App Service override the ones in Web.config or appsettings.json. You can keep development settings (for example, local MySQL password) in Web.config or appsettings.json and production secrets (for example, Azure MySQL database password) safely in App Service. The same code uses your development settings when you debug locally, and it uses your production secrets when deployed to Azure.

Other language stacks, likewise, get the app settings as environment variables at runtime. For language-stack specific steps, see:

App settings are always encrypted when stored (encrypted-at-rest).

Note

If you store secrets in app settings, consider using Key Vault references. If your secrets are for connectivity to back-end resources, consider more secure connectivity options that don't require secrets at all. For more information, see Secure connectivity to Azure services and databases from Azure App Service.

Azure portal

  1. In the Azure portal, search for and select App Services, and then select your app.

    Search for App Services

  2. In the app's left menu, select Environment variables > App settings.

    Screenshot showing how to navigate to the App Settings page.

    By default, values for app settings are hidden in the portal for security. To see a hidden value of an app setting, select its Value field. To see the hidden values of all app settings, select the Show values button.

  3. To add a new app setting, select Add. To edit a setting, click the setting.

  4. In the dialog, you can stick the setting to the current slot.

    [!NOTE] In a default Linux app service or a custom Linux container, any nested JSON key structure in the app setting name like ApplicationInsights:InstrumentationKey needs to be configured in App Service as ApplicationInsights__InstrumentationKey for the key name. In other words, any : should be replaced by __ (double underscore). Any periods in the app setting name will be replaced with a _ (single underscore).

  5. When finished, select Apply. Don't forget to select Apply back in the Environment variables page.

Azure CLI

Add or edit an app setting with az webapp config app settings set:

az webapp config appsettings set --name <app-name> --resource-group <group-name> --settings <setting-name>="<value>"

Replace <setting-name> with the name of the setting, and <value> with the value to assign to it.

Show all settings and their values with az webapp config appsettings list:

az webapp config appsettings list --name <app-name> --resource-group <group-name>

Remove one or more settings with az webapp config app settings delete:

az webapp config appsettings delete --name <app-name> --resource-group <group-name> --setting-names {<setting-name1>,<setting-name2>,...}

Azure PowerShell

Set one or more app settings with Set-AzWebApp:

Set-AzWebApp -ResourceGroupName <group-name> -Name <app-name> -AppSettings @{"<setting-name1>"="<value1>"; "<setting-name2>"="<value2>";...}

This cmdlet replaces the entire set of app settings with the ones you specify. To add or edit an app setting within an existing set, include the existing app settings in your input Hashtable by using the Get-AzWebApp cmdlet. For example:

# Get app configuration
$webapp=Get-AzWebApp -ResourceGroupName <group-name> -Name <app-name>

# Copy app settings to a new Hashtable
$appSettings = @{}
ForEach ($item in $webapp.SiteConfig.AppSettings) {
$appSettings[$item.Name] = $item.Value
}

# Add or edit one or more app settings
$appSettings['<setting-name1>'] = '<value1>'
$appSettings['<setting-name2>'] = '<value2>'

# Save changes
Set-AzWebApp -ResourceGroupName <group-name> -Name <app-name> -AppSettings $appSettings

To check if an app setting is slot-specific, use Get-AzWebAppSlotConfigName:

Get-AzWebAppSlotConfigName -ResourceGroupName <group-name> -Name <app-name> | select AppSettingNames

To make one or more app settings slot-specific, use Set-AzWebAppSlotConfigName:

Set-AzWebAppSlotConfigName -ResourceGroupName <group-name> -Name <app-name> -AppSettingNames <setting-name1>,<setting-name2>,...

Edit app settings in bulk

Azure portal

Select the Advanced edit button. Edit the settings in the text area. When finished, select OK. Don't forget to select Apply back in the Environment variables page.

App settings have the following JSON formatting:

[
  {
    "name": "<key-1>",
    "value": "<value-1>",
    "slotSetting": false
  },
  {
    "name": "<key-2>",
    "value": "<value-2>",
    "slotSetting": false
  },
  ...
]

Azure CLI

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 quotes is only required in PowerShell.

The file format needed 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 into a JSON file with az webapp config appsettings list. The following example can be run in Bash.

# Save the settings
az webapp config appsettings list --name <app-name> --resource-group <group-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

Azure PowerShell

It's not possible to edit app settings in bulk by using a JSON file with Azure PowerShell.

Configure connection strings

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.

For ASP.NET and ASP.NET Core developers, setting connection strings in App Service are like setting them in <connectionStrings> in Web.config, but the values you set in App Service override the ones in Web.config. You can keep development settings (for example, a database file) in Web.config and production secrets (for example, SQL Database credentials) safely in App Service. The same code uses your development settings when you debug locally, and it uses your production secrets when deployed to Azure.

For other language stacks, it's better to use app settings instead, because connection strings require special formatting in the variable keys in order to access the values.

Note

There is one case where you may 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, then use app settings.

At runtime, connection strings are available as environment variables, prefixed with the following connection types:

  • SQLServer: SQLCONNSTR_
  • MySQL: MYSQLCONNSTR_
  • SQLAzure: SQLAZURECONNSTR_
  • Custom: CUSTOMCONNSTR_
  • PostgreSQL: POSTGRESQLCONNSTR_
  • Notification Hub: NOTIFICATIONHUBCONNSTR_
  • Service Bus: SERVICEBUSCONNSTR_
  • Event Hub: EVENTHUBCONNSTR_
  • Document DB: DOCDBCONNSTR_
  • Redis Cache: REDISCACHECONNSTR_

Note

.NET apps targeting PostgreSQL, Notification Hub, Service Bus, Event Hub, Document Db and Redis Cache should set the connection string to Custom as 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 language-stack specific steps, see:

Connection strings are always encrypted when stored (encrypted-at-rest).

Note

Connection strings can also be resolved from Key Vault using Key Vault references.

Azure portal

  1. In the Azure portal, search for and select App Services, and then select your app.

    Search for App Services

  2. In the app's left menu, select Environment variables > Connection strings.

    Screenshot showing UI open to Connection strings.

    By default, values for connection strings are hidden in the portal for security. To see a hidden value of a connection string, select its Value field. To see the hidden values of all connection strings, select the Show value button.

  3. To add a new connection string, select Add. To edit a connection string, select the connection string.

  4. In the dialog, you can stick the connection string to the current slot.

  5. When finished, select Apply. Don't forget to select Apply back in the Environment variables page.

Azure CLI

Add or edit an app setting with az webapp config connection-string set:

az webapp config connection-string set --name <app-name> --resource-group <group-name> --connection-string-type <type> --settings <string-name>='<value>'

Replace <string-name> with the name of the connection string, and <value> with the value to assign to it. For possible values of <type> (for example, SQLAzure), see the CLI command documentation.

Show all connection strings and their values with az webapp config connection-string list:

az webapp config connection-string list --name <app-name> --resource-group <group-name>

Remove one or more connection strings with az webapp config connection-string delete:

az webapp config connection-string delete --name <app-name> --resource-group <group-name> --setting-names {<string-name1>,<string-name2>,...}

Azure PowerShell

Set one or more connection strings with Set-AzWebApp:

$PropertiesObject = @{
  "<string-name1>" = @{
    value="<connection-string1>";
    type="<type>"};
  "<string-name2>" = @{
    value="<connection-string2>";
    type="<type>"}
}

Set-AzWebApp -ResourceGroupName <group-name> -Name <app-name> -ConnectionStrings $PropertiesObject

Each connection string contains a name (<string-name1>), a value (<connection-string1>), and the type, which is a numerical value that corresponds to one of the ConnectionStringType enum fields. For example, For SQL Azure, specify type="2".

This cmdlet replaces the entire set of connection strings with the ones you specify. To add or edit an app setting within an existing set, include the existing app settings in your input hashtable by using the Get-AzWebApp cmdlet. For example:

# Get app configuration
$webapp=Get-AzWebApp -ResourceGroupName <group-name> -Name <app-name>

# Copy connection strings to a new hashtable
$connStrings = @{}
ForEach ($item in $webapp.SiteConfig.ConnectionStrings) {
    $connStrings[$item.Name] = @{value=$item.ConnectionString; type=$item.Type.ToString()}
}

# Add or edit one or more connection strings
$connStrings['<string-name1>'] = @{value='<connection-string1>', type='<type>'}
$connStrings['<string-name2>'] = @{value='<connection-string2>', type='<type>'}

# Save changes
Set-AzWebApp -ResourceGroupName <group-name> -Name <app-name> -ConnectionStrings $connStrings

To check if a connection string is slot-specific, use Get-AzWebAppSlotConfigName:

Get-AzWebAppSlotConfigName -ResourceGroupName <group-name> -Name <app-name> | select ConnectionStringNames

To make one or more connection strings slot-specific, use Set-AzWebAppSlotConfigName:

Set-AzWebAppSlotConfigName -ResourceGroupName <group-name> -Name <app-name> -ConnectionStringNames <string-name1>,<string-name2>,...

Edit connection strings in bulk

Azure portal

Select the Advanced edit button. Edit the connection strings in the text area. When finished, select Apply. Don't forget to select Apply back in the Environment variables page.

Connection strings have the following JSON formatting:

[
  {
    "name": "name-1",
    "value": "conn-string-1",
    "type": "SQLServer",
    "slotSetting": false
  },
  {
    "name": "name-2",
    "value": "conn-string-2",
    "type": "PostgreSQL",
    "slotSetting": false
  },
  ...
]

Azure CLI

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 quotes is only required in PowerShell.

The file format needed 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 into a JSON file with az webapp config connection-string list. The following example can be run in Bash.

# 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

Azure PowerShell

It's not possible to edit connection strings in bulk by using a JSON file with Azure PowerShell.

Configure language stack settings

Configure general settings

Azure portal

In the Azure portal, search for and select App Services, and then select your app. In the app's left menu, select Configuration > General settings.

General settings

Here, you can configure some common settings for the app. Some settings require you to scale up to higher pricing tiers.

  • Stack settings: The software stack to run the app, including the language and SDK versions.

    For Linux apps, you can select the language runtime version and set an optional Startup command or a startup command file.

    General settings for Linux containers

  • Platform settings: Lets you configure settings for the hosting platform, including:

    • Platform bitness: 32-bit or 64-bit. For Windows apps only.
    • FTP state: Allow only FTPS or disable FTP altogether.
    • HTTP version: Set to 2.0 to enable support for HTTPS/2 protocol.

    [!NOTE] Most modern browsers support HTTP/2 protocol over TLS only, while non-encrypted traffic continues to use HTTP/1.1. To ensure that client browsers connect to your app with HTTP/2, secure your custom DNS name. For more information, see Secure a custom DNS name with a TLS/SSL binding in Azure App Service.

    • Web sockets: For ASP.NET SignalR or socket.io, for example.

    • Always On: Keeps the app loaded even when there's no traffic. When Always On isn't turned on (default), the app is unloaded after 20 minutes without any incoming requests. The unloaded app can cause high latency for new requests because of its warm-up time. When Always On is turned on, the front-end load balancer sends a GET request to the application root every five minutes. It's important to ensure this request receives a 200 OK response to ensure any re-imaging operations are performed correctly. The continuous ping prevents the app from being unloaded.

      Always On is required for continuous WebJobs or for WebJobs that are triggered using a CRON expression.

    • Session affinity: In a multi-instance deployment, ensure that the client is routed to the same instance for the life of the session. You can set this option to Off for stateless applications.

    • Session affinity proxy: Session affinity proxy can be turned on if your app is behind a reverse proxy (like Azure Application Gateway or Azure Front Door) and you are using the default host name. The domain for the session affinity cookie will align with the forwarded host name from the reverse proxy.

    • HTTPS Only: When enabled, all HTTP traffic is redirected to HTTPS.

    • Minimum TLS version: Select the minimum TLS encryption version required by your app.

  • Debugging: Enable remote debugging for ASP.NET, ASP.NET Core, or Node.js apps. This option turns off automatically after 48 hours.

  • Incoming client certificates: require client certificates in mutual authentication.

Azure CLI

You can set many of the common configurable options 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.

Azure PowerShell

You can set many of the common configurable options using Set-AzWebApp. The following example shows a subset of the configurable options.

Set-AzWebApp -ResourceGroupName <group-name> -Name <app-name> -Use32BitWorkerProcess [True|False] -WebSocketsEnabled [True|False] -AlwaysOn [True|False] -NumberOfWorkers

To show the existing settings, use the Get-AzWebApp command.

Configure default documents

This setting is only for Windows apps.

The default document is the web page that's displayed 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.

Azure portal

  1. In the Azure portal, search for and select App Services, and then select your app.

  2. In the app's left menu, select Configuration > Default documents.

    Default documents

  3. To add a default document, select New document. To remove a default document, select Delete to its right.

Azure CLI

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>

Azure PowerShell

Add a default document by modifying the updating app's PowerShell object:

$webapp = Get-AzWebApp -ResourceGroupName <group-name> -Name <app-name>
$webapp.SiteConfig.DefaultDocuments.Add("<filename>")
Set-AzWebApp $webapp

Map a URL path to a directory

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.

Important

Virtual directory to a physical path feature is only available on Windows apps.

Azure portal

  1. In the Azure portal, search for and select App Services, and then select your app.

  2. In the app's left menu, select Configuration > Path mappings

  3. Select New virtual application or directory.

    • To map a virtual directory to a physical path, leave the Directory check box selected. Specify the virtual directory and the corresponding relative (physical) path to the website root (D:\home).
    • To mark a virtual directory as a web application, clear the Directory check box.

    Directory check box

  4. Select OK. Don't forget to select Save in the Configuration page.

Azure CLI

The following example sets the root path / to the public subdirectory (which works for Laravel), and 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 running 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"

Azure PowerShell

The following example sets the root path / to the public subdirectory (which works for Laravel), and also adds a second virtual application at the /app2 path. To run it, change <group-name> and <app-name>.

$webapp=Get-AzWebApp -ResourceGroupName <group-name> -Name <app-name>

# Set default / path to public subdirectory
$webapp.SiteConfig.VirtualApplications[0].PhysicalPath= "site\wwwroot\public"

# Add a virtual application
$virtualApp = New-Object Microsoft.Azure.Management.WebSites.Models.VirtualApplication
$virtualApp.VirtualPath = "/app2"
$virtualApp.PhysicalPath = "site\wwwroot\app2"
$virtualApp.PreloadEnabled = $false
$webapp.SiteConfig.VirtualApplications.Add($virtualApp)

# Save settings
Set-AzWebApp $webapp

Configure handler mappings

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:

  1. In the Azure portal, search for and select App Services, and then select your app.

  2. In the app's left menu, select Configuration > Path mappings.

    Path mappings

  3. Select New handler mapping. Configure the handler as follows:

    • Extension. The file extension you want to handle, such as *.php or handler.fcgi.
    • Script processor. The absolute path of the script processor to you. Requests to files that match the file extension are processed by the script processor. Use the path D:\home\site\wwwroot to refer to your app's root directory.
    • Arguments. Optional command-line arguments for the script processor.

  4. Select OK. Don't forget to select Save in the Configuration page.

Configure custom containers

Next steps