共用方式為

Register-ArgumentCompleter

模組:
Microsoft.PowerShell.Core Module

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

語法

NativeSet 

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

PowerShellSet 

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

Description

Register-ArgumentCompleter cmdlet 會註冊自定義引數完成器。 參數完成器允許您在執行時為您指定的任何命令提供動態的自動完成功能。

範例

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

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

$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 的可用值。 每個時區的 識別碼 屬性會管線傳送至 Where-Object Cmdlet。 Where-Object該 cmdlet 篩選出任何不以 提供的$wordToComplete值開頭的 ID，該值表示使用者在按 Tab 鍵之前鍵入的文本。如果值包含空格，則篩選的ID將通過管道傳輸到 cmdlet，ForEach-Object該 cmdlet 將每個值括在引號中。

第二個命令透過傳遞 scriptblock、ParameterNameId 和 CommandNameSet-TimeZone，來註冊參數補全器。

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

下列範例將會覆寫 Cmdlet 的 Stop-Service 參數的索引標籤自動完成功能，並且只會返回執行中的服務。

$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 參數說明。

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

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

  • completionText （String） - 要當做自動完成結果使用的文字。 這是傳送至指令的值。
  • listItemText （String） - 要顯示在清單中的文字，例如當使用者 按下 Ctrl+Space時。 這僅用於顯示，而且不會在選取時傳遞至命令。
  • resultType （CompletionResultType） - 完成結果的類型。
  • 工具提示 （String） - 工具提示的文字，其中包含要顯示對象的詳細數據。 當使用者按下 Ctrl +Space並選取項目時，這個將變得可見。

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

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

您可以使用 Native 參數為原生命令提供快速補全功能。 下列範例會為 dotnet 命令列介面 （CLI） 新增標籤補全功能。

備註

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 命令來執行索引標籤完成。 結果通過管道傳輸到 cmdlet，ForEach-Object該 cmdlet 使用 System.Management.Automation.CompletionResult 類的新靜態方法為每個值創建新的 CompletionResult 物件。

參數

-CommandName

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

參數屬性

類型:

String[]

預設值:None
支援萬用字元:False
不要顯示:False

參數集

NativeSet
Position:Named
必要:True
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False
PowerShellSet
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-Native

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

參數屬性

類型:SwitchParameter
預設值:None
支援萬用字元:False
不要顯示:False

參數集

NativeSet
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-ParameterName

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

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

參數屬性

類型:String
預設值:None
支援萬用字元:False
不要顯示:False

參數集

PowerShellSet
Position:Named
必要:True
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-ScriptBlock

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

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

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

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

  • $wordToComplete （位置 0） - 此參數設定為使用者在按下 Tab 鍵之前提供的值。腳本塊應使用此值來確定製表符補全值。
  • $commandAst （位置 1） - 此參數設置為當前輸入行的抽象語法樹 （AST）。 如需詳細資訊，請參閱 Ast 類別。
  • $cursorPosition （位置 2） - 此參數設定為使用者按 Tab 鍵時光標的位置。

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

參數屬性

類型:ScriptBlock
預設值:None
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:Named
必要:True
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

CommonParameters

此 Cmdlet 支援一般參數：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 如需詳細資訊，請參閱 about_CommonParameters。

輸入

None

您不能將物件透過管道傳送到此 Cmdlet。

輸出

None

此 Cmdlet 不會傳回任何輸出。