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

Este artigo aplica-se a: ✔️ .NET 8 SDK 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 irá criar é uma aplicação de consola que recolhe informações sobre o ambiente .NET atual e as apresenta, incluindo a versão .NET, detalhes do sistema operativo e definições chave de variáveis do ambiente.

Este tutorial é o primeiro de uma série de três tutoriais. Neste tutorial, você cria e empacota uma ferramenta. Nos dois tutoriais seguintes, usas a ferramenta como uma ferramenta global e usas 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 10.0 ou uma versão posterior.

    Este tutorial utiliza o .NET SDK 10.0, mas aplica-se ao .NET 8.0 e versões posteriores.

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

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 digite o seguinte comando:

    dotnet new console -n dotnet-env

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

  3. Navegue até à pasta dotnet-env .

    cd dotnet-env

Adicionar o código

  1. Abra o arquivo Program.cs com seu 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 utiliza instruções de topo para ler a versão informativa da assembleia usando Assembly.GetEntryAssembly() e AssemblyInformationalVersionAttribute, depois imprime o nome da aplicação e uma linha separadora antes de mostrar três secções de informação:

    • Runtime — a versão .NET, descrição do framework e identificador de runtime, usando Environment.Version e RuntimeInformation.
    • Sistema — Descrição do sistema operativo, arquitetura, nome da máquina e número de processadores.
    • Variáveis de ambiente — seis variáveis-chave relacionadas com .NET (DOTNET_ROOT, DOTNET_HOST_PATH, DOTNET_CLI_HOME, DOTNET_NOLOGO, NUGET_PACKAGES e DOTNET_ENVIRONMENT), mostrando (not set) para quaisquer que não estejam configuradas.

    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 a aplicação

Executa o projeto e vê o resultado:

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 da sua máquina e da instalação .NET. A saída varia consoante a plataforma.

Empacotar a ferramenta

Para empacotar e distribuir a aplicação como uma ferramenta, modifique o ficheiro do projeto.

  1. Adicione três novos nós XML ao final do nó <PropertyGroup> após abrir o ficheiro dotnet-env.csproj.

    <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 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 ficheiros (como .exe ou .cmd) porque a ferramenta está instalada como anfitriã de aplicação 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 .NET produz o pacote NuGet. A CLI .NET usa o pacote NuGet para instalar a sua ferramenta.

    O arquivo de projeto agora se parece com o exemplo a seguir:

    <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 ficheiro dotnet-env.1.0.0.nupkg é criado na pasta identificada pelo <PackageOutputPath> valor do ficheiro dotnet-env.csproj , que neste exemplo é a pasta ./nupkg .

    Para lançar uma ferramenta publicamente, carregue-a em https://www.nuget.org. Uma vez que a ferramenta esteja disponível no NuGet, os programadores podem instalá-la usando o comando de instalação da ferramenta dotnet . 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

Consulte também

  • Last updated on