Partilhar via


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

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

Este tutorial ensina-o a criar e empacotar uma ferramenta .NET. A CLI de .NET permite-lhe criar uma aplicação de consola como uma ferramenta, que outras pessoas podem instalar e executar. As ferramentas .NET são pacotes NuGet que são instalados a partir da CLI do .NET. Para obter mais informações sobre ferramentas, veja Descrição geral das ferramentas .NET.

A ferramenta que irá criar é uma aplicação de consola que utiliza uma mensagem como entrada e apresenta a mensagem juntamente com linhas de texto que criam a imagem de um robô.

Este é o primeiro de uma série de três tutoriais. Neste tutorial, vai criar e empacotar uma ferramenta. Nos dois tutoriais seguintes , utilize a ferramenta como uma ferramenta global e utilize a ferramenta como uma ferramenta local. Os procedimentos para criar uma ferramenta são os mesmos, quer a utilize como uma ferramenta global ou como uma ferramenta local.

Pré-requisitos

  • SDK .NET 6.0.100 ou uma versão posterior.

    Este tutorial utiliza o SDK .NET 6.0, mas as ferramentas globais estão disponíveis a partir do SDK .NET Core 2.1. As ferramentas locais estão disponíveis a partir do SDK .NET Core 3.0.

  • Um editor de texto ou editor de código da sua preferência.

Criar um projeto

  1. Abra uma linha de comandos e crie uma pasta com o nome repositório.

  2. Navegue para a pasta do repositório e introduza o seguinte comando:

    dotnet new console -n microsoft.botsay -f net6.0
    

    O comando cria uma nova pasta com o nome microsoft.botsay na pasta do repositório .

    Nota

    Neste tutorial, vai criar uma ferramenta que visa o .NET 6.0. Para direcionar uma arquitetura diferente, altere a opção -f|--framework . Para direcionar várias arquiteturas, altere o TargetFramework elemento para um TargetFrameworks elemento no ficheiro de projeto, conforme mostrado no exemplo seguinte:

    <Project Sdk="Microsoft.NET.Sdk">
      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFrameworks>net8.0;net6.0</TargetFrameworks>
      </PropertyGroup>
    </Project>
    
  3. Navegue para a pasta microsoft.botsay .

    cd microsoft.botsay
    

Adicionar o código

  1. Abra o ficheiro Program.cs com o editor de código.

  2. 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 adicionar no passo seguinte.

  3. Substitua o Main método pelo seguinte código para processar os argumentos da linha de comandos da aplicação.

    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 não forem transmitidos argumentos, será apresentada uma breve mensagem de ajuda. Caso contrário, todos os argumentos são concatenados numa única cadeia e impressos ao chamar o ShowBot método que criar no passo seguinte.

  4. Adicione um novo método com o nome ShowBot que utiliza um parâmetro de cadeia. O método imprime a mensagem e uma imagem de um robô com linhas de texto.

    static void ShowBot(string message)
    {
        string bot = $"\n        {message}";
        bot += @"
        __________________
                          \
                           \
                              ....
                              ....'
                               ....
                            ..........
                        .............'..'..
                     ................'..'.....
                   .......'..........'..'..'....
                  ........'..........'..'..'.....
                 .'....'..'..........'..'.......'.
                 .'..................'...   ......
                 .  ......'.........         .....
                 .    _            __        ......
                ..    #            ##        ......
               ....       .                 .......
               ......  .......          ............
                ................  ......................
                ........................'................
               ......................'..'......    .......
            .........................'..'.....       .......
         ........    ..'.............'..'....      ..........
       ..'..'...      ...............'.......      ..........
      ...'......     ...... ..........  ......         .......
     ...........   .......              ........        ......
    .......        '...'.'.              '.'.'.'         ....
    .......       .....'..               ..'.....
       ..       ..........               ..'........
              ............               ..............
             .............               '..............
            ...........'..              .'.'............
           ...............              .'.'.............
          .............'..               ..'..'...........
          ...............                 .'..............
           .........                        ..............
            .....
    ";
        Console.WriteLine(bot);
    }
    
  5. Guarde as alterações.

Testar a aplicação

Execute o projeto e veja o resultado. Experimente estas variações na linha de comandos 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 serem transmitidos para a sua aplicação.

Empacotar a ferramenta

Antes de poder empacotar e distribuir a aplicação como uma ferramenta, tem de modificar o ficheiro do projeto.

  1. Abra o ficheiro microsoft.botsay.csproj e adicione três novos nós XML ao final do <PropertyGroup> nó:

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

    <ToolCommandName> é um elemento opcional que especifica o comando que invocará a ferramenta depois de ser instalada. Se este elemento não for fornecido, o nome do comando da ferramenta é o nome da assemblagem, que é normalmente o nome do ficheiro do 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 de .NET utiliza para instalar a sua ferramenta.

    O ficheiro de projeto tem agora o seguinte aspeto:

    <Project Sdk="Microsoft.NET.Sdk">
    
      <PropertyGroup>
    
        <OutputType>Exe</OutputType>
        <TargetFramework>net6.0</TargetFramework>
    
        <PackAsTool>true</PackAsTool>
        <ToolCommandName>botsay</ToolCommandName>
        <PackageOutputPath>./nupkg</PackageOutputPath>
    
      </PropertyGroup>
    
    </Project>
    
  2. Crie um pacote NuGet ao executar o comando dotnet pack :

    dotnet pack
    

    O ficheiro microsoft.botsay.1.0.0.nupkg é criado na pasta identificada pelo <PackageOutputPath> valor do ficheiro microsoft.botsay.csproj , que neste exemplo é a pasta ./nupkg .

    Quando quiser lançar uma ferramenta publicamente, pode carregá-la para https://www.nuget.org. Assim que a ferramenta estiver disponível no NuGet, os programadores podem instalar a ferramenta com o comando de instalação da ferramenta dotnet . Neste tutorial, vai instalar o pacote diretamente a partir da pasta nupkg local, pelo que não é necessário carregar o pacote para o NuGet.

Resolução de problemas

Se receber uma mensagem de erro ao seguir o tutorial, veja Resolver problemas de utilização da ferramenta .NET.

Passos seguintes

Neste tutorial, criou uma aplicação de consola e empacotou-a como uma ferramenta. Para saber como utilizar a ferramenta como uma ferramenta global, avance para o próximo tutorial.

Se preferir, pode ignorar o tutorial de ferramentas globais e aceder diretamente ao tutorial de ferramentas locais.