Tutorial: criar uma ferramenta .NET usando a CLI do .NET

Artigo
06/02/2023

Este artigo se aplica ao: ✔️ SDK do .NET Core 2.1 e versões posteriores

Este tutorial ensina como criar e empacotar uma ferramenta .NET. A CLI do .NET permite que você crie um aplicativo de console como uma ferramenta, que outras pessoas podem instalar e executar. As ferramentas .NET são pacotes NuGet instalados por meio da CLI do .NET. Para obter mais informações, confira Visão geral das ferramentas .NET.

A ferramenta que você criará é um aplicativo de console que usa uma mensagem como entrada e exibe a mensagem junto com linhas de texto que criam a imagem de um robô.

Este é o primeiro de uma série de três tutoriais. Neste tutorial, você cria e empacota uma ferramenta. Nos próximos dois tutoriais, você usa a ferramenta como uma ferramenta global e usa a ferramenta como uma ferramenta local. Os procedimentos para criar uma ferramenta são os mesmos, quer seja ela uma ferramenta global ou local.

Pré-requisitos

SDK do .NET 6.0.100 ou versão posterior.

Este tutorial usa o SDK do .NET 6.0, mas as ferramentas globais estão disponíveis do SDK do .NET Core 2.1 em diante. As ferramentas locais estão disponíveis do SDK do .NET Core 3.0 em diante.
Um editor de texto ou editor de código de sua escolha.

Criar um projeto

Abra um prompt de comando e crie uma pasta chamada repository.
Navegue até a pasta repository e insira o seguinte comando:
```
dotnet new console -n microsoft.botsay -f net6.0
```
O comando cria uma pasta chamada microsoft.botsay abaixo da pasta repository.
Observação

Neste tutorial, você cria uma ferramenta direcionada ao .NET 6.0. Para direcionar a outra estrutura, altere a opção -f|--framework. Para direcionar a várias estruturas, altere o elemento TargetFramework para um elemento TargetFrameworks no arquivo de projeto, conforme mostrado no seguinte exemplo:
```
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFrameworks>net8.0;net6.0</TargetFrameworks>
  </PropertyGroup>
</Project>
```
Navegue até a pasta microsoft.botsay.
```
cd microsoft.botsay
```

Adicionar o código

Abra o arquivo Program.cs com seu editor de código.

Substitua o código em Program.cs pelo código a seguir:

using System.Reflection;

namespace microsoft.botsay;

internal class Program
{
    static void Main(string[] args)
    {
        Console.WriteLine("Hello World!");
    }
}

A diretiva using System.Reflection; é necessária para o código que você adiciona na próxima etapa.

Substitua o método Main pelo código a seguir para processar os argumentos de linha de comando do aplicativo.

static void Main(string[] args)
{
    if (args.Length == 0)
    {
        var versionString = Assembly.GetEntryAssembly()?
                                .GetCustomAttribute<AssemblyInformationalVersionAttribute>()?
                                .InformationalVersion
                                .ToString();

        Console.WriteLine($"botsay v{versionString}");
        Console.WriteLine("-------------");
        Console.WriteLine("\nUsage:");
        Console.WriteLine("  botsay <message>");
        return;
    }

    ShowBot(string.Join(' ', args));
}

Se nenhum argumento for passado, uma breve mensagem de ajuda será exibida. Caso contrário, todos os argumentos serão concatenados em uma só cadeia de caracteres, e impressos chamando o método ShowBot que será criado na próxima etapa.

Adicione um novo método chamado ShowBot que usa um parâmetro de cadeia de caracteres. O método imprime a mensagem e uma imagem de um robô usando linhas de texto.

static void ShowBot(string message)
{
    string bot = $"\n        {message}";
    bot += @"
    __________________
                      \
                       \
                          ....
                          ....'
                           ....
                        ..........
                    .............'..'..
                 ................'..'.....
               .......'..........'..'..'....
              ........'..........'..'..'.....
             .'....'..'..........'..'.......'.
             .'..................'...   ......
             .  ......'.........         .....
             .    _            __        ......
            ..    #            ##        ......
           ....       .                 .......
           ......  .......          ............
            ................  ......................
            ........................'................
           ......................'..'......    .......
        .........................'..'.....       .......
     ........    ..'.............'..'....      ..........
   ..'..'...      ...............'.......      ..........
  ...'......     ...... ..........  ......         .......
 ...........   .......              ........        ......
.......        '...'.'.              '.'.'.'         ....
.......       .....'..               ..'.....
   ..       ..........               ..'........
          ............               ..............
         .............               '..............
        ...........'..              .'.'............
       ...............              .'.'.............
      .............'..               ..'..'...........
      ...............                 .'..............
       .........                        ..............
        .....
";
    Console.WriteLine(bot);
}

Salve suas alterações.

Testar o aplicativo

Execute o projeto e veja a saída. Experimente essas variações na linha de comando para ver resultados diferentes:

dotnet run
dotnet run -- "Hello from the bot"
dotnet run -- Hello from the bot

Todos os argumentos após o delimitador -- são passados para o aplicativo.

Empacotar a ferramenta

Antes de poder empacotar e distribuir o aplicativo como uma ferramenta, você precisa modificar o arquivo de projeto.

Abra o arquivo microsoft.botsay.csproj e adicione três novos nós XML ao final do nó <PropertyGroup>:
```
<PackAsTool>true</PackAsTool>
<ToolCommandName>botsay</ToolCommandName>
<PackageOutputPath>./nupkg</PackageOutputPath>
```
<ToolCommandName> é um elemento opcional que especifica o comando que invocará a ferramenta após a instalação. Se esse elemento não for fornecido, o nome do comando da ferramenta será o nome de assembly, que geralmente é o nome do arquivo de projeto sem a extensão .csproj.

<PackageOutputPath> é um elemento opcional que determina onde o pacote NuGet será produzido. O pacote NuGet é o que a CLI do .NET usa para instalar sua ferramenta.

O arquivo de projeto agora se parece com o seguinte exemplo:
```
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>

    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>

    <PackAsTool>true</PackAsTool>
    <ToolCommandName>botsay</ToolCommandName>
    <PackageOutputPath>./nupkg</PackageOutputPath>

  </PropertyGroup>

</Project>
```
Crie um pacote NuGet executando o comando dotnet pack:
```
dotnet pack
```
O arquivo microsoft.botsay.1.0.0.nupkg é criado na pasta identificada pelo valor <PackageOutputPath> do arquivo microsoft.botsay.csproj, que neste exemplo é a pasta ./nupkg.

Quando você quiser lançar uma ferramenta publicamente, poderá fazer upload dela em https://www.nuget.org. Depois que a ferramenta estiver disponível no NuGet, os desenvolvedores poderão instalar a ferramenta usando o comando dotnet tool install. Neste tutorial, você instala o pacote diretamente da pasta nupkg local, portanto, não é necessário carregar o pacote no NuGet.

Solucionar problemas

Se você receber uma mensagem de erro ao seguir o tutorial, confira Solucionar problemas de uso da ferramenta .NET.

Próximas etapas

Neste tutorial, você criou um aplicativo de console e o empacotou como uma ferramenta. Para saber como usá-la como uma ferramenta global, avance para o próximo tutorial.

Instalar e usar uma ferramenta global

Se preferir, ignore o tutorial de ferramentas globais e vá diretamente para o tutorial de ferramentas locais.

Instalar e usar uma ferramenta local