蛋糕如何建立参数记录？

Question

在一个蛋糕构建脚本中，有一个非常简洁的方式来记录在任务上使用.Description()扩展的任务。使用-showdescription参数调用构建脚本时会显示这些说明。

我在我的构建脚本中有几个自定义参数，我想以某种方式记录文档。目前，我补充说，输出类似于manual page style对可用参数的说明文字，看起来像这样一个任务：

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" 

，因为它不是你需要使用完全限定的类型名称或就像普通的“原生”蛋糕插件C＃添加这样的使用语句

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. 

和Default任务会的分析参数，就输出值

>> cake .\commandline.cake 

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

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

氏s会以相当简单的方式为您提供强有力的类型和记录参数。

完整的蛋糕下面的脚本：

#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);