『CliWrap』.NET 生态最优雅的命令行封装库

项目简介

CliWrap 是 .NET 生态中最受欢迎的第三方命令行封装库，由乌克兰开发者 Tyrrrz（Alexey Golub）创建并维护。它提供了一套简洁、类型安全的 API，让 C# 开发者能够轻松调用外部进程、处理标准输出/错误流，并优雅地管理进程生命周期。CliWrap 以零外部依赖、纯异步流式管道模型和优雅的事件驱动 API著称，是替代原生 System.Diagnostics.Process 的首选方案。

GitHub 数据

核心功能

• 流式管道（Pipe）模型：通过 PipeSource / PipeTarget 将标准输入/输出与内存缓冲、文件流或管道连接，构建灵活的数据处理链条
• 全异步支持：基于 ValueTask 的异步 API，完美适配现代 .NET 异步编程模型
• 事件驱动编程：订阅 Started、StdOut、StdErr、Exited 等事件，实时追踪进程状态
• 超时与取消控制：原生支持 CancellationToken，可设置超时自动终止进程
• 参数安全转义：自动处理命令行参数中的特殊字符与空格，防止注入攻击
• 多种输出模式：支持内存缓冲（Buffered）、管道到流（PipeToStream）、管道到文件（PipeToFile）、丢弃输出（PipeToNull）
• Docker 友好：可与 Docker CLI 无缝集成，在容器化环境中安全执行外部命令

v3.10.2 亮点

• 改进的取消令牌处理，减少资源泄漏
• 增强的错误诊断消息
• 对 .NET 8 / .NET 9 的全面兼容性
• 更完善的 XML 文档注释

技术栈

• 语言：C#
• 框架：.NET Standard 2.0+ / .NET 6 及以上
• 外部依赖：零依赖，纯 BCL API 实现
• 兼容性：支持 Windows、Linux、macOS 全平台

使用方式 / 安装

通过 NuGet 一键安装：

dotnet add package CliWrap

基础用法示例：

using CliWrap;

// 最简调用：执行命令并等待完成
var result = await Cli.Wrap("git")
    .WithArguments("log --oneline -5")
    .ExecuteAsync();

// 流式输出：实时读取标准输出
await Cli.Wrap("ffmpeg")
    .WithArguments("-i input.mp4 output.gif")
    .WithStandardOutputPipe(PipeTarget.ToStream(Console.OpenStandardOutput()))
    .ExecuteAsync();

// 事件驱动模式
var cmd = Cli.Wrap("dotnet")
    .WithArguments("build -c Release");

cmd.StdOut += (_, e) => Console.WriteLine($"[OUT] {e.Text}");
cmd.StdErr += (_, e) => Console.WriteLine($"[ERR] {e.Text}");
cmd.Exited += (_, e) => Console.WriteLine($"Exit code: {e.ExitCode}");

await cmd.ExecuteAsync();

// 超时控制
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
try
{
    await Cli.Wrap("slow-command")
        .WithArguments("--work")
        .ExecuteAsync(cts.Token);
}
catch (OperationCanceledException)
{
    Console.WriteLine("命令执行超时，已终止");
}

适用场景

• .NET 后端服务调用 CLI：在 ASP.NET Core 应用中调用 FFmpeg、ImageMagick、wkhtmltopdf 等第三方工具
• 自动化与 CI/CD 脚本：用 C# 编写跨平台构建脚本、部署管道，替代 Python/Shell
• 日志与数据处理：实时读取外部进程的日志输出，进行结构化分析
• Docker 容器管理：在 C# 应用中安全调用 docker/podman 命令
• DevOps 工具开发：构建自定义 CLI 工具的执行引擎或调度器

竞品对比

CliWrap 的核心优势在于零外部依赖的轻量设计与优雅的链式 API。原生 Process 类虽内置但使用繁琐（需要手动管理流、处理编码、处理退出事件），CliWrap 将这些琐碎工作全部封装为一行代码。它在 NuGet 上的周下载量超过 300 万，是 .NET 开发者调用外部进程的首选库。

参考资料

• GitHub: Tyrrrz/CliWrap
• NuGet: CliWrap
• CliWrap 官方文档
• 作者 Tyrrrz 的其他开源项目