ASP.NET Core如何从单个环境变量绑定完整Options对象？

场景背景 #

现有Options模型：

public class MyOptions
{
    public required int Option1 { get; init; }
    public required string Option2 { get; init; }
}

常见的配置绑定方式：

1. 从appsettings.json绑定完整对象：

// builder 为 IHostApplicationBuilder
var options = builder.BindOptions<MyOptions>("MyOptions");

2. 拆分属性设置环境变量：

MyOptions__Option1=1
MyOptions__Option2=hello

问题 #

在ASP.NET Core中，是否有开箱即用的方法，通过单个环境变量绑定整个Options对象？比如使用这种形式的环境变量：

MyOptions={ "Option1": 1, "Option2": "hello" }

如果存在，需要用什么语法设置变量值？（已知可自定义配置提供器）

回答 #

ASP.NET Core 配置系统原生支持通过单个环境变量绑定完整Options对象，核心是利用其内置的JSON格式值解析能力。

语法规则 #

只需将Options对象的JSON序列化字符串作为环境变量的值，变量名对应配置节点名称（如MyOptions），根据操作系统终端的不同，需要注意转义处理：

• Windows CMD：用双引号包裹整个JSON值，内部双引号需转义为\"：

  MyOptions="{ \"Option1\": 1, \"Option2\": \"hello\" }"
  

• Windows PowerShell：两种方式可选：

  # 方式1：单引号包裹，内部双引号无需转义
  $env:MyOptions='{ "Option1": 1, "Option2": "hello" }'
  # 方式2：双引号包裹，内部双引号转义为`"
  $env:MyOptions="{ `"Option1`": 1, `"Option2`": `"hello`" }"
  

• Linux/macOS bash/zsh：两种方式可选：

  # 方式1：单引号包裹，内部双引号无需转义
  export MyOptions='{ "Option1": 1, "Option2": "hello" }'
  # 方式2：双引号包裹，内部双引号转义为\"
  export MyOptions="{ \"Option1\": 1, \"Option2\": \"hello\" }"
  

验证方法 #

配置完成后，依然可以使用原有的BindOptions方法绑定，配置系统会自动解析JSON字符串并映射到Options对象：

var options = builder.BindOptions<MyOptions>("MyOptions");
// 此时 options.Option1 = 1，options.Option2 = "hello"

注意事项 #

• 若同时存在单个JSON格式的环境变量和拆分属性的环境变量（如MyOptions__Option1），拆分属性的变量会覆盖JSON中的对应值——因为环境变量配置提供器的优先级高于JSON配置（默认优先级：环境变量 > 命令行参数 > appsettings.json等）。
• 必须保证JSON字符串格式有效，格式错误会导致绑定失败并抛出异常，可通过配置系统日志排查问题。

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