Finalización de tabulación para System.CommandLine

Importante

System.CommandLine actualmente está en versión preliminar y esta documentación es para la versión 2.0 beta 5. Cierta información se relaciona con el producto de versión preliminar que puede modificarse sustancialmente antes de su lanzamiento. Microsoft no ofrece ninguna garantía, expresa o implícita, con respecto a la información proporcionada aquí.

Las aplicaciones que usan System.CommandLine tienen compatibilidad integrada con la finalización de tabulaciones en determinados shells. Para habilitarlo, el usuario final debe realizar algunos pasos una vez por shell. Una vez hecho esto, la finalización de tabulación es automática para los valores estáticos de la aplicación, como valores de enumeración o valores definidos mediante una llamada a System.CommandLine.Option<T>.AcceptOnlyFromAmong. También puede personalizar la finalización de tabulación proporcionando valores dinámicamente en tiempo de ejecución.

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

En el equipo en el que desea habilitar la finalización de pestañas, siga estos pasos.

Para la CLI de .NET:

• Consulte Habilitación de la finalización de pestañas.

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

• Instale la dotnet-suggest herramienta global.

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

  • 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 de dotnet-suggest-shim.ps1 al perfil de PowerShell. Para encontrar la ruta de acceso esperada al perfil de PowerShell, ejecute el siguiente comando en la consola:

    echo $profile
    

• Registre la aplicación llamando a dotnet-suggest register --command-path $executableFilePath, donde $executableFilePath es la ruta de acceso al archivo ejecutable de la aplicación.

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

Para cmd.exe en Windows (símbolo del sistema de Windows) no hay ningún mecanismo de finalización de tabulación conectable, por lo que no hay ningún script de correcciones de compatibilidad disponible. Para otros shells, busque un problema de GitHub con la etiqueta Area-Completions. Si no encuentra ningún problema, puede abrir uno nuevo.

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

El código siguiente muestra una aplicación que recupera valores para la finalización de tabulaciones dinámicamente en tiempo de ejecución. El código obtiene una lista de las dos próximas semanas de fechas después de la fecha actual. La lista se proporciona a la --date opción llamando a CompletionSources.Add:

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

new DateCommand().Parse(args).Invoke();

class DateCommand : Command
{
    private Argument<string> subjectArgument = new("subject")
    {
        Description = "The subject of the appointment."
    };
    private Option<DateTime> dateOption = new("--date")
    {
        Description = "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.Arguments.Add(subjectArgument);
        this.Options.Add(dateOption);

        dateOption.CompletionSources.Add(ctx => {
            var today = System.DateTime.Today;
            List<CompletionItem> dates = new();
            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.SetAction(parseResult =>
        {
            Console.WriteLine($"Scheduled \"{parseResult.GetValue(subjectArgument)}\" for {parseResult.GetValue(dateOption)}");
        });
    }
}

Los valores que se muestran cuando se presiona la tecla Tab se proporcionan como CompletionItem instancias:

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

Se establecen las siguientes CompletionItem propiedades:

• Label es el valor de finalización que se va a mostrar.
• SortText garantiza que los valores de la lista se presentan en el orden correcto. Se establece convirtiendo i en una cadena de dos dígitos, por lo que la ordenación se basa en 01, 02, 03, etc., hasta 14. Si no establece este parámetro, la ordenación se basa en , Labelque en este ejemplo tiene un formato de fecha corta y no se ordenará correctamente.

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

La lista de finalización de pestañas dinámicas 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

Consulte también

System.CommandLine visión general