Anpassa hjälputdata

Kommando-radsprogram ger vanligtvis ett alternativ för att visa en kort beskrivning av de tillgängliga kommandona, alternativen och argumenten. System.CommandLine tillhandahåller HelpOption, som ingår i RootCommand-alternativen som standard. HelpOption genererar hjälputdata för definierade symboler med hjälp av informationen som exponeras av Name, HelpName, Descriptionoch andra egenskaper som standardvärde eller slutförandekällor.

Option<FileInfo> fileOption = new("--file")
{
    Description = "The file to print out.",
};
Option<bool> lightModeOption = new("--light-mode")
{
    Description = "Determines whether the background color will be black or white"
};
Option<ConsoleColor> foregroundColorOption = new("--color")
{
    Description = "Specifies the foreground color of console output",
    DefaultValueFactory = _ => ConsoleColor.White
};

RootCommand rootCommand = new("Read a file")
{
    fileOption,
    lightModeOption,
    foregroundColorOption
};
rootCommand.Parse("-h").Invoke();

Description:
  Read a file

Usage:
  scl [options]

Options:
  -?, -h, --help                                            Show help and usage information
  --version                                                 Show version information
  --file                                                    The file to print out.
  --light-mode                                              Determines whether the background color will be black
                                                            or white
  --color                                                   Specifies the foreground color of console output
  <Black|Blue|Cyan|DarkBlue|DarkCyan|DarkGray|DarkGreen|Da  [default: White]
  rkMagenta|DarkRed|DarkYellow|Gray|Green|Magenta|Red|Whit
  e|Yellow>

Appanvändare kan vara vana vid olika sätt att be om hjälp på olika plattformar, så appar byggda på System.CommandLine svarar på många sätt att be om hjälp. Följande kommandon är alla lika:

dotnet --help
dotnet -h
dotnet /h
dotnet -?
dotnet /?

Hjälputmatningen visar inte nödvändigtvis alla tillgängliga kommandon, argument och alternativ. Vissa av dem kan vara dolda via Hidden egenskapen, vilket innebär att de inte visas i hjälputdata (och slutföranden) men kan anges på kommandoraden.

Hjälpanpassning

Du kan anpassa hjälputdata för kommandon genom att definiera specifik hjälptext för varje symbol, vilket ger användarna ytterligare klarhet om deras användning.

Om du vill anpassa namnet på ett alternativs argument använder du alternativets System.CommandLine.Option.HelpName egenskap.

I exempelappen förklaras --light-mode korrekt, men ändringar i beskrivningarna för alternativen --file och --color skulle vara till hjälp. För --filekan argumentet identifieras som en <FILEPATH>. För alternativet --color kan du förkorta listan över tillgängliga färger.

Om du vill göra dessa ändringar utökar du den tidigare koden med följande kod:

fileOption.HelpName = "FILEPATH";
foregroundColorOption.AcceptOnlyFromAmong(
    ConsoleColor.Black.ToString(),
    ConsoleColor.White.ToString(),
    ConsoleColor.Red.ToString(),
    ConsoleColor.Yellow.ToString()
);

Appen genererar nu följande hjälputdata:

Description:
  Read a file

Usage:
  scl [options]

Options:
  -?, -h, --help                    Show help and usage information
  --version                         Show version information
  --file <FILEPATH>                 The file to print out.
  --light-mode                      Determines whether the background color will be black or white
  --color <Black|Red|White|Yellow>  Specifies the foreground color of console output [default: White]

Lägg till avsnitt för att hjälpa produktionen.

Du kan lägga till första eller sista avsnitt i hjälputdata. Anta till exempel att du vill lägga till lite ASCII-konst i beskrivningsavsnittet med hjälp av NuGet-paketet Spectre.Console .

Definiera en anpassad åtgärd som utför lite extra logik före och efter anrop av standardinställningen HelpAction:

internal class CustomHelpAction : SynchronousCommandLineAction
{
    private readonly HelpAction _defaultHelp;

    public CustomHelpAction(HelpAction action) => _defaultHelp = action;

    public override int Invoke(ParseResult parseResult)
    {
        Spectre.Console.AnsiConsole.Write(new FigletText(parseResult.RootCommandResult.Command.Description!));

        int result = _defaultHelp.Invoke(parseResult);

        Spectre.Console.AnsiConsole.WriteLine("Sample usage: --file input.txt");

        return result;

    }
}

Uppdatera den HelpAction som definierats av RootCommand för att använda den anpassade åtgärden:

for (int i = 0; i < rootCommand.Options.Count; i++)
{
    // RootCommand has a default HelpOption; update its Action.
    if (rootCommand.Options[i] is HelpOption defaultHelpOption)
    {
        defaultHelpOption.Action = new CustomHelpAction((HelpAction)defaultHelpOption.Action!);
        break;
    }
}

Hjälputdata ser nu ut så här:

  ____                       _                __   _   _
 |  _ \    ___    __ _    __| |     __ _     / _| (_) | |   ___
 | |_) |  / _ \  / _` |  / _` |    / _` |   | |_  | | | |  / _ \
 |  _ <  |  __/ | (_| | | (_| |   | (_| |   |  _| | | | | |  __/
 |_| \_\  \___|  \__,_|  \__,_|    \__,_|   |_|   |_| |_|  \___|

Description:
  Read a file

Usage:
  scl [options]

Options:
  -?, -h, --help                    Show help and usage information
  --version                         Show version information
  --file <FILEPATH>                 The file to print out.
  --light-mode                      Determines whether the background color will be black or white
  --color <Black|Red|White|Yellow>  Specifies the foreground color of console output [default: White]

Sample usage: --file input.txt

Se även

System.CommandLine överblick