PowerArgs 使用教程

1. 项目介绍

PowerArgs 是一个强大的 .NET 库，专门用于将命令行参数转换为易于编程处理的 .NET 对象。它不仅提供了基本的参数解析功能，还支持多种高级特性，如参数验证、自动生成的使用文档、Tab 补全、安全字符串参数等。PowerArgs 的设计目标是简化命令行应用程序的开发，使开发者能够专注于业务逻辑而非命令行参数的处理。

2. 项目快速启动

安装 PowerArgs

首先，你需要通过 NuGet 安装 PowerArgs。在 Visual Studio 的 Package Manager Console 中运行以下命令：

Install-Package PowerArgs

创建一个简单的命令行应用程序

以下是一个简单的示例，展示了如何使用 PowerArgs 解析命令行参数：

using PowerArgs;
using System;

// 定义命令行参数类
public class MyArgs
{
    [ArgRequired(PromptIfMissing = true)]
    public string StringArg { get; set; }

    [ArgRange(0, 60)]
    public int IntArg { get; set; }
}

class Program
{
    static void Main(string[] args)
    {
        try
        {
            var parsed = Args.Parse<MyArgs>(args);
            Console.WriteLine($"你输入的字符串是 '{parsed.StringArg}'，整数是 '{parsed.IntArg}'");
        }
        catch (ArgException ex)
        {
            Console.WriteLine(ex.Message);
            Console.WriteLine(ArgUsage.GenerateUsageFromTemplate<MyArgs>());
        }
    }
}

运行应用程序

编译并运行你的应用程序。如果用户没有提供所需的参数，PowerArgs 会自动提示用户输入。

3. 应用案例和最佳实践

案例1：多命令支持

PowerArgs 支持在一个应用程序中定义多个命令。例如，你可以创建一个简单的计算器应用程序，支持加、减、乘、除四种操作：

[ArgExceptionBehavior(ArgExceptionPolicy.StandardExceptionHandling)]
public class CalculatorProgram
{
    [HelpHook, ArgShortcut("-?"), ArgDescription("显示帮助信息")]
    public bool Help { get; set; }

    [ArgActionMethod, ArgDescription("加法操作")]
    public void Add(TwoOperandArgs args)
    {
        Console.WriteLine(args.Value1 + args.Value2);
    }

    [ArgActionMethod, ArgDescription("减法操作")]
    public void Subtract(TwoOperandArgs args)
    {
        Console.WriteLine(args.Value1 - args.Value2);
    }

    [ArgActionMethod, ArgDescription("乘法操作")]
    public void Multiply(TwoOperandArgs args)
    {
        Console.WriteLine(args.Value1 * args.Value2);
    }

    [ArgActionMethod, ArgDescription("除法操作")]
    public void Divide(TwoOperandArgs args)
    {
        Console.WriteLine(args.Value1 / args.Value2);
    }
}

public class TwoOperandArgs
{
    [ArgRequired, ArgDescription("第一个操作数"), ArgPosition(1)]
    public double Value1 { get; set; }

    [ArgRequired, ArgDescription("第二个操作数"), ArgPosition(2)]
    public double Value2 { get; set; }
}

class Program
{
    static void Main(string[] args)
    {
        Args.InvokeAction<CalculatorProgram>(args);
    }
}

最佳实践

1. 参数验证：使用 ArgRequired、ArgRange 等属性对参数进行验证，确保用户输入的有效性。
2. 自动帮助生成：通过 HelpHook 属性自动生成帮助信息，减少手动编写帮助文档的工作量。
3. Tab 补全：使用 TabCompletion 属性启用命令行参数的 Tab 补全功能，提升用户体验。

4. 典型生态项目

PowerArgs 作为一个命令行参数解析库，通常与其他 .NET 项目结合使用，以构建功能强大的命令行工具。以下是一些典型的生态项目：

1. klooie：一个用于构建文本用户界面的 .NET 库，与 PowerArgs 结合使用可以创建交互式的命令行应用程序。
2. Cocona：一个轻量级的 .NET 控制台应用程序框架，支持快速构建命令行工具。
3. ConsoleAppFramework：一个零依赖、零开销的 .NET 控制台应用程序框架，适用于构建高性能的命令行工具。

通过结合这些生态项目，开发者可以构建出功能丰富、用户体验良好的命令行应用程序。