Compartir vía

Finalización con tabulación para System.CommandLine

  • Artículo

Importante

System.CommandLine se encuentra actualmente en versión preliminar y esta documentación es para la versión 2.0 beta 4. Parte de la información hace referencia a la versión preliminar del producto, que puede haberse modificado sustancialmente antes de lanzar la versión definitiva. Microsoft no otorga ninguna garantía, explícita o implícita, con respecto a la información proporcionada aquí.

Las aplicaciones que usan System.CommandLine tienen compatibilidad integrada con la finalización con tabulación en determinados shells. Para habilitarla, el usuario final debe seguir varios paso una vez por cada shell. Una vez que el usuario lo hace, la finalización con tabulación es automática para los valores estáticos de la aplicación, como los valores de enumeración o los valores que defina llamando a FromAmong. También puede personalizar la finalización con tabulación mediante la obtención de valores de forma dinámica en runtime.

Habilitación de la finalización con tabulación

En la máquina donde desea habilitar la finalización con tabulación, siga estos pasos.

Para la CLI de .NET:

Para otras aplicaciones de línea de comandos basadas en System.CommandLine:

  • Instale la herramienta global dotnet-suggest.

  • Agregue el script de correcciones de compatibilidad (shim) adecuado a su perfil de shell. Es posible que deba crear un archivo de perfil de shell. El script de correcciones de compatibilidad (shim) reenvía las solicitudes de finalización desde el shell a la herramienta dotnet-suggest, que delega a la aplicación basada en System.CommandLine adecuada.

    • Para bash, agregue el contenido de dotnet-suggest-shim.bash a ~/.bash_profile.

    • Para zsh, agregue el contenido de dotnet-suggest-shim.zsh a ~/.zshrc.

    • Para PowerShell, agregue el contenido del dotnet-suggest-shim.ps1 al perfil de PowerShell. Puede encontrar la ruta de acceso prevista para el perfil de PowerShell ejecutando el comando siguiente en la consola:

      echo $profile

Una vez configurado el shell del usuario, las finalizaciones funcionarán para todas las aplicaciones compiladas mediante System.CommandLine.

Para cmd.exe en Windows (el símbolo del sistema de Windows) no hay ningún mecanismo de finalización con tabulación que se pueda conectar, por lo que no hay ningún script de correcciones de compatibilidad (shim) disponible. Para otros shells, busque una incidencia de GitHub con la etiqueta Area-Completions. Si no encuentra ninguna, puede crear una nueva.

Obtención de valores de finalización con tabulación en tiempo de ejecución

El código siguiente muestra una aplicación que obtiene valores para la finalización con tabulación de forma dinámica en runtime. El código obtiene una lista de las próximas dos semanas de fechas siguientes a la fecha actual. La lista se proporciona a la opción --date llamando a AddCompletions:

using System.CommandLine;
using System.CommandLine.Completions;
using System.CommandLine.Parsing;

await new DateCommand().InvokeAsync(args);

class DateCommand : Command
{
    private Argument<string> subjectArgument = 
        new ("subject", "The subject of the appointment.");
    private Option<DateTime> dateOption = 
        new ("--date", "The day of week to schedule. Should be within one week.");
    
    public DateCommand() : base("schedule", "Makes an appointment for sometime in the next week.")
    {
        this.AddArgument(subjectArgument);
        this.AddOption(dateOption);

        dateOption.AddCompletions((ctx) => {
            var today = System.DateTime.Today;
            var dates = new List<CompletionItem>();
            foreach (var i in Enumerable.Range(1, 7))
            {
                var date = today.AddDays(i);
                dates.Add(new CompletionItem(
                    label: date.ToShortDateString(),
                    sortText: $"{i:2}"));
            }
            return dates;
        });

        this.SetHandler((subject, date) =>
            {
                Console.WriteLine($"Scheduled \"{subject}\" for {date}");
            },
            subjectArgument, dateOption);
    }
}

Los valores que se muestran cuando se presiona la tecla de tabulación se proporcionan como instancias CompletionItem:

dates.Add(new CompletionItem(
    label: date.ToShortDateString(),
    sortText: $"{i:2}"));

Las propiedades CompletionItem siguientes están establecidas:

  • Label es el valor de finalización que se va a mostrar.
  • SortText garantiza que los valores de la lista se presenten en el orden correcto. Se establece mediante la conversión de i en una cadena de dos dígitos, por lo que la organización se basa en 01, 02, 03, etc., hasta 14. Si no establece este parámetro, la organización se basa en Label, que en este ejemplo está en formato de fecha corta y no se ordenará de forma correcta.

Hay otras propiedades CompletionItem, como Documentation y Detail, pero aún no se usan en System.CommandLine.

La lista de finalización de tabulación dinámica creada por este código también aparece en la salida de la ayuda:

Description:
  Makes an appointment for sometime in the next week.

Usage:
  schedule <subject> [options]

Arguments:
  <subject>  The subject of the appointment.

Options:
  --date                                                                          The day of week to schedule. Should be within one week.
  <2/4/2022|2/5/2022|2/6/2022|2/7/2022|2/8/2022|2/9/2022|2/10/2022>
  --version                                                                       Show version information
  -?, -h, --help

Vea también

Información general de System.CommandLine