Arguments to Config — простая и мощная библиотека для пар...

В одной из прошлых статей я писал о том, как рефакторил CLI-сервис на C#, в котором не был реализован маппинг аргументов в класс конфигураций. Пришлось писать свой.

Есть разные библиотеки для этого, в т.ч. от MS. Но эта слишком сложная, другие не очень понравились. А главное то, что нет реализаций пайплайна, т.е. в сервис передаётся набор команд с параметрами и значениями, которые потом выполняются по порядку.

Прошло время и мне пришло в голову своё решение. Я намеренно не смотрел, как было сделано у других, а просто начал собирать то, что могло смапить самые популярные команды, типа git commit со всеми параметрами. А, главное, он должен в конечном итоге решать мою задачу. Шаг за шагом я собрал свою библиотеку, обложив её тестами.

Ключевой особенностью является то, что в ней нет других зависимостей и нет настроек — всё необходимое описывается через понятные атрибуты. А полученные значения можно сохранить даже в словарь коллекций, используя всего два атрибута (один получает значение, другой его раскладывает).

И, конечно же, пайплайны.

Представьте. Вы теперь легко можете написать свой сервис, который будет одной командой по порядку собирать проект на python, запускать тесты. закидывать в docker-контейнер и публиковать в Azure, а потом ещё и curl'ом сходит посмотреть, перемешав всё это с необходимой бизнес-логикой. Но команды могут и повторяться.

Я очень люблю, когда к проекту написан подробный README с работающими примерами (ну, или хотя бы есть ссылка на подробную документацию), поэтому снабдил свой проект подробным описанием со всеми возможными случаями использования. В тестах также можно увидеть множество вариантов использования библиотеки. Я там постарался учесть все возможные случаи.

Тут исходники: https://github.com/Mansiper/ArgsToConfig
Тут пакет: https://www.nuget.org/packages/Mansiper.ArgsToConfig

Фичи библиотеки:

поддержка множества базовых типов, а также возможность конвертации в вообще любой;
базовая поддержка типа tuple (больше нет ни у кого);
поддержка команд --help и --version;
возможность преобразования обратно в команду;
генерация справки;
поддержка pathspec;
поддержка любых атрибутов, унаследованных от ValidationAttribute;
поддержка списков команд (пайплайнов)
поддержка коллекций;
поддержка вложенных классов;
гибкая поддержка самых разных типов
и мн. др.

Пример кода:

// Команда: app connect -u alice -p secret run

class AppConfig
{
    [ArgsObject("connect", Description = "Параметры подключения")]
    public ConnectionConfig Connect { get; set; } = null!;

    [ArgsHasParameter("run")]
    public bool? Run { get; set; }
}

record ConnectionConfig
{
    [ArgsValueFor("-u")]
    public string User { get; set; } = null!;

    [ArgsValueFor("-p")]
    public string Pass { get; set; } = null!;
}

// А для преобразования просто вызываем в самом начале программы:

var (config, errors, position) = ArgumentsReader.ToObject<AppConfig>(args);

Пример для пайплайна:

//команда: app pipeline pull --fetch commit -m "fix" push run

class ExecConfig
{
    [ArgsHasParameter("pipeline")]
    public bool? Pipeline { get; set; }

    [ArgsPipeline]
    public IPipelineCommand[]? Commands { get; set; }

    [ArgsHasParameter("run")]
    public bool? Run { get; set; }
}

interface IPipelineCommand { }

[ArgsPipelineCommand("pull")]
class PullCommand : IPipelineCommand
{
    [ArgsHasParameter("--fetch")]
    public bool? Fetch { get; set; }
}

[ArgsPipelineCommand("commit")]
class CommitCommand : IPipelineCommand
{
    [ArgsValueFor("-m")]
    public string? Message { get; set; }
}

[ArgsPipelineCommand("push")]
class PushCommand : IPipelineCommand
{
    [ArgsHasParameter("--force")]
    public bool? Force { get; set; }
}

Что мне помогло всё это сделать?

Помимо того, что я бы заколебался писать всю эту логику преобразования на 1600 строк без помощи LLM, добавляя туда всё новые фичи, мне помог Claude с анализом других сервисов. Когда я закончил всё то, что придумал изначально, закинул в Claude ссылку на свою библиотеку с уже готовым подробным описанием в README. Он "прочитал" о моей библиотеке и сравнил с существующими, предложив ещё несколько фич, о которых я даже не подозревал. Также он косвенно подкинул пару других идей. Например, поддержку ValidationAttribute. Реализовав почти все из них, я попросил ещё раз сравнить с другими решениями, на что он мне выдал следующую сравнительную таблицу.

Тут очень большая таблица

	Mansiper.ArgsToConfig (моя библиотека)	CommandLineParser	System.CommandLine	McMaster.Extensions.CommandLineUtils	Spectre.Console.Cli
