为什么

dotnet-config（或.netconfig）为.NET Core工具提供了一个统一的机制，以便以可预测的格式存储和读取配置值，这些值可以通过命令行工具、API以及用户通过任何文本编辑器手动操纵。

就像git config为所有 git 命令提供了一个统一的存储设置方式一样，dotnet-config的目标是在所有 .NET 工具之间保持一致性的水平。格式也与它（主要）兼容，因此利用了 git 社区关于配置任意工具的学习。

这是什么

dotnet-config提供以下功能：

• 任何文本编辑器都可以手工编辑的良好文档文件格式。
• 一个 .NET 全局工具，用于管理配置文件（类似于 git config）。
• 为 dotnet 工具作者提供的 API，用于读取/写入设置。

默认情况下，配置文件命名为 .netconfig，并支持四种存储级别

• 本地：旁边的 .netconfig.user 文件与 Default 级别。
• 默认：当前目录及其任何祖先目录。
• 全局：用户个人资料目录，来自 System.Environment.SpecialFolder.UserProfile。
• 系统：系统级目录，来自 System.Environment.SpecialFolder.System。

文件将按上述顺序读取，首先找到的值具有优先权。当读取多个值时，将返回所有文件的键的所有值。

.netconfig.user 可以用来将仅限于本地的设置在源控制中与团队设置分开，并且它已经在 .gitignore 中被广泛忽略。

谁

以下是一些利用 .netconfig 提供灵活配置持久性选项的工具

在我们文档网站的 Who 部分了解更多有关各种工具如何利用 .netconfig 的信息。

如何

格式

示例文件

# .netconfig is awesome: https://dotnetconfig.org

[serve]
	port = 8080
	gzip                    #shorthand for gzip=true

[vs "alias"]
	comexp = run|community|exp
	preexp = run|preview|exp

[file]
	# example of multi-valued variables
	url = https://github.com/dotnet/runtime/tree/master/docs/design/features
	url = https://github.com/dotnet/aspnetcore/tree/master/docs

; subsections allow grouping variables
[file "docs/design/features/code-versioning.md"]
	url = https://github.com/dotnet/runtime/blob/master/docs/design/features/code-versioning.md
	etag = 7405567...

[file "docs/APIReviewProcess.md"]
	url = https://github.com/dotnet/aspnetcore/blob/master/docs/APIReviewProcess.md
	etag = 1e4acd7...

[mytool]
    description = "\t tab and \n newline escapes, plus \\ backslash are valid"
    title = My tool is great    # internal whitespace preserved without needing double quotes
    path = C:\\tool             # backslashes always escaped, inside or outside double quotes
    size = 500kb                # numbers can have a multiplier (case insensitive) suffix kb, mb, gb, tb 
    max-size = 1T               # the 'b' is optional.
    compress = true             # multiple variants for boolean: true|false|yes|no|on|off|1|0
    secure   = yes
    localized = off
    enabled  = 1

; array like syntax for complex objects
[myArray "0"] # indecies must be unique
    description = 1st item description
    name = Fero
[myArray "1"]
    description = 2nd item description
    name = Jozo

语法与 git-config 语法 非常相似。字符 # 和 ; 开始直到行尾的注释，空白行被忽略。

文件由 部分 和 变量 组成。一个部分以方括号中的部分名为开头，直到下一个部分开始。部分名不区分大小写。部分名中只允许使用字母数字字符和 -。每个变量必须属于某个部分，这意味着在变量的第一个设置之前必须有一个部分标题。

部分可以进一步分为 子部分。要开始一个子部分，将在部分标题中将其名称放入双引号中，并与部分名称用空格分隔，例如下面的示例。

[section "subsection"]

子部分名区分大小写，可以包含任何字符，但不能包含换行符。双引号 " 和反斜杠 \ 可以通过分别作为 \" 和 \\ 转义来包含。

部分标题不能跨越多行。变量可以直接属于一个部分或一个特定的子部分。如果您已经有了 [section "subsection"]，则可以省略 [section]，但如果要包含子部分，则不需要省略。

所有其他行都被识别为 变量 的设置，形式为 名称 = 值（或仅 名称，它是布尔值 true 的快捷方式）。变量名不区分大小写，仅允许字母数字字符和 -，必须以字母开头。变量可以出现多次；我们说变量是 多值的。

在 名称 = 之后的前导空白，第一行注释字符 # 或 ; 之后的行剩余部分，以及行的尾随空白被丢弃，除非它们被双引号包围。值内部保留的空白以原始形式保留。

反斜杠 \ 字符必须始终使用 \\ 转义。双引号必须通过 \" 转义或正确配对，这将在内部保留空白。

除了 \" 和 \\ 之外，还认可 \n（换行符 NL）和 \t（水平制表符 HT, TAB）转义序列。

注意：当使用 CLI 或 API 时，这些转义规则将自动应用

值

许多变量的值被处理为简单的字符串，但有一些变量接受特定类型的值，存在关于如何拼写的规则。

