Cómo usar System.CommandLine en C#

System.CommandLine es una biblioteca de .NET para definir y procesar comandos, opciones y argumentos en aplicaciones de consola.

Además del análisis de la entrada, permite generar ayuda, validar valores y organizar subcomandos sin mantener manualmente un parser basado en string[] args.

Instalar System.CommandLine

Para empezar a usar System.CommandLine, es necesario instalar el paquete NuGet correspondiente. Esto se puede hacer de la siguiente manera:

dotnet add package System.CommandLine

Crear un comando básico

Una de las principales ventajas de System.CommandLine es su capacidad para definir comandos de manera estructurada. A continuación, se presenta un ejemplo básico de cómo definir y ejecutar un comando con esta biblioteca:

Ejemplo básico

using System.CommandLine;

class Program
{
    static int Main(string[] args)
    {
        Option<string> nameOption = new("--name")
        {
            Description = "Tu nombre",
            Required = true
        };

        RootCommand rootCommand = new("Aplicación de ejemplo");
        rootCommand.Options.Add(nameOption);
        rootCommand.SetAction(parseResult =>
        {
            string name = parseResult.GetValue(nameOption)!;
            Console.WriteLine($"Hola, {name}!");
        });

        return rootCommand.Parse(args).Invoke();
    }
}

Ejecución

Si ejecutamos el programa con los siguientes argumentos:

miaplicacion.exe --name Carlos

La salida será:

Hola, Carlos!

Este ejemplo básico muestra cómo crear un comando sencillo con una opción que acepta un argumento. System.CommandLine maneja la validación de los argumentos y su análisis de manera eficiente.

Trabajar con subcomandos

En aplicaciones más complejas, es probable que necesitemos subcomandos para organizar las operaciones. Los subcomandos permiten crear comandos jerárquicos, donde un comando principal puede tener varios subcomandos asociados.

Ejemplo con subcomandos

using System.CommandLine;

class Program
{
    static int Main(string[] args)
    {
        Option<string> greetName = new("--name") { Required = true };
        Command greet = new("greet", "Saludar a un usuario") { greetName };
        greet.SetAction(result =>
            Console.WriteLine($"Hola, {result.GetValue(greetName)}!"));

        Option<string> farewellName = new("--name") { Required = true };
        Command farewell = new("farewell", "Despedirse de un usuario") { farewellName };
        farewell.SetAction(result =>
            Console.WriteLine($"Adiós, {result.GetValue(farewellName)}!"));

        RootCommand rootCommand = new("Aplicación con subcomandos");
        rootCommand.Subcommands.Add(greet);
        rootCommand.Subcommands.Add(farewell);

        return rootCommand.Parse(args).Invoke();
    }
}

Explicación del código

1. Definición de subcomandos: Hemos añadido dos subcomandos al RootCommand: greet y farewell, cada uno con una opción --name.

2. Asignación de acciones: Cada subcomando tiene una acción que define su comportamiento, como saludar o despedirse del usuario.

Ejecución

Si ejecutamos el programa con el siguiente comando:

miaplicacion.exe greet --name Carlos

La salida será:

Hola, Carlos!

Si ejecutamos el subcomando farewell:

miaplicacion.exe farewell --name Carlos

La salida será:

Adiós, Carlos!

Este ejemplo demuestra cómo manejar subcomandos, lo que es útil para crear aplicaciones más estructuradas y organizadas.

Validación y conversión de tipos

System.CommandLine también ofrece funcionalidades avanzadas como validación de argumentos y conversión de tipos. Por ejemplo, podemos validar que un argumento sea un número o que se ajuste a un formato específico.

Ejemplo de validación

using System.CommandLine;
class Program
{
    static int Main(string[] args)
    {
        Option<int> num1Option = new("--num1") { Required = true };
        Option<int> num2Option = new("--num2") { Required = true };

        Command command = new("calculate", "Calcular la suma de dos números")
        {
            num1Option,
            num2Option
        };
        command.SetAction(result =>
        {
            int num1 = result.GetValue(num1Option);
            int num2 = result.GetValue(num2Option);
            Console.WriteLine($"La suma es: {num1 + num2}");
        });

        RootCommand rootCommand = new("Calculadora de ejemplo");
        rootCommand.Subcommands.Add(command);
        return rootCommand.Parse(args).Invoke();
    }
}

Ejecución

miaplicacion.exe calculate --num1 5 --num2 10

La salida será:

La suma es: 15

En este caso, System.CommandLine convierte automáticamente los valores de --num1 y --num2 a enteros. Si alguno no es válido, muestra un error antes de ejecutar la acción.

Autocompletado de comandos

Una característica avanzada de System.CommandLine es el autocompletado de comandos. Esta característica permite que los usuarios obtengan sugerencias automáticas mientras escriben los comandos y opciones en la línea de comandos. Esto es útil para mejorar la usabilidad y experiencia de usuario.

Para habilitar el autocompletado, es necesario configurar la funcionalidad correspondiente en el comando raíz y sus subcomandos, además de asegurarse de que la terminal que se utilice soporte esta característica.