共用方式為

Register-ArgumentCompleter

  • 參考
模組:
Microsoft.PowerShell.Core

註冊自定義自變數完成器。

Syntax

Register-ArgumentCompleter
        -CommandName <String[]>
        -ScriptBlock <ScriptBlock>
        [-Native]
        [<CommonParameters>]
Register-ArgumentCompleter
        [-CommandName <String[]>]
        -ParameterName <String>
        -ScriptBlock <ScriptBlock>
        [<CommonParameters>]

Description

Cmdlet Register-ArgumentCompleter 會註冊自定義自變數完成器。 自變數完成器可讓您在執行時間提供您指定之任何命令的動態索引標籤完成。

範例

範例 1：註冊自定義自變數完成器

下列範例會為 Cmdlet 的 Set-TimeZoneId 參數註冊自變數完成器。

$scriptBlock = {
    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)

    (Get-TimeZone -ListAvailable).Id | Where-Object {
        $_ -like "$wordToComplete*"
    } | ForEach-Object {
          "'$_'"
    }
}
Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $scriptBlock

第一個命令會建立腳本區塊，此區塊會採用使用者按下 Tab 鍵時傳入的必要參數。如需詳細資訊，請參閱 ScriptBlock 參數描述。

在腳本區塊中，會使用 Cmdlet 擷取 標識碼 的 Get-TimeZone 可用值。 每個時區的 Id 屬性都會以管線傳送至 Where-Object Cmdlet。 Cmdlet 會 Where-Object 篩選出任何不是以 所提供的值開頭的 $wordToComplete標識符，代表使用者在按下 Tab 之前輸入的文字。篩選的標識碼會透過管線傳送至 ForEach-Object Cmdlet，以引號括住每個值，此值應包含空格。

第二個命令會藉由傳遞 scriptblock、 ParameterName標識符 和 CommandNameSet-TimeZone 來註冊自變數完成器。

範例 2：將詳細數據新增至索引標籤完成值

下列範例會覆寫 Cmdlet 之 Name 參數的 Stop-Service Tab 鍵自動完成，而且只會傳回執行中的服務。

$s = {
    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)
    $services = Get-Service | Where-Object {$_.Status -eq "Running" -and $_.Name -like "$wordToComplete*"}
    $services | ForEach-Object {
        New-Object -Type System.Management.Automation.CompletionResult -ArgumentList $_.Name,
            $_.Name,
            "ParameterValue",
            $_.Name
    }
}
Register-ArgumentCompleter -CommandName Stop-Service -ParameterName Name -ScriptBlock $s

第一個命令會建立腳本區塊，此區塊會採用使用者按下 Tab 鍵時傳入的必要參數。如需詳細資訊，請參閱 ScriptBlock 參數描述。

在腳本區塊中，第一個命令會使用 Cmdlet 擷取所有執行中的 Where-Object 服務。 服務會透過管線傳送至 ForEach-Object Cmdlet。 Cmdlet ForEach-Object 會建立新的 System.Management.Automation.CompletionResult 物件，並以管線變數 $_.Name (所代表的目前服務名稱填入) 。

CompletionResult 物件可讓您為每個傳回的值提供其他詳細數據：

  • completionText (String) - 要當做自動完成結果使用的文字。 這是傳送至命令的值。
  • listItemText (String) - 要顯示在清單中的文字，例如當使用者按下 Ctrl空格鍵+時。 這僅用於顯示，而且不會在選取時傳遞至命令。
  • resultType (CompletionResultType) - 完成結果的類型。
  • toolTip (String) - 工具提示的文字，其中包含有關對象的詳細數據。 當使用者按下 Ctrl+空格鍵之後選取專案時，就會看到此專案。

最後一個命令示範停止的服務仍然可以手動 Stop-Service 傳入 Cmdlet。 索引標籤自動完成是唯一受影響的層面。

範例 3：註冊自定義原生自變數完成器

您可以使用 Native 參數來提供原生命令的索引標籤自動完成。 下列範例會為 dotnet 命令行介面 (CLI) 新增 Tab 鍵自動完成。

注意

此命令 dotnet complete 僅適用於 2.0 版和更新版本的 dotnet cli。

$scriptblock = {
    param($wordToComplete, $commandAst, $cursorPosition)
        dotnet complete --position $cursorPosition $commandAst.ToString() | ForEach-Object {
            [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
        }
}
Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock

第一個命令會建立腳本區塊，此區塊會採用使用者按下 Tab 鍵時傳入的必要參數。如需詳細資訊，請參閱 ScriptBlock 參數描述。

在腳本區塊中 dotnet complete ，命令是用來執行索引標籤完成。 結果會透過管線傳送至 ForEach-Object Cmdlet，以使用 System.Management.Automation.CompletionResult 類別的新靜態方法，為每個值建立新的 CompletionResult 物件。

參數

-CommandName

指定命令的名稱做為陣列。

Type:String[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Native

指出自變數完成器適用於PowerShell無法完成參數名稱的原生命令。

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ParameterName

指定參數的名稱，其自變數正在完成。 指定的參數名稱不能是列舉值，例如 Cmdlet 的 Write-HostForegroundColor 參數。

如需列舉的詳細資訊，請參閱 about_Enum。

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-ScriptBlock

指定要執行以執行索引標籤完成的命令。 您提供的文稿區塊應該會傳回完成輸入的值。 腳本區塊必須使用管線 (ForEach-Object、 Where-Object等 ) 或其他適當的方法來取消註冊值。 傳回值的陣列會導致PowerShell將整個數位視為 一個 索引標籤完成值。

腳本區塊必須依照下列指定的順序接受下列參數。 參數的名稱並不重要，因為PowerShell會依位置傳入值。

  • $commandName (位置 0) - 此參數會設定為腳本區塊提供索引標籤完成的命令名稱。
  • $parameterName (Position 1) - 此參數會設定為其值需要索引標籤完成的參數。
  • $wordToComplete (Position 2) - 此參數會設定為使用者在按下 Tab 之前所提供的值。您的腳本區塊應該使用此值來判斷索引標籤完成值。
  • $commandAst (位置 3) - 此參數會設定為目前輸入行的抽象語法樹狀結構 (AST) 。 如需詳細資訊，請參閱 Ast 類別。
  • $fakeBoundParameters (Position 4) - 此參數會在使用者按下 Tab 之前，將設定為包含 $PSBoundParameters Cmdlet 之 的哈希 表。如需詳細資訊，請參閱 about_Automatic_Variables。

當您指定 Native 參數時，腳本區塊必須依指定的順序採用下列參數。 參數的名稱並不重要，因為PowerShell會依位置傳入值。

  • $wordToComplete (Position 0) - 此參數會設定為使用者在按下 Tab 之前所提供的值。您的腳本區塊應該使用此值來判斷索引標籤完成值。
  • $commandAst (位置 1) - 此參數設定為目前輸入行的抽象語法樹狀結構 (AST) 。 如需詳細資訊，請參閱 Ast 類別。
  • $cursorPosition (Position 2) - 當使用者按下 Tab 鍵時，此參數會設定為游標的位置。

您也可以提供 ArgumentCompleter 做為參數屬性。 如需詳細資訊，請參閱 about_Functions_Advanced_Parameters。

Type:ScriptBlock
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

輸入

None

您無法使用管線將物件傳送至此 Cmdlet。

輸出

None

此 Cmdlet 不會傳回任何輸出。