Compartir a través de


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

Este artículo se aplica a: ✔️ SDK de .NET Core 2.1 y versiones posteriores

En este tutorial se explica cómo crear y empaquetar una herramienta de .NET. La CLI de .NET permite crear una aplicación de consola como una herramienta, que otros usuarios 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, vea Información general sobre las herramientas de .NET.

La herramienta que se va a crear es una aplicación de consola que toma un mensaje como entrada y muestra el mensaje junto con líneas de texto que crean la imagen de un robot.

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

Requisitos previos

  • SDK de .NET 6.0.100 o una versión posterior.

    En este tutorial se usa el SDK de .NET 6.0, pero las herramientas globales están disponibles a partir del SDK de .NET Core 2.1. Las herramientas locales están disponibles a partir del SDK de .NET Core 3.0.

  • Un editor de texto o un editor de código de su elección.

Crear un proyecto

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

  2. Desplácese hasta la carpeta repository y escriba el comando siguiente:

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

    El comando crea una carpeta denominada microsoft.botsay en la carpeta repository.

    Nota:

    En este tutorial, se crea una herramienta que tiene como destino .NET 6.0. Para que el destino sea otra plataforma, cambie la opción -f|--framework. Para que el destino sean varias plataformas, cambie el elemento TargetFramework a un elemento TargetFrameworks en el archivo de proyecto, como se muestra en el ejemplo siguiente:

    <Project Sdk="Microsoft.NET.Sdk">
      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFrameworks>net8.0;net6.0</TargetFrameworks>
      </PropertyGroup>
    </Project>
    
  3. Navegue hasta la carpeta microsoft.botsay.

    cd microsoft.botsay
    

Agregar el código

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

  2. Reemplace el código de Program.cs por el código siguiente:

    using System.Reflection;
    
    namespace microsoft.botsay;
    
    internal class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Hello World!");
        }
    }
    

    El código que agregue en el paso siguiente necesitará la directiva using System.Reflection;.

  3. Reemplace el método Main con el siguiente código para procesar los argumentos de la línea de comandos para la aplicación.

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

    Si no se pasó ningún argumento, se muestra un mensaje de ayuda breve. De lo contrario, todos los argumentos se concatenan en una sola cadena y se imprimen llamando al método ShowBot que se crea en el paso siguiente.

  4. Agregue un nuevo método denominado ShowBot que toma un parámetro de cadena. El método imprime el mensaje y una imagen de un robot usando líneas de texto.

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

Probar la aplicación

Ejecute el proyecto y observe la salida. Pruebe estas variaciones en la línea de comandos para ver resultados diferentes:

dotnet run
dotnet run -- "Hello from the bot"
dotnet run -- Hello from the bot

Todos los argumentos después del delimitador -- se pasan a la aplicación.

Empaquetado de la herramienta

Antes de que pueda empaquetar y distribuir la aplicación como una herramienta, debe modificar el archivo de proyecto.

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

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

    <ToolCommandName> es un elemento opcional que especifica el comando que invocará a la herramienta una vez instalada. Si no se proporciona este elemento, el nombre de comando para la herramienta es el nombre de ensamblado, que suele ser el nombre del archivo de proyecto sin la extensión .csproj.

    <PackageOutputPath> es un elemento opcional que determina dónde se generará el paquete NuGet. El paquete NuGet es el que la CLI de .NET utiliza para instalar la herramienta.

    El archivo del proyecto debe ser similar al siguiente ejemplo:

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

    dotnet pack
    

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

    Si quiere lanzar una herramienta públicamente, puede cargarla 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 instalará el paquete directamente desde la carpeta local nupkg, por lo que no es necesario cargar el paquete en NuGet.

Solucionar problemas

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

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 una herramienta global, avance al siguiente tutorial.

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