Formação
Percurso de aprendizagem
Criar métodos em aplicativos de console C# (Introdução ao C#, Parte 5) - Training
Este caminho de aprendizagem abrange a sintaxe de criação e uso de métodos em aplicativos de console C#.
Este browser já não é suportado.
Atualize para o Microsoft Edge para tirar partido das mais recentes funcionalidades, atualizações de segurança e de suporte técnico.
Importante
System.CommandLine
está atualmente em PREVIEW, e esta documentação é para a versão 2.0 beta 4.
Algumas informações estão relacionadas ao produto de pré-lançamento que pode ser substancialmente modificado antes de ser lançado. A Microsoft não faz garantias, de forma expressa ou implícita, em relação à informação aqui apresentada.
Este artigo explica como definir comandos, opções e argumentos em aplicativos de linha de comando criados com a System.CommandLine
biblioteca. Para criar um aplicativo completo que ilustre essas técnicas, consulte o tutorial Introdução ao System.CommandLine.
Para obter orientação sobre como criar comandos, opções e argumentos de um aplicativo de linha de comando, consulte Diretrizes de design.
Cada aplicativo de linha de comando tem um comando raiz, que se refere ao próprio arquivo executável. O caso mais simples para invocar seu código, se você tiver um aplicativo sem subcomandos, opções ou argumentos, ficaria assim:
using System.CommandLine;
class Program
{
static async Task Main(string[] args)
{
var rootCommand = new RootCommand("Sample command-line app");
rootCommand.SetHandler(() =>
{
Console.WriteLine("Hello world!");
});
await rootCommand.InvokeAsync(args);
}
}
Os comandos podem ter comandos filho, conhecidos como subcomandos ou verbos, e podem aninhar quantos níveis você precisar. Você pode adicionar subcomandos conforme mostrado no exemplo a seguir:
var rootCommand = new RootCommand();
var sub1Command = new Command("sub1", "First-level subcommand");
rootCommand.Add(sub1Command);
var sub1aCommand = new Command("sub1a", "Second level subcommand");
sub1Command.Add(sub1aCommand);
O subcomando mais interno neste exemplo pode ser invocado assim:
myapp sub1 sub1a
Um método manipulador de comandos normalmente tem parâmetros, e os valores podem vir de opções de linha de comando. O exemplo a seguir cria duas opções e as adiciona ao comando root. Os nomes das opções incluem prefixos de hífen duplo, o que é típico das CLIs POSIX. O código do manipulador de comandos exibe os valores dessas opções:
var delayOption = new Option<int>
(name: "--delay",
description: "An option whose argument is parsed as an int.",
getDefaultValue: () => 42);
var messageOption = new Option<string>
("--message", "An option whose argument is parsed as a string.");
var rootCommand = new RootCommand();
rootCommand.Add(delayOption);
rootCommand.Add(messageOption);
rootCommand.SetHandler((delayOptionValue, messageOptionValue) =>
{
Console.WriteLine($"--delay = {delayOptionValue}");
Console.WriteLine($"--message = {messageOptionValue}");
},
delayOption, messageOption);
Aqui está um exemplo de entrada de linha de comando e a saída resultante para o código de exemplo anterior:
myapp --delay 21 --message "Hello world!"
--delay = 21
--message = Hello world!
Para adicionar uma opção a um comando de cada vez, use o Add
método ou AddOption
como mostrado no exemplo anterior. Para adicionar uma opção a um comando e recursivamente a todos os seus subcomandos, use o AddGlobalOption
método, conforme mostrado no exemplo a seguir:
var delayOption = new Option<int>
("--delay", "An option whose argument is parsed as an int.");
var messageOption = new Option<string>
("--message", "An option whose argument is parsed as a string.");
var rootCommand = new RootCommand();
rootCommand.AddGlobalOption(delayOption);
rootCommand.Add(messageOption);
var subCommand1 = new Command("sub1", "First level subcommand");
rootCommand.Add(subCommand1);
var subCommand1a = new Command("sub1a", "Second level subcommand");
subCommand1.Add(subCommand1a);
subCommand1a.SetHandler((delayOptionValue) =>
{
Console.WriteLine($"--delay = {delayOptionValue}");
},
delayOption);
await rootCommand.InvokeAsync(args);
O código anterior é adicionado --delay
como uma opção global ao comando raiz e está disponível no manipulador para subCommand1a
.
Os argumentos são definidos e adicionados a comandos como opções. O exemplo a seguir é como o exemplo de opções, mas define argumentos em vez de opções:
var delayArgument = new Argument<int>
(name: "delay",
description: "An argument that is parsed as an int.",
getDefaultValue: () => 42);
var messageArgument = new Argument<string>
("message", "An argument that is parsed as a string.");
var rootCommand = new RootCommand();
rootCommand.Add(delayArgument);
rootCommand.Add(messageArgument);
rootCommand.SetHandler((delayArgumentValue, messageArgumentValue) =>
{
Console.WriteLine($"<delay> argument = {delayArgumentValue}");
Console.WriteLine($"<message> argument = {messageArgumentValue}");
},
delayArgument, messageArgument);
await rootCommand.InvokeAsync(args);
Aqui está um exemplo de entrada de linha de comando e a saída resultante para o código de exemplo anterior:
myapp 42 "Hello world!"
<delay> argument = 42
<message> argument = Hello world!
Um argumento que é definido sem um valor padrão, como messageArgument
no exemplo anterior, é tratado como um argumento necessário. Uma mensagem de erro é exibida e o manipulador de comandos não é chamado, se um argumento necessário não for fornecido.
Ambos os comandos e opções suportam aliases. Você pode adicionar um alias a uma opção chamando AddAlias
:
var option = new Option("--framework");
option.AddAlias("-f");
Dado esse alias, as seguintes linhas de comando são equivalentes:
myapp -f net6.0
myapp --framework net6.0
Os aliases de comando funcionam da mesma maneira.
var command = new Command("serialize");
command.AddAlias("serialise");
Esse código torna equivalentes as seguintes linhas de comando:
myapp serialize
myapp serialise
Recomendamos que você minimize o número de aliases de opção definidos e evite definir determinados aliases em particular. Para obter mais informações, consulte Aliases de formulário curto.
Para tornar uma opção necessária, defina sua IsRequired
propriedade como true
, conforme mostrado no exemplo a seguir:
var endpointOption = new Option<Uri>("--endpoint") { IsRequired = true };
var command = new RootCommand();
command.Add(endpointOption);
command.SetHandler((uri) =>
{
Console.WriteLine(uri?.GetType());
Console.WriteLine(uri?.ToString());
},
endpointOption);
await command.InvokeAsync(args);
A seção de opções da ajuda do comando indica que a opção é necessária:
Options:
--endpoint <uri> (REQUIRED)
--version Show version information
-?, -h, --help Show help and usage information
Se a linha de comando deste aplicativo de exemplo não incluir --endpoint
, uma mensagem de erro será exibida e o manipulador de comandos não será chamado:
Option '--endpoint' is required.
Se uma opção necessária tiver um valor padrão, a opção não precisa ser especificada na linha de comando. Nesse caso, o valor padrão fornece o valor de opção necessário.
Talvez você queira oferecer suporte a um comando, opção ou argumento, mas evite facilitar a descoberta. Por exemplo, pode ser um recurso preterido, administrativo ou de visualização. Use a IsHidden propriedade para impedir que os usuários descubram esses recursos usando o preenchimento de guias ou a ajuda, conforme mostrado no exemplo a seguir:
var endpointOption = new Option<Uri>("--endpoint") { IsHidden = true };
var command = new RootCommand();
command.Add(endpointOption);
command.SetHandler((uri) =>
{
Console.WriteLine(uri?.GetType());
Console.WriteLine(uri?.ToString());
},
endpointOption);
await command.InvokeAsync(args);
A seção options da ajuda de comando deste exemplo omite a --endpoint
opção.
Options:
--version Show version information
-?, -h, --help Show help and usage information
Você pode definir explicitamente a aridade do argumento usando a Arity
propriedade, mas na maioria dos casos isso não é necessário. System.CommandLine
determina automaticamente a aridade do argumento com base no tipo de argumento:
Tipo de argumento | Aridade padrão |
---|---|
Boolean |
ArgumentArity.ZeroOrOne |
Tipos de recolha | ArgumentArity.ZeroOrMore |
Tudo o resto | ArgumentArity.ExactlyOne |
Por padrão, quando você chama um comando, pode repetir um nome de opção para especificar vários argumentos para uma opção que tenha aridade máxima maior que um.
myapp --items one --items two --items three
Para permitir vários argumentos sem repetir o nome da opção, defina Option.AllowMultipleArgumentsPerToken como true
. Essa configuração permite que você insira a seguinte linha de comando.
myapp --items one two three
A mesma configuração tem um efeito diferente se a aridade máxima do argumento for 1. Ele permite que você repita uma opção, mas leva apenas o último valor na linha. No exemplo a seguir, o valor three
seria passado para o aplicativo.
myapp --item one --item two --item three
Para especificar uma lista de valores válidos para uma opção ou argumento, especifique um enum como o tipo de opção ou use FromAmong, conforme mostrado no exemplo a seguir:
var languageOption = new Option<string>(
"--language",
"An option that that must be one of the values of a static list.")
.FromAmong(
"csharp",
"fsharp",
"vb",
"pwsh",
"sql");
Aqui está um exemplo de entrada de linha de comando e a saída resultante para o código de exemplo anterior:
myapp --language not-a-language
Argument 'not-a-language' not recognized. Must be one of:
'csharp'
'fsharp'
'vb'
'pwsh'
'sql'
A seção de opções da ajuda do comando mostra os valores válidos:
Options:
--language <csharp|fsharp|vb|pwsh|sql> An option that must be one of the values of a static list.
--version Show version information
-?, -h, --help Show help and usage information
Para obter informações sobre validação de argumentos e como personalizá-la, consulte as seguintes seções no artigo Vinculação de parâmetros:
Comentários do .NET
O .NET é um projeto código aberto. Selecione um link para fornecer comentários:
Formação
Percurso de aprendizagem
Criar métodos em aplicativos de console C# (Introdução ao C#, Parte 5) - Training
Este caminho de aprendizagem abrange a sintaxe de criação e uso de métodos em aplicativos de console C#.