蛋糕如何建立參數記錄？

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