选项卡完成 System.CommandLine

2025-06-21

重要

System.CommandLine 目前为预览版，本文档适用于版本 2.0 beta 5。某些信息与预发布产品有关，该产品在发布前可能会进行大幅修改。 Microsoft对此处提供的信息不作任何明示或暗示的保证。

某些 System.CommandLine shell 中使用内置支持选项卡完成的应用。若要启用它，最终用户必须按 shell 执行几个步骤。完成此作后，应用内的静态值会自动完成选项卡，例如通过调用 System.CommandLine.Option<T>.AcceptOnlyFromAmong定义的枚举值或值。还可以通过在运行时动态提供值来自定义选项卡完成。

启用Tab键补全

在想要启用选项卡完成的计算机上，执行以下步骤。

对于 .NET CLI：

请参阅 “如何启用选项卡完成”。

对于基于以下方法 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
```
通过调用 dotnet-suggest register --command-path $executableFilePath注册应用，其中 $executableFilePath 是应用的可执行文件的路径。

设置用户的 shell 并注册可执行文件后，完成将适用于使用 <a0/&a0> 生成的所有应用。

对于 Windows（Windows 命令提示符）上的 cmd.exe ，没有可插入的选项卡完成机制，因此没有可用的填充码脚本。对于其他 shell，请查找标记的 Area-CompletionsGitHub 问题。如果找不到问题，可以打开一个新问题。

在运行时获取选项卡完成值

以下代码显示了一个应用，该应用在运行时动态检索选项卡完成的值。该代码获取当前日期后的接下来两周日期的列表。通过调用CompletionSources.Add以下命令向选项提供--date列表：

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

按 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。

此代码创建的动态选项卡完成列表也显示在帮助输出中：

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键补全

在运行时获取选项卡完成值

另请参阅

其他资源