Personalizzare l'output del supporto

Le app da riga di comando offrono in genere un'opzione per visualizzare una breve descrizione dei comandi, delle opzioni e degli argomenti disponibili. System.CommandLine fornisce HelpOption, che è incluso nelle opzioni del RootCommand per impostazione predefinita. HelpOption genera l'output di aiuto per i simboli definiti utilizzando le informazioni esposte da Name, HelpName, Description e altre proprietà, come il valore predefinito o le fonti di completamento.

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>

Gli utenti delle app potrebbero essere abituati a diversi modi per richiedere assistenza su piattaforme diverse, quindi le app basate su System.CommandLine rispondono a molti modi per richiedere assistenza. Tutti i comandi seguenti sono equivalenti:

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

L'output di aiuto non mostra necessariamente tutti i comandi, gli argomenti e le opzioni disponibili. Alcuni di essi potrebbero essere nascosti tramite la Hidden proprietà, il che significa che non vengono visualizzati nell'output della guida (e nei completamenti) ma possono essere specificati tramite riga di comando.

Personalizzazione dell'aiuto

È possibile personalizzare l'output della guida per i comandi definendo un testo guida specifico per ogni simbolo, fornendo maggiore chiarezza agli utenti per quanto riguarda il loro utilizzo.

Per personalizzare il nome dell'argomento di un'opzione, usare la proprietà dell'opzione System.CommandLine.Option.HelpName .

Nell'app di esempio, --light-mode viene spiegato in modo adeguato, ma risulterà utile apportare modifiche alle descrizioni delle opzioni --file e --color. Per --file, l'argomento può essere identificato come <FILEPATH>. Per l'opzione --color , è possibile abbreviare l'elenco dei colori disponibili.

Per apportare queste modifiche, estendere il codice precedente con il codice seguente:

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

L'app produce ora l'output della Guida seguente:

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]

Aggiungere sezioni per migliorare l'output

È possibile aggiungere le prime o le ultime sezioni all'output di aiuto. Si supponga, ad esempio, di voler aggiungere alcune immagini ASCII alla sezione description usando il pacchetto NuGet Spectre.Console .

Definire un'azione personalizzata che esegue una logica aggiuntiva prima e dopo aver chiamato il valore predefinito 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;

    }
}

Aggiorna HelpAction definito da RootCommand per usare l'azione personalizzata:

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

L'output della Guida è ora simile al seguente:

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

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

Vedere anche

System.CommandLine panoramica