• 布尔值

  当变量提到要接受一个 布尔值 时，许多同义词都接受 true 和 false；这些都不区分大小写。

  • true：布尔值的真文字是 yes、on、true、1。此外，未定义 =<值> 的变量被视为 true。

  • false：布尔值的假文字是 no、off、false、0 以及空字符串。

• 日期时间

  此类型的变量始终使用ISO 8601格式（或圆旅行格式）解析/写入。

• 数字

  对于表示各种大小的许多变量的值，可以用k、M、G或T后缀来表示“将数字乘以1024”、“乘以1024x1024”、“乘以1024x1024x1024”或“乘以1024x1024x1024x1024”分别。后缀的大小写不敏感，也可以包括b，如kb或MB。

复杂对象的数组

通过子节，可以在数组中创建更复杂的对象。假设我们有以下配置对象

public class WatchedProcess
{
    public string Name { get; set; }
    public string ApplicationPath { get; set; }
}

我们希望将配置作为IList<WatchedProcess>检索出来。即使git-config语法没有直接支持这种情况，我们也能通过子节和ConfigurationRoot来创建复杂对象的列表。

ConfigurationRoot支持通过使用项目索引作为“子节”创建数组来处理数组。这使得我们可以创建一个选择器，它会根据元素索引从数组中选取值。例如，WatchedProcess:0:Name会选择数组的第一个项目中的Name值。这意味着我们可以在子节中使用索引，并按如下方式创建复杂对象的数组

[WatchedProcesses "0"] # indicies must be unique
	ApplicationPath = "C:\\MyProcessPath\ABCD"
	Name = NServiceBus.Host

[WatchedProcesses "1"] # indicies must be unique
	ApplicationPath = "C:\\MyProcessPath2\ABCD"
	Name = NServiceBus.Host

[WatchedProcesses "2"] # indicies must be unique
	ApplicationPath = "C:\\MyProcessPath2\ABCD"
	Name = NServiceBus.Host

使用此配置，我们可以按以下方式检索复杂对象的数组

var configurationBuilder = new ConfigurationBuilder();
configurationBuilder.AddDotNetConfig();
var configurationRoot = configurationBuilder.Build();
var watchedProcesses = configurationRoot.GetSection(nameof(WatchedProcess)).Get<IList<Json.Appsettings.WatchedProcess>>();

注意：确保您的数组项目具有唯一的索引

API

访问.netconfig值有三种主要方式

• 本地API用于直接访问.netconfig值
• Microsoft.Extensions.Configuration提供者
• System.CommandLine用于CLI应用程序

本地API

PM> Install-Package DotNetConfig

.NET工具作者消耗DotNetConfig API的主要用途是首先从一个特定的路径（如果省略，则假定当前目录）构建配置

var config = Config.Build();

生成的配置将包含当前目录（或给定的路径）中设置的分层变量，还包括所有其祖先目录、全局和系统位置。

获取值时，支持的原始数据类型（布尔值、日期时间、数字和字符串）暴露为第一级方法，例如Add、Get和Set，因此您会为每个Boolean、DateTime、Number和String获得许多可用的重载，例如AddBoolean、GetDateTime、GetString或SetNumber。

// reads from:
// [mytool]
//   enabled = true

bool? enabled = config.GetBoolean("mytool", "enabled");

// reads from:
// [mytool.editor]
//   path = code.exe

string? path = config.GetString("mytool.editor", "path");


// reads from:
// [mytool "src/file.txt"]
//   createdOn = 2020-08-23T12:00:00Z

DateTime? created = config.GetDateTime("mytool", "src/file.txt", "createdOn");
// If value was not found, set it to the current datetime
if (created == null)
    // Would create the section if it did not previously exist, and add the variable
    config.SetDateTime("mytool", "src/file.txt", "createdOn", DateTime.Now);

或者你可以使用TryGetXXX方法来代替，以避免在变量（在请求的节和可选子节中）找不到时检查空值返回

if (!config.TryGetDateTime("mytool", "src/file.txt", "createdOn", out created))
    config.SetDateTime("mytool", "src/file.txt", "createdOn", DateTime.Now);

由于.netconfig支持多值变量，你可以通过ConfigEntry获取所有条目并逐一检查或修改它们

foreach (ConfigEntry entry in config.GetAll("proxy", "url"))
{
    // entry.Level allows inspecting the location where the entry was read from
    if (entry.Level == ConfigLevel.System)
        // entry came from Environment.SpecialFolder.System
    else if (entry.Level == ConfigLevel.Global)
        // entry came from Environment.SpecialFolder.UserProfile
    else if (entry.Level == ConfigLevel.Local)
        // entry came from .netconfig.user file in the current dir or an ancestor directory
    else
        // local entry from current dir .netconfig or an ancestor directory

    Console.WriteLine(entry.GetString());
    // entry.GetBoolean(), entry.GetDateTime(), entry.GetNumber()
}

在写入值（通过AddXXX或SetXXX）时，你可以通过传递一个ConfigLevel来指定一个用于持久化值的配置级别

// writes on the global .netconfig in the user's profile
//[vs "alias"]
//	comexp = run|community|exp

config.AddString("vs", "alias", "comexp", "run|community|exp", ConfigLevel.Global);

