隔离式.NET8函数应用中local.settings.json无法解析Azure App Configuration引用

核心原因 #

Azure App Configuration的应用设置引用语法（@Microsoft.AppConfiguration(Endpoint=<myendpoint>; Key=<mykey>;)）仅由Azure托管环境的平台层自动解析，本地运行Azure Functions时，宿主程序不会处理该语法，因此直接返回原始字符串是预期行为。

本地调试解决方法 #

• 方法1：直接替换为实际配置值
  编辑local.settings.json，将带有引用语法的配置项直接替换为App Configuration中的真实值，例如：

  {
    "Values": {
      "MyTargetSetting": "真实的配置值内容"
    }
  }
  

  优势是快速简单，适合临时调试；缺点是配置变更时需手动同步。

• 方法2：通过SDK手动解析引用
  在函数启动逻辑中，利用Azure App Configuration SDK主动解析引用并加载真实值，保持和Azure环境行为一致：

  var host = new HostBuilder()
      .ConfigureFunctionsWorkerDefaults()
      .ConfigureAppConfiguration((context, configBuilder) =>
      {
          var currentConfig = configBuilder.Build();
          var configRef = currentConfig["MyTargetSetting"];
  
          // 判断是否为App Configuration引用格式
          if (!string.IsNullOrWhiteSpace(configRef) && configRef.StartsWith("@Microsoft.AppConfiguration("))
          {
              // 提取Endpoint和Key参数
              var refContent = configRef.TrimStart('@').Replace("Microsoft.AppConfiguration(", "").TrimEnd(')');
              var parameters = refContent.Split(';', StringSplitOptions.RemoveEmptyEntries)
                                         .ToDictionary(p => p.Split('=')[0].Trim(), p => p.Split('=')[1].Trim());
  
              // 添加App Configuration配置源
              configBuilder.AddAzureAppConfiguration(options =>
              {
                  options.Connect(new Uri(parameters["Endpoint"]))
                         .Select(parameters["Key"]);
              });
          }
      })
      .Build();
  
  host.Run();
  

  这种方式无需修改local.settings.json，自动同步云端配置值，适合长期开发调试。

• 方法3：升级Azure Functions Core Tools
  确保安装最新版的Azure Functions Core Tools，部分新版本对App Configuration的本地集成有优化，但核心仍需依赖上述手动解析逻辑，因为平台级解析仅在Azure托管环境生效。

补充说明 #

你提到通过IConfigurationRoot能正常解析值，是因为该方式是直接通过SDK连接Azure App Configuration读取数据，属于常规的配置加载流程；而应用设置引用语法是Azure平台提供的注入机制，本地宿主未实现该解析逻辑，因此两种场景存在差异。

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