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

Este artigo aplica-se a: ✔️ 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 criar um aplicativo de console como uma ferramenta, que outras pessoas podem instalar e executar. As ferramentas .NET são pacotes NuGet instalados a partir da CLI do .NET. Para obter mais informações sobre ferramentas, consulte 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 você a use como uma ferramenta global ou como uma ferramenta local.

Pré-requisitos

.NET SDK 6.0.100 ou uma versão posterior.

Este tutorial usa o .NET SDK 6.0, mas as ferramentas globais estão disponíveis a partir do .NET Core SDK 2.1. As ferramentas locais estão disponíveis a partir do .NET Core SDK 3.0.
Um editor de texto ou editor de código da sua preferência.

Criar um projeto

Abra um prompt de comando e crie uma pasta chamada repositório.
Navegue até a pasta do repositório e digite o seguinte comando:
```
dotnet new console -n microsoft.botsay -f net6.0
```
O comando cria uma nova pasta chamada microsoft.botsay na pasta do repositório .
Observação

Para este tutorial, você cria uma ferramenta destinada ao .NET 6.0. Para direcionar uma estrutura diferente, altere a -f|--framework opção. Para direcionar várias estruturas, altere o TargetFramework elemento para um TargetFrameworks elemento no arquivo de projeto, conforme mostrado no exemplo a seguir:
```
<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 seguinte código:

using System.Reflection;

namespace microsoft.botsay;

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

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

Substitua o Main método com o código a seguir para processar os argumentos de linha de comando para o 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 são concatenados numa única string e exibidos chamando o ShowBot método que você cria na próxima etapa.

Adicione um novo método chamado ShowBot que usa um parâmetro string. 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 a aplicação

Execute o projeto e veja a saída. Experimente estas 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 seu 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 no 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 depois de instalada. Se esse elemento não for fornecido, o nome do comando para a ferramenta será o nome do assembly, que normalmente é o nome do arquivo do projeto sem a extensão .csproj .

Observação

Escolha um valor exclusivo para <ToolCommandName>. Evite usar extensões de arquivo (como .exe ou .cmd) porque a ferramenta é instalada como um host de aplicativo e o comando não deve incluir uma extensão. Isso ajuda a evitar conflitos com comandos existentes e garante uma experiência de instalação suave.

<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 exemplo a seguir:
```
<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 <PackageOutputPath> valor do arquivo microsoft.botsay.csproj , que neste exemplo é a pasta ./nupkg .

Quando quiser lançar uma ferramenta publicamente, pode carregá-la para https://www.nuget.org. Quando a ferramenta estiver disponível no NuGet, os desenvolvedores poderão instalá-la usando o comando dotnet tool install . Para este tutorial, você instala o pacote diretamente da pasta nupkg local, portanto, não há necessidade de carregar o pacote no NuGet.

Solucionar problemas

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

Próximos passos

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

Instalar e usar uma ferramenta global

Se preferir, você pode pular o tutorial de ferramentas globais e ir diretamente para o tutorial de ferramentas locais.

Instalar e usar uma ferramenta local