System.CommandLine 的 Tab 自动补全

项目
06/08/2023

重要

System.CommandLine 目前为预览版，本文档适用于版本 2.0 beta 4。一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。

使用 System.CommandLine 的应用在某些 shell 中内置了对 Tab 自动补全的支持。若要启用它，最终用户必须为每个 shell 执行一次相关步骤。用户执行此操作后，对于应用中的静态值（例如枚举值或通过调用 FromAmong 定义的值），会执行 Tab 自动补全。还可以在运行时动态获取值来自定义 Tab 自动补全。

启用 tab 自动补全

在要启用 Tab 自动补全功能的计算机上，执行以下步骤。

对于 .NET CLI：

请参阅如何启用 Tab 自动补全。

对于基于 System.CommandLine 构建的其他命令行应用：

安装 dotnet-suggest 全局工具。
将适当的填充码脚本添加到 shell 配置文件中。可能必须创建一个 shell 配置文件。填充码脚本将补全请求从 shell 转发到 dotnet-suggest 工具，其会委托到相应的基于 System.CommandLine 的应用。
- 对于 bash，将 dotnet-suggest-shim.bash 的内容添加到 ~/.bash_profile。
- 对于 zsh，将 dotnet-suggest-shim.zsh 的内容添加到 ~/.zshrc。
- 对于 PowerShell，将 dotnet-suggest-shim.ps1 的内容添加到 PowerShell 配置文件中。可以通过在控制台中运行以下命令来查找 PowerShell 配置文件的预期路径：
```
echo $profile
```

设置用户的 shell 后，补全操作将适用于使用 System.CommandLine 生成的所有应用。

对于 Windows 上的 cmd.exe（Windows 命令提示符），没有可插入的 Tab 自动补全机制，因此没有可用的填充码脚本。对于其他 shell，请查找标记为 Area-Completions 的 GitHub 问题。如果找不到问题，可以创建一个新问题。

运行时获取 Tab 自动补全值

以下代码显示在运行时 Tab 自动补全动态获取值的应用。该代码获取当前日期之后接下来两周的日期列表。通过调用 AddCompletions 向 --date 选项提供列表：

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

按下 Tab 键时显示的值作为 CompletionItem 实例提供：

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

设置以下 CompletionItem 属性：

Label 是要显示的补全值。
SortText 确保列表中的值按正确的顺序显示。它通过将 i 转换为两位数字符串进行设置，因此排序基于 01、02、03 等，一直到 14。如果未设置此参数，则排序基于 Label，此示例采用短日期格式，无法正确排序。

还有其他 CompletionItem 属性，如 Documentation 和 Detail，但它们尚未在 System.CommandLine 中使用。

此代码创建的动态 Tab 自动补全列表也显示在帮助输出中：

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

请参阅

System.CommandLine 概述

System.CommandLine 的 Tab 自动补全

启用 tab 自动补全

运行时获取 Tab 自动补全值

请参阅

反馈

其他资源