用
System.CommandLine创建 C# 命令行工具，核心是定义命令、选项、参数，再绑定处理逻辑——它比手动解析
args更清晰，也比传统
Console.ReadLine()交互更专业。
安装 System.CommandLine
在项目中通过 NuGet 安装最新稳定版（推荐 v2.0.0-beta4 或更高）：
CLI 方式：dotnet add package System.CommandLine --version 2.0.0-beta4或在 .csproj 中添加：
<packagereference include="System.CommandLine" version="2.0.0-beta4"></packagereference>
注意：v2 是当前主推版本，API 更统一，文档和示例也以 v2 为主；避免混用 v1（已归档）。
定义基础命令和选项
从
RootCommand开始，用
Option<t></t>添加开关，用
Argument<t></t>接收位置参数：
var root = new RootCommand("我的工具：处理文本文件");
var inputOpt = new Option<string>("--input", "输入文件路径") { IsRequired = true };
var verboseOpt = new Option<bool>("--verbose", "显示详细日志");
<p>root.AddOption(inputOpt);
root.AddOption(verboseOpt);</p><p>root.SetHandler((input, verbose) =>
{
Console.WriteLine($"处理文件：{input}");
if (verbose) Console.WriteLine("详细模式已启用");
}, inputOpt, verboseOpt);
关键点：
-
SetHandler绑定执行逻辑，参数顺序必须与
AddOption/
AddArgument传入顺序一致
- 选项名支持短格式（如
-i）和长格式（
--input），可同时注册：
new Option<string>("-i", "--input", ...)</string>
支持子命令（如 git commit / push）
用
Command创建子命令，再挂到根命令下：
var commitCmd = new Command("commit", "提交更改");
var messageOpt = new Option<string>("--message", "提交信息");
commitCmd.AddOption(messageOpt);
commitCmd.SetHandler(msg => Console.WriteLine($"提交：{msg}"), messageOpt);
<p>root.AddCommand(commitCmd);</p><p>// 运行：dotnet run -- commit --message "feat: add login"
子命令可嵌套多层，适合功能复杂的 CLI 工具（比如
dotnet tool restore中的
tool是命令，
restore是其子命令）。
自动帮助与错误提示
无需手写
--help逻辑，
System.CommandLine默认支持： 运行
dotnet run -- --help→ 显示根命令帮助 运行
dotnet run -- commit --help→ 显示
commit子命令帮助 参数缺失、类型错误时自动报错并提示正确用法
还可自定义帮助文本：
root.Description = "一个轻量级文件处理器"，或为选项加说明：
inputOpt.Description = "必填：UTF-8 编码的 .txt 文件"。
基本上就这些。不复杂但容易忽略的是 handler 参数顺序和 option 注册顺序必须严格对应——写错会导致运行时报
ArgumentException。其他高级用法（如自定义类型转换、中间件管道、国际化）可按需查官方文档。
