如何记录蛋糕构建参数？

Question

在蛋糕构建脚本中,有一种非常巧妙的方法是使用.Description()Task上的扩展来记录任务.使用-showdescription参数调用构建脚本时,将显示这些说明.

我在构建脚本中有几个自定义参数,我想以某种方式记录.目前,我添加了一个任务,输出类似于手册页面样式的描述文本,用于可查看的参数,如下所示:

var nextLineDescription = "\n\t\t\t\t\t"; // for formatting 
Console.WriteLine("ARGUMENTS");
Console.WriteLine("");

Console.WriteLine("\t--someparameter=<number>\t\t" +
                "Description of the parameter" + nextLineDescription +
                "that can span multiple lines" + nextLineDescription +
                "and defaults to 5.\n");

这工作正常,但是很多工作,特别是如果文本应该正确格式化,以便它在命令行中可读.

因此,当我打电话给./build.ps1 -Target MyDocTask 我时,我得到了一个很好

ARGUMENTS

        --someparameter=number          Description of the parameter
                                        that can span multiple lines
                                        and defaults to 5

        --nextParameter                 Next description

...

是否有另一种方法或最佳实践来为参数添加文档,以便它可以在命令行中显示,类似于任务描述？

编辑:或者,我可以在构建脚本中找到所有可用参数来循环它们并生成这样的描述而不是为每个参数手动编写它吗？

Answer 1

目前没有"注册"参数帮助的内置功能,虽然如此,但是请提出一个问题.

也就是说它可以实现,因为Cake只是.NET,你可以使用NuGet上可用的命令行解析器之一来实现这一点.一个这样的解析器是CommandLineParser.

程序集可以是使用该#addin指令从NuGet引用,对于CommandLineParser,它如下所示

#addin "nuget:?package=CommandLineParser&version=2.1.1-beta&prerelease=true"

因为它不是一个"原生"的Cake插件,你需要使用完全限定的类型名称,或者像普通的C#一样添加一个像这样的using语句

using CommandLine;

CommandLineParser使用属性上的类和属性来提供规则和帮助.在下面移植您的示例将如下所示

class Options
{
    [Option("someparameter",
        HelpText = "Description of the parameter, that can span multiple lines",
        Default = 5)]
    public int SomeParameter { get; set; }

    [Option("nextParameter", HelpText = "Next description")]
    public string NextParameter { get; set; }

    [Option("target", HelpText = "Target", Default = "Default")]
    public string Target { get; set; }
}

通常,CommandLineParser会向控制台输出帮助,但是如果要在任务中显示它,则可以使用 TextWriter

var helpWriter = new StringWriter();
var parser = new Parser(config => config.HelpWriter = helpWriter);

然后解析参数,如果指定了"MyDocTask",则会向其提供帮助 helpWriter

Options options = parser
    .ParseArguments<Options>(
        StringComparer.OrdinalIgnoreCase.Equals(Argument("target", "Default"), "MyDocTask")
            ? new []{ "--help" }
            : System.Environment.GetCommandLineArgs()
    )
    .MapResult(
        o => o,
        errors=> new Options { Target = "MyDocTask"} // TODO capture errors here
);

和任务

Task("MyDocTask")
    .Does(() => {
        Information(helpWriter.ToString());
}
);

Task("Default")
    .Does(() => {
        Information("SomeParameter: {0}", options.SomeParameter);
        Information("NextParameter: {0}", options.NextParameter);
        Information("Target: {0}", options.Target);
}
);

然后执行

RunTarget(options.Target);

在MyDocTask将输出帮助

>> cake .\commandline.cake --Target="MyDocTask"

========================================
MyDocTask
========================================
Cake 0.20.0+Branch.main.Sha.417d1eb9097a6c71ab25736687162c0f58bbb74a
Copyright (c) .NET Foundation and Contributors

  --someparameter    (Default: 5) Description of the parameter, that can span multiple lines

  --nextParameter    Next description

  --target           (Default: Default) Target

  --help             Display this help screen.

  --version          Display version information.

而Defaulttask将只输出已解析参数的值

>> cake .\commandline.cake

========================================
Default
========================================
SomeParameter: 5
NextParameter: [NULL]
Target: Default

Task                          Duration
--------------------------------------------------
Default                       00:00:00.0133265
--------------------------------------------------
Total:                        00:00:00.0133265

这将以相当简单的方式为您提供强类型和文档化的参数.

完整的Cake脚本如下:

#addin "nuget:?package=CommandLineParser&version=2.1.1-beta&prerelease=true"
using CommandLine;
class Options
{
    [Option("someparameter",
        HelpText = "Description of the parameter, that can span multiple lines",
        Default = 5)]
    public int SomeParameter { get; set; }

    [Option("nextParameter", HelpText = "Next description")]
    public string NextParameter { get; set; }

    [Option("target", HelpText = "Target", Default = "Default")]
    public string Target { get; set; }
}

var helpWriter = new StringWriter();
var parser = new Parser(config => config.HelpWriter = helpWriter);

    Options options = parser
        .ParseArguments<Options>(
            StringComparer.OrdinalIgnoreCase.Equals(Argument("target", "Default"), "MyDocTask")
                ? new []{ "--help" }
                : System.Environment.GetCommandLineArgs()
        )
        .MapResult(
            o => o,
            errors=> new Options { Target = "MyDocTask"} // could capture errors here
    );


    Task("MyDocTask")
        .Does(() => {
            Information(helpWriter.ToString());
    }
    );

    Task("Default")
        .Does(() => {
            Information("SomeParameter: {0}", options.SomeParameter);
            Information("NextParameter: {0}", options.NextParameter);
            Information("Target: {0}", options.Target);
    }
    );


RunTarget(options.Target);