Tutorial: Creación de una herramienta .NET mediante la CLI de .NET

Este artículo se aplica a: ✔️ sdk de .NET 8 y versiones posteriores

En este tutorial se explica cómo crear y empaquetar una herramienta .NET. La CLI de .NET le permite crear una aplicación de consola como herramienta, que otras pueden instalar y ejecutar. Las herramientas de .NET son paquetes NuGet que se instalan desde la CLI de .NET. Para obtener más información sobre las herramientas, consulte Introducción a las herramientas de .NET.

La herramienta que va a crear es una aplicación de consola que toma información sobre el entorno de .NET actual y la muestra, incluida la versión de .NET, los detalles del sistema operativo y la configuración de variables de entorno clave.

Este tutorial es el primero en una serie de tres tutoriales. En este tutorial, crea y empaqueta una herramienta. En los dos tutoriales siguientes, usará la herramienta como herramienta global y usará la herramienta como herramienta local. Los procedimientos para crear una herramienta son los mismos si se usa como una herramienta global o como una herramienta local.

Prerrequisitos

  • .NET SDK 10.0 o una versión posterior.

    En este tutorial se usa .NET SDK 10.0, pero esta guía se aplica a .NET 8.0 y versiones posteriores.

  • El editor de texto o de código que elija.

Creación de un proyecto

  1. Abra un símbolo del sistema y cree una carpeta denominada repositorio.

  2. Vaya a la carpeta del repositorio y escriba el siguiente comando:

    dotnet new console -n dotnet-env

    El comando crea una nueva carpeta denominada dotnet-env en la carpeta del repositorio .

  3. Vaya a la carpeta dotnet-env .

    cd dotnet-env

Agregar el código

  1. Abra el archivo Program.cs con el editor de código.

  2. Reemplace el contenido por el código siguiente:

    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)"}");
}

    El programa usa instrucciones de nivel superior para leer la versión informativa del ensamblado mediante Assembly.GetEntryAssembly() y AssemblyInformationalVersionAttribute, luego imprime el nombre de la aplicación y una línea separadora antes de mostrar tres secciones de información:

    • Runtime: la versión de .NET, la descripción del marco y el identificador en tiempo de ejecución, mediante Environment.Version y RuntimeInformation.
    • Sistema : descripción del sistema operativo, arquitectura, nombre de máquina y recuento de procesadores.
    • Variables de entorno: seis variables clave relacionadas con .NET (DOTNET_ROOT, DOTNET_HOST_PATH, DOTNET_CLI_HOME, DOTNET_NOLOGO, NUGET_PACKAGES y DOTNET_ENVIRONMENT), mostrando (not set) para los que no estén configurados.

    La using System.Reflection directiva es necesaria para Assembly.GetEntryAssembly() y AssemblyInformationalVersionAttribute. La using System.Runtime.InteropServices directiva es necesaria para RuntimeInformation.

  3. Guarde los cambios.

Prueba de la aplicación

Ejecute el proyecto y vea la salida:

dotnet run

El resultado es similar al ejemplo siguiente:

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)

Nota:

Los valores que se muestran dependen de la máquina y .NET instalación. La salida varía según la plataforma.

Empaquetar la herramienta

Para empaquetar y distribuir la aplicación como una herramienta, modifique el archivo del proyecto.

  1. Abra el archivo dotnet-env.csproj y agregue tres nodos XML nuevos al final del <PropertyGroup> nodo:

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

    <ToolCommandName> es un elemento opcional que especifica el comando que invoca la herramienta después de la instalación. Si no se proporciona este elemento, el nombre del comando de la herramienta es el nombre del ensamblado, que suele ser el nombre de archivo del proyecto sin la extensión .csproj .

    Nota:

    Elija un valor único para <ToolCommandName>. Evite usar extensiones de archivo (como .exe o .cmd) porque la herramienta está instalada como host de aplicación y el comando no debe incluir una extensión. Esto ayuda a evitar conflictos con comandos existentes y garantiza una experiencia de instalación fluida.

    <PackageOutputPath> es un elemento opcional que determina dónde .NET genera el paquete NuGet. La CLI de .NET usa el paquete NuGet para instalar la herramienta.

    El archivo de proyecto ahora es similar al ejemplo siguiente:

    <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. Cree un paquete NuGet ejecutando el comando dotnet pack :

    dotnet pack

    El archivo dotnet-env.1.0.0.nupkg se crea en la carpeta identificada por el <PackageOutputPath> valor del archivo dotnet-env.csproj , que en este ejemplo es la carpeta ./nupkg .

    Para liberar una herramienta públicamente, cárguelo en https://www.nuget.org. Una vez que la herramienta esté disponible en NuGet, los desarrolladores pueden instalar la herramienta mediante el comando dotnet tool install . En este tutorial se instala el paquete directamente desde la carpeta nupkg local, por lo que no es necesario cargar el paquete en NuGet.

Solución de problemas

Si recibe un mensaje de error al seguir el tutorial, consulte Solución de problemas de uso de herramientas de .NET.

Pasos siguientes

En este tutorial, ha creado una aplicación de consola y la ha empaquetado como una herramienta. Para aprender a usar la herramienta como herramienta global, vaya al siguiente tutorial.

Instalación y uso de una herramienta global

Si lo prefiere, puede omitir el tutorial de herramientas globales y ir directamente al tutorial de herramientas locales.

Instalación y uso de una herramienta local

Consulte también

  • Last updated on