System.CommandLine 的索引標籤完成

發行項
03/05/2024

重要

System.CommandLine 目前為預覽版，而此文件適用於版本 2.0 搶鮮版 (Beta) 4。部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

使用 System.CommandLine 的應用程式，在特定殼層中具有索引標籤自動完成的內建支援。若要啟用它，終端使用者必須針對每個殼層採取一些步驟。一旦使用者執行此作業，索引標籤完成會針對應用程式中的靜態值自動完成，例如呼叫 FromAmong 所定義的列舉值或值。您也可以在執行階段動態取得值，以自訂索引標籤完成。

啟用 TAB 鍵自動完成

在您想要啟用索引標籤完成的電腦上，執行下列步驟。

針對 .NET CLI：

請參閱如何啟用索引標籤完成。

針對建置在 System.CommandLine 上的其他命令列應用程式：

安裝 dotnet-suggest 全域工具。
將適當的填充碼指令碼新增至 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
```

設定使用者的殼層之後，完成會適用於使用 System.CommandLine 建置的所有應用程式。

針對 Windows 上的 cmd.exe (Windows 命令提示字元)，因為沒有插入式索引標籤完成機制，所以沒有可用的填充碼指令碼。針對其他殼層，尋找標示為 Area-Completions 的 GitHub 問題。如果您找不到問題，您可以提出新的問題。

在執行階段取得索引標籤完成值

下列程式碼顯示可在執行階段動態取得索引標籤自動完成值的應用程式。此程式碼會取得目前日期之後的接下來兩周日期清單。清單會藉由呼叫 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);
    }
}

按下索引標籤鍵時所顯示的值，會以 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 鍵自動完成

在執行階段取得索引標籤完成值

另請參閱

其他資源