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

Esso artigo se aplica a: ✔️ .NET 8 SDK 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 do .NET são pacotes NuGet instalados da CLI do .NET. Para obter mais informações sobre ferramentas, consulte a visão geral das ferramentas do .NET.

A ferramenta que você criará é um aplicativo de console que obtém informações sobre o ambiente de .NET atual e o exibe, incluindo a versão .NET, os detalhes do sistema operacional e as principais configurações de variável de ambiente.

Este tutorial é o primeiro de uma série de três tutoriais. Neste tutorial, você cria e empacota uma ferramenta. Nos próximos dois tutoriais, você usará a ferramenta como uma ferramenta global e usará a ferramenta como uma ferramenta local. Os procedimentos para criar uma ferramenta são os mesmos se você usá-la como uma ferramenta global ou como uma ferramenta local.

Pré-requisitos

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

    Este tutorial usa .NET SDK 10.0, mas este guia se aplica a .NET 8.0 e posteriores.

  • Um editor de texto ou editor de código de sua escolha.

Criar um projeto

  1. Abra um prompt de comando e crie uma pasta chamada repositório.

  2. Navegue até a pasta do repositório e insira o seguinte comando:

    dotnet new console -n dotnet-env

    O comando cria uma nova pasta chamada dotnet-env na pasta do repositório .

  3. Navegue até a pasta dotnet-env .

    cd dotnet-env

Adicionar o código

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

  2. Substitua o conteúdo pelo seguinte código:

    using System.Reflection;
using System.Runtime.InteropServices;

var versionString = Assembly.GetEntryAssembly()?
                        .GetCustomAttribute<AssemblyInformationalVersionAttribute>()?
                        .InformationalVersion
                        .ToString();

Console.WriteLine($"dotnet-env v{versionString}");
Console.WriteLine(new string('-', 40));

Console.WriteLine();
Console.WriteLine("Runtime");
Console.WriteLine($"  .NET Version          {Environment.Version}");
Console.WriteLine($"  Framework             {RuntimeInformation.FrameworkDescription}");
Console.WriteLine($"  Runtime Identifier    {RuntimeInformation.RuntimeIdentifier}");

Console.WriteLine();
Console.WriteLine("System");
Console.WriteLine($"  OS                    {RuntimeInformation.OSDescription}");
Console.WriteLine($"  Architecture          {RuntimeInformation.OSArchitecture}");
Console.WriteLine($"  Machine Name          {Environment.MachineName}");
Console.WriteLine($"  Processor Count       {Environment.ProcessorCount}");

Console.WriteLine();
Console.WriteLine("Environment Variables");
string[] envVars = { "DOTNET_ROOT", "DOTNET_HOST_PATH",
                        "DOTNET_CLI_HOME", "DOTNET_NOLOGO",
                        "NUGET_PACKAGES", "DOTNET_ENVIRONMENT" };

foreach (string name in envVars)
{
    string? value = Environment.GetEnvironmentVariable(name);
    Console.WriteLine($"  {name,-24}{value ?? "(not set)"}");
}

    O programa usa instruções de nível superior para ler a versão informativa do assembly usando Assembly.GetEntryAssembly() e AssemblyInformationalVersionAttribute, em seguida, imprime o nome do aplicativo e uma linha do separador antes de exibir três seções de informações:

    • Runtime — a versão .NET, a descrição da estrutura e o identificador de runtime, usando Environment.Version e RuntimeInformation.
    • Sistema – descrição do sistema operacional, arquitetura, nome do computador e contagem de processadores.
    • variáveis de ambiente Environment — seis variáveis principais relacionadas a .NET (DOTNET_ROOT, DOTNET_HOST_PATH, DOTNET_CLI_HOME, DOTNET_NOLOGO, NUGET_PACKAGES e DOTNET_ENVIRONMENT), mostrando (not set) para qualquer uma que não esteja configurada.

    A using System.Reflection diretiva é necessária para Assembly.GetEntryAssembly() e AssemblyInformationalVersionAttribute. A using System.Runtime.InteropServices diretiva é necessária para RuntimeInformation.

  3. Salve suas alterações.

Testar o aplicativo

Execute o projeto e veja a saída:

dotnet run

A saída é semelhante ao exemplo a seguir:

dotnet-env v1.0.0
----------------------------------------

Runtime
  .NET Version          10.0.4
  Framework             .NET 10.0.4
  Runtime Identifier    win-x64

System
  OS                    Microsoft Windows 10.0.22631
  Architecture          X64
  Machine Name          MY-MACHINE
  Processor Count       16

Environment Variables
  DOTNET_ROOT             (not set)
  DOTNET_HOST_PATH        (not set)
  DOTNET_CLI_HOME         (not set)
  DOTNET_NOLOGO           (not set)
  NUGET_PACKAGES          (not set)
  DOTNET_ENVIRONMENT      (not set)

Observação

Os valores mostrados dependem do computador e .NET instalação. A saída varia de acordo com a plataforma.

Empacotar a ferramenta

Para empacotar e distribuir o aplicativo como uma ferramenta, modifique o arquivo de projeto.

  1. Abra o arquivo dotnet-env.csproj e adicione três novos nós XML ao final do nó <PropertyGroup>:

    <PackAsTool>true</PackAsTool>
<ToolCommandName>dotnet-env</ToolCommandName>
<PackageOutputPath>./nupkg</PackageOutputPath>

    <ToolCommandName> é um elemento opcional que especifica o comando que invoca a ferramenta após a instalação. Se esse elemento não for fornecido, o nome do comando da ferramenta será o nome do assembly, que normalmente é o nome do arquivo de 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 está instalada como um host de aplicativo e o comando não deve incluir uma extensão. Isso ajuda a evitar conflitos com os comandos existentes e garante uma experiência de instalação tranquila.

    <PackageOutputPath> é um elemento opcional que determina onde .NET produz o pacote NuGet. A CLI do .NET usa o pacote NuGet 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>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>

    <PackAsTool>true</PackAsTool>
    <ToolCommandName>dotnet-env</ToolCommandName>
    <PackageOutputPath>./nupkg</PackageOutputPath>

  </PropertyGroup>

</Project>

  2. Crie um pacote NuGet executando o comando dotnet pack :

    dotnet pack

    O arquivo dotnet-env.1.0.0.nupkg é criado na pasta identificada pelo <PackageOutputPath> valor do arquivo dotnet-env.csproj , que neste exemplo é a pasta ./nupkg .

    Para liberar uma ferramenta publicamente, carregue-a para https://www.nuget.org. Depois que a ferramenta estiver disponível no NuGet, os desenvolvedores poderão instalar a ferramenta usando o comando de instalação da ferramenta dotnet . Para este tutorial, instale 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 usar a ferramenta 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

Consulte também

  • Last updated on