Como configurar o analisador em System.CommandLine

2025-06-22

Importante

System.CommandLine está atualmente em VERSÃO PRÉVIA e essa documentação é para a versão 2.0 beta 5. Algumas informações referem-se ao produto de pré-lançamento que pode ser substancialmente modificado antes de ser lançado. A Microsoft não oferece garantias, expressas ou implícitas, em relação às informações fornecidas aqui.

System.CommandLine.CommandLineConfiguration é uma classe que fornece propriedades para configurar o analisador. É um argumento opcional para todos os Parse métodos, como System.CommandLine.Command.Parse ou System.CommandLine.Parsing.CommandLineParser.Parse. Quando não for fornecido, a configuração padrão será usada.

Cada System.CommandLine.ParseResult instância tem uma System.CommandLine.ParseResult.Configuration propriedade que retorna a configuração usada para análise.

Saída e erro padrão

System.CommandLine.CommandLineConfiguration torna o teste, bem como muitos cenários de extensibilidade, mais fácil do que usar System.Console. Ele expõe duas TextWriter propriedades: Output e Error. Elas podem ser definidas para qualquer TextWriter instância, como uma StringWriter, que pode ser usada para capturar a saída para teste.

Vamos definir um comando simples que grava na saída padrão:

Option<FileInfo?> fileOption = new("--file")
{
    Description = "An option whose argument is parsed as a FileInfo"
};

RootCommand rootCommand = new("Configuration sample")
{
    fileOption
};

rootCommand.SetAction((parseResult) =>
{
    FileInfo? fileOptionValue = parseResult.GetValue(fileOption);
    parseResult.Configuration.Output.WriteLine($"File option value: {fileOptionValue?.FullName}");
});

Agora, vamos usar CommandLineConfiguration para capturar a saída:

StringWriter output = new();
CommandLineConfiguration configuration = new(rootCommand)
{
    Output = output,
    Error = TextWriter.Null
};

configuration.Parse("-h").Invoke();
Debug.Assert(output.ToString().Contains("Configuration sample"));

EnablePosixBundling

O agrupamento de opções de caractere único é habilitado por padrão, mas você pode desabilitá-lo definindo a System.CommandLine.CommandLineConfiguration.EnablePosixBundling propriedade como false.

ProcessTerminationTimeout

O tempo limite de término do processo pode ser configurado por meio da System.CommandLine.CommandLineConfiguration.ProcessTerminationTimeout propriedade. O valor padrão é 2 segundos.

ResponseFileTokenReplacer

Os arquivos de resposta são habilitados por padrão, mas você pode desabilitá-los definindo a System.CommandLine.CommandLineConfiguration.ResponseFileTokenReplacer propriedade como null. Você também pode fornecer uma implementação personalizada para personalizar como os arquivos de resposta são processados.

EnableDefaultExceptionHandler

Por padrão, todas as exceções sem tratamento geradas durante a invocação de um comando são capturadas e relatadas ao usuário. Esse comportamento pode ser desabilitado definindo a System.CommandLine.CommandLineConfiguration.EnableDefaultExceptionHandler propriedade como false. Isso é útil quando você deseja lidar com exceções de maneira personalizada, como registrar em log ou fornecer uma experiência de usuário diferente.

Classes derivadas

System.CommandLine.CommandLineConfiguration não está lacrado, portanto, você pode derivar dele para adicionar propriedades ou métodos personalizados. Isso é útil quando você deseja fornecer opções de configuração adicionais específicas ao seu aplicativo.

Consulte também

visão geral System.CommandLine

Compartilhar via