您可以在文档站点中探索整个API。

Microsoft.Extensions.Configuration

PM> Install-Package DotNetConfig.Configuration

使用（在此示例中，也链其他提供程序）

var config = new ConfigurationBuilder()
    .AddJsonFile(...)
    .AddEnvironmentVariables()
    .AddIniFile(...)
    .AddDotNetConfig();

给定以下.netconfig

[serve]
	port = 8080

[security "admin"]
    timeout = 60

您可以读取两个值

string port = config["serve:port"];  // == "8080";
string timeout = config["security:admin:timeout"];  // == "60";

System.CommandLine

为了让< **.netconfig** >在(dotnet)（全局）工具中成为第一级元素，它提供了与System.CommandLine无缝集成的出色功能。

让我们假设你创建了一个名为package的CLI应用程序，该应用程序管理你本地的包缓存（即NuGet）。你可能有几个命令，如download和prune。

var root = new RootCommand
{
  new Command("download")
  {
    new Argument<string>("id")
  },
  new Command("prune")
  {
    new Argument<string>("id"),
    new Option<int>("days")
  },
}.WithConfigurableDefaults("package");

添加的 WithConfigurableDefaults 调用意味着现在所有的参数和选项都可以在配置文件中指定默认值，例如

[package]
  id = DotNetConfig

[package "prune"]
  days = 30

注意如何在上层也可以指定 id。只要具有兼容的类型（在 download 和 prune 命令中两者都定义为了 string），集成会自动将可配置的值提升到上层部分。

现在在命令行中运行 package -? 将从配置文件中拉取渲染后的默认值，因此您可以看到在没有值的情况下运行命令会实际使用什么值。

Usage:
  package [options] [command]

Options:
  --version       Show version information
  -?, -h, --help  Show help and usage information

Commands:
  download <id>  [default: DotNetConfig]
  prune <id>     [default: DotNetConfig]

而 package prune -? 将显示

Usage:
  package [options] prune [<id>]

Arguments:
  <id>  [default: DotNetConfig]

Options:
  --days <days>   [default: 30]
  -?, -h, --help  Show help and usage information

由于 .netconfig 支持多值变量，因此非常适合为可以多次指定的参数或选项设置默认值。通过将上面的参数进行如下简单更改

    new Argument<string[]>("id")

我们现在可以支持以下配置

[package]
  id = DotNetConfig
  id = Moq
  id = ThisAssembly

现在在没有 id 参数的情况下运行命令将导致处理程序接收所有三个值。您还可以通过例如 download -? 验证这一点。

Usage:
  package [options] download [<id>...]

Arguments:
  <id>  [default: DotNetConfig|Moq|ThisAssembly]

Options:
  -?, -h, --help  Show help and usage information

System.CommandLine 支持的对于多值参数和选项的所有类型都将自动填充：数组、IEnumerable、ICollection、IList 和 List。

对于数字，参数/选项可以是 long 或 int。请注意，由于 .netconfig 中的数字总是 long，在 int 的情况下可能会发生截断。

CLI

命令行工具允许您检查和修改您的 dotnet 工具使用的配置文件。与任何其他 dotnet 工具的安装方式相同。

> dotnet tool install -g dotnet-config

可用的选项和动作（大部分）与 git config 的行为兼容。

当从单个文件中读取和写入数据时，您可以使用与兼容性选项 -f|--file 指定读取/写入文件的 git config。

读取和写入变量不需要任何特殊选项。以下行首先写入一个变量的值，然后检索它的值

> dotnet config mytool.myvariable myvalue
> dotnet config mytool.myvariable
myvalue

值将原样通过标准输出返回，因此您可以直接将其分配给变量，例如。

运行 dotnet config -? 时显示的所有当前选项

Usage: dotnet config [options]

Location (uses all locations by default)
      --global               use global config file
      --system               use system config file
      --local                use .netconfig.user file
  -f, --file                 use given config file (git config compat)
      --path[=VALUE]         use given config file or directory

Action
      --get                  get value: name [value-regex]
      --get-all              get all values: key [value-regex]
      --get-regexp           get values for regexp: name-regex [value-regex]
      --add                  add a new variable: name value
      --unset                remove a variable: name [value-regex]
      --unset-all            remove all matches: name [value-regex]
      --set                  set value: name value [value-regex]
      --set-all              set all matches: name value [value-regex]
      --rename-section       rename section: old-name new-name
      --remove-section       remove a section: name
  -l, --list                 list all
  -e, --edit                 edit the config file in an editor

Other
      --name-only            show variable names only
      --default[=VALUE]      with --get, use default value when missing entry
      --type[=VALUE]         value is given this type, can be 'boolean', '
                               datetime' or 'number'
  -?, -h, --help             Display this help

命令行解析使用 Mono.Options 完成，因此以下所有参数的变体都得到支持：-flag、--flag、/flag、-flag=value、--flag=value、/flag=value、-flag:value、--flag:value、/flag:value、-flag value、--flag value、/flag value。

赞助商

了解更多关于 GitHub Sponsors 的信息