Register-ArgumentCompleter

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

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

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

下列範例會為 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所提供的值開頭的任何標識符，代表使用者按下 <TAB>之前輸入的文字。 篩選的標識符會透過管線傳送至 For-EachObject Cmdlet，此 Cmdlet 會以引號括住每個值，如果值包含空格。

第二個命令會藉由傳遞 scriptblock、ParameterName “Id” 和 CommandNameSet-TimeZone來註冊自變數完成項。

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

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

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

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

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

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

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

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

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

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

在腳本區塊中，會使用 dotnet complete 命令來執行索引標籤完成。 結果會 ForEach-Object 靜態方法，為每個值建立新的 CompletionResult 物件。

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

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

此 Cmdlet 不會傳回任何輸出。