dotnet-env: .NET 开发的环境变量加载工具

在开发过程中，我们经常需要使用环境变量来配置应用程序,dotnet-env 是一个 .NET 库，它可以从 .env 文件中加载环境变量。 这个库支持 .NET Core 和 .NET Framework（4.6 及以上版本）。

安装方法

你可以通过两种方式安装 dotnet-env：

• • 在 Visual Studio 的包管理器控制台中运行命令：

  PM> Install-Package DotNetEnv

• • 在 .NET CLI 中运行命令：

  dotnet add package DotNetEnv

基本用法

加载 .env 文件

默认情况下，Load() 方法会在当前目录查找 .env 文件：

DotNetEnv.Env.Load();

如果想让程序向上级目录查找 .env 文件，可以使用 TraversePath() 方法：

DotNetEnv.Env.TraversePath().Load();

你也可以指定 .env 文件的路径：

DotNetEnv.Env.Load("./path/to/.env");

除了文件路径，还可以从流或字符串中加载内容：

using (var stream = File.OpenRead("./path/to/.env")) {
    DotNetEnv.Env.Load(stream);
}

DotNetEnv.Env.LoadContents("OK=GOOD\nTEST=\"more stuff\"");

如果有多个 .env 文件，可以用 LoadMulti() 按顺序加载：

DotNetEnv.Env.LoadMulti(new[] { ".env", ".env2" });

注意：后面的文件中的变量会覆盖前面的值。
如果你不希望这样，可以使用 NoClobber() 方法。

---

访问环境变量

加载完成后，可以通过以下方式访问环境变量：

• • 使用 .NET 内置的方法：

  System.Environment.GetEnvironmentVariable("IP");

• • 或者使用 dotnet-env 提供的方法：

  DotNetEnv.Env.GetString("A_STRING");
  DotNetEnv.Env.GetBool("A_BOOL");
  DotNetEnv.Env.GetInt("AN_INT");
  DotNetEnv.Env.GetDouble("A_DOUBLE");

这些方法还支持设置默认值：

DotNetEnv.Env.GetString("THIS_DOES_NOT_EXIST", "未找到变量");

---

高级设置

你可以通过 LoadOptions 来控制加载行为：

new DotNetEnv.LoadOptions(
    setEnvVars: true,
    clobberExistingVars: true,
    onlyExactPath: true
)

推荐使用链式调用语法来设置选项：

DotNetEnv.Env.NoEnvVars().NoClobber().TraversePath().Load();

参数说明：

1. 1. setEnvVars：是否将 .env 中的变量写入系统环境变量。

• • 默认为 true

• • 设置为 false 时，只读取变量，不会修改系统环境变量。

• 2. clobberExistingVars：是否覆盖已有的环境变量。

• • • 默认为 true

  • • 设置为 false 时，保留已有环境变量。

• 3. onlyExactPath：是否仅在指定路径查找 .env 文件。

• • • 默认为 false

  • • 设置为 true 时，不会向上级目录查找。

  ---

  集成到 ConfigurationBuilder

  dotnet-env 可以轻松集成到 .NET 的 ConfigurationBuilder 中：

  var configuration = new ConfigurationBuilder()
      .AddDotNetEnv(".env", LoadOptions.TraversePath())
      .Build();

  该功能会将 __ 解析为 :，从而支持嵌套结构：

  APP__PORT=5000

  对应 C# 中的访问方式：

  configuration["APP:PORT"]; // 返回 "5000"

  ---

  .env 文件格式说明

  .env 文件的格式简单易懂。

  简单赋值

  KEY=value

  支持的导出关键字

  export KEY="value"
  set KEY=value
  SET KEY=value
  set -x KEY=value

  插值语法

  KEY=${ENVVAR:-default}      # 如果 ENVVAR 不存在，则使用 default
  KEY=${ENVVAR?error}         # 如果 ENVVAR 不存在，则返回 error
  KEY=${ENVVAR:+alternative}  # 如果 ENVVAR 存在，则使用 alternative

  多行值

  KEY="value
  and more"

  Unicode 字符

  UTF8_BYTES="\xF0\x9F\x9A\x80"  # 🚀
  UTF16_BYTES="\uae"             # ®

  ---

  使用建议

  • • 不要在生产环境中使用 .env 文件。
    这个工具主要用于本地开发。

  • • 生产环境应直接使用系统环境变量。

  • • .env 文件应存储在安全的地方，例如 1Password、LastPass 或 S3。
    团队成员可以下载一份用于本地开发。

  • • 环境变量应在程序启动时一次性加载。
    不要在程序运行期间多次读取。

  ---

  总结

  dotnet-env 是一个简单好用的工具。
  它可以帮你快速加载 .env 文件中的变量。
  无论你是开发 Web 应用、微服务还是控制台程序，都可以使用它。

  现在就去试试吧！🚀

  GitHub 地址：https://github.com/tonerdo/dotnet-env

  ---

  如果你觉得这篇文章对你有帮助，欢迎点赞、收藏并分享给更多开发者！让我们一起学习，共同进步！