如何在ARM模板中为AppService的appsettings配置动态数组

1. ARM模板侧配置 #

1.1 定义参数与公共变量 #

首先在ARM模板的参数段声明数组类型的覆盖配置参数，同时将固定不需要修改的默认应用设置存入变量：

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "webAppName": {
      "type": "string"
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    // 接收传入的应用设置键值对数组
    "appSettingsOverrides": {
      "type": "array",
      "defaultValue": [],
      "metadata": {
        "description": "App Service自定义应用设置，格式为[{name: '配置名', value: '配置值'}]的数组"
      }
    }
  },
  "variables": {
    // 固定默认应用配置，不需要每次传入
    "defaultAppSettings": [
      {
        "name": "WEBSITE_NODE_DEFAULT_VERSION",
        "value": "~18"
      },
      {
        "name": "ASPNETCORE_ENVIRONMENT",
        "value": "Production"
      }
    ]
  },

1.2 配置App Service资源节点 #

在App Service的siteConfig.appSettings属性中用union函数合并默认配置和传入的自定义配置，避免原有配置被清空：

"resources": [
    {
      "type": "Microsoft.Web/sites",
      "apiVersion": "2022-03-01",
      "name": "[parameters('webAppName')]",
      "location": "[parameters('location')]",
      "properties": {
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', parameters('appServicePlanName'))]",
        "siteConfig": {
          // 合并默认配置与自定义配置，自定义配置优先级更高，同名配置会覆盖默认值
          "appSettings": "[union(variables('defaultAppSettings'), parameters('appSettingsOverrides'))]"
        }
      }
    }
  ]
}

注意：union函数会自动对同名的name属性去重，后面传入的数组元素优先级更高，因此自定义配置可以覆盖默认配置中同名的项

2. YAML侧overrideParameters写法 #

在CI/CD流水线的ARM部署步骤中，按数组格式传入自定义配置即可，支持动态注入流水线变量：

- task: AzureResourceManagerTemplateDeployment@3
  inputs:
    deploymentScope: 'Resource Group'
    azureResourceManagerConnection: '$(serviceConnectionName)'
    subscriptionId: '$(targetSubscriptionId)'
    resourceGroupName: '$(targetResourceGroup)'
    location: '$(deployLocation)'
    csmFile: './webapp-deploy.json'
    overrideParameters: >
      -webAppName '$(webAppName)'
      -appServicePlanName '$(appServicePlanName)'
      -appSettingsOverrides [
        {"name": "Database_ConnectionString", "value": "$(prodDbConnectionString)"},
        {"name": "Storage_AccessKey", "value": "$(blobStorageAccessKey)"},
        {"name": "FeatureFlag_EnableNewPayment", "value": "true"}
      ]

如果你的流水线环境对换行和转义要求严格，可以直接写为单行格式避免解析错误：
overrideParameters: '-webAppName $(webAppName) -appSettingsOverrides [{"name":"Database_ConnectionString","value":"$(prodDbConnectionString)"},{"name":"Storage_AccessKey","value":"$(blobStorageAccessKey)"}]'

常见部署失败原因 #

• 参数类型定义错误：如果将appSettingsOverrides的类型设置为object而非array，ARM会直接抛出类型校验错误
• 未使用union合并配置：直接将appSettings赋值为传入的数组，会清空App Service自动生成的系统配置，导致应用启动异常
• YAML参数转义错误：配置值中包含特殊字符（比如引号、换行）时没有提前转义，或者数组括号前后缺少空格，导致参数解析失败

内容的提问来源于stack exchange，提问作者Gauls