NuGet package	`Mansiper.ArgsToConfig`	`CommandLineParser`	`System.CommandLine`	`McMaster.Extensions.CommandLineUtils`	`Spectre.Console.Cli`
Maintainer	Community (Mansiper)	Community	Microsoft	Community (natemcmaster)	Community (.NET Foundation)
Stable since	< 1.0 (pre-release)	2005	2024 (beta → stable)	2017	2021
API style	Attribute-only	Attribute + Fluent	Imperative builder	Attribute + Builder	Attribute (opinionated)
License	MIT	MIT	MIT	Apache 2.0	MIT
Target frameworks	.NET 8+ (modern)	.NET Standard 2.0, .NET Fx 4.0+	.NET 6+	.NET Standard 2.0+	.NET Standard 2.0, .NET 8+
External dependencies	None	None	None	None	Spectre.Console
Attribute-based declaration	✅	✅	⚠️ Partial (via DragonFruit)	✅	✅
Fluent builder API	❌	✅	✅	✅	❌
Method-parameter inference	❌	❌	✅	❌	❌
Returns errors without exceptions	✅	⚠️ (callback-based)	⚠️ (exception or callback)	⚠️	⚠️
Object-to-args round-trip (`ToArgs`)	✅	❌	❌	❌	❌
Synopsis / usage string generation	✅	❌	❌	❌	❌
Named flags (`--verbose`)	✅	✅	✅	✅	✅
Positional arguments	✅	✅	✅	✅	✅
True/false flag pairs (`--sign`/`--no-sign`)	✅	❌	❌	❌	❌
Short + long aliases (`-v\|--verbose`)	✅	✅	✅	✅	✅
Combined short flags (`-am` → `-a -m`)	✅	✅	✅	✅	✅
`--flag=value` syntax	✅	✅	✅	✅	✅
`-fflag` inline value (`-o./bin`)	✅	✅	❌	❌	❌
Repeated flags as collection	✅	✅	✅	✅	✅
Pathspec (`--` separator)	✅	❌	✅	❌	❌
Enum mapping from flags	✅	✅	✅	✅	✅
Bit-flag (Flags) enum	✅	❌	❌	❌	❌
Tuple splitting from single arg	✅	❌	❌	❌	❌
Dictionary from repeated flags	✅	❌	❌	❌	✅ (via IDictionary option)
Pipeline command sequences	✅	❌	❌	❌	❌
Primitives (`string`, `int`, `bool`, `double`, …)	✅	✅	✅	✅	✅
`DateTime`, `DateOnly`, `TimeOnly`, `TimeSpan`	✅	⚠️ `DateTime` only	✅	⚠️ `DateTime` only	⚠️ via custom converter
`Guid`, `Uri`, `Version`, `IPAddress`	✅	⚠️ `Uri` via ctor	✅ `Uri`, others via converter	⚠️	⚠️
`FileInfo`, `DirectoryInfo`	✅	❌	✅	✅	❌
Any `IConvertible`	✅	⚠️	⚠️	⚠️	❌
Custom converter	✅	✅	✅	✅	✅ (`TypeConverter`)
Value tuples	✅	❌	❌	❌	❌
Nullable types (optional by nullability)	✅	✅	✅	✅	✅
Records & structs as config objects	✅	❌	❌	❌	❌
Subcommand support	✅	✅ (verbs)	✅	✅	✅
Arbitrary nesting depth	✅	✅	✅	✅	✅
Record/struct as subcommand	✅	❌	❌	❌	❌
Global/recursive options	❌	❌	✅	✅	✅
Async command execution	❌	❌	✅	✅	✅
DI integration	❌	❌	✅	✅ (via DI)	✅
`System.ComponentModel.DataAnnotations`	✅	❌	❌	✅ (`[Required]`, `[Range]`)	❌
Allowed-values list	✅	❌	⚠️ Custom validator	❌	⚠️ Custom validator
Existing file validation	✅	❌	⚠️	❌	⚠️ Custom
Existing directory validation	✅	❌	⚠️	❌	⚠️ Custom
Legal filename characters	✅	❌	❌	❌	❌
Mutual exclusion (`[ArgsOneOf]`)	✅	❌	❌	❌	❌
Mutual requirement (`[ArgsMutuallyRequired]`)	✅	❌	❌	❌	❌
Conditional dependency (`[ArgsIfSet]`)	✅	❌	❌	❌	❌
Ordering constraint (`[ArgsAfter]`)	✅	❌	❌	❌	❌
Custom `Validate()` override	❌	❌	✅	❌	✅
Error position reporting	✅	❌	❌	❌	❌
Env var fallback per argument	✅	❌	✅	❌	❌
`.env` file auto-loading	✅	❌	❌	❌	❌
Config file / `appsettings.json` support	❌	❌	⚠️ Via host builder	✅ (via `IConfiguration`)	❌
Response file support (`@file`)	❌	❌	✅	❌	❌
Auto-generated help (`--help`)	✅	✅	✅	✅	✅
`--version` flag	✅	✅	✅	✅	✅
Help grouping / sections	✅	❌	❌	❌	❌
Cached help generation	✅	❌	❌	❌	❌
Unknown-argument callback	✅	✅	✅	✅	✅
Rich terminal output (colors, tables)	❌	❌	❌	❌	✅ (via Spectre.Console)
Shell tab completion	❌	❌	✅	❌	❌ (via Cocona: yes)
NuGet downloads (approx.)	< 1 K (new)	80 M+	50 M+	25 M+	30 M+
GitHub stars (approx.)	0	4 K+	3 K+	2 K+	1 K+ (part of Spectre.Console 10 K+)
Active maintenance	✅	⚠️ Slow	✅	⚠️ Slow	✅
.NET Foundation member	❌	❌	✅	❌	✅
Test helper package	❌	❌	❌	❌	✅ (`Spectre.Console.Testing`)
F# support	❌	✅ (separate pkg)	✅	❌	❌

Благодаря этому проекту я узнал немало нового о возможностях командных строк. Раньше я их просто использовал, не особо задумываясь, как они работают.

Пользуйтесь. Принимаются любые предложения по улучшению и баг-репорты (мог упустить особо мудрёные случаи, хотя, кажется, уже должно покрываться 99,9% случаев).

推荐订阅源

Все публикации подряд на Хабре

И, конечно же, пайплайны.

Фичи библиотеки:

Пример кода:

Что мне помогло всё это сделать?