共用方式為

Register-ArgumentCompleter

  • 參考
模組:
Microsoft.PowerShell.Core

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

語法

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

Description

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

當您使用 CommandName 參數呼叫此命令，且不使用 ParameterName 或 Native 參數時，命令會如同您指定 Native 參數一樣執行。 這可防止自變數完成項處理PowerShell命令參數。 當您想要註冊 PowerShell 命令的自變數完成項時，請一律指定 ParameterName 參數。

範例

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

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

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

    (Get-TimeZone -ListAvailable).Id | Where-Object {
        $_ -like "$wordToComplete*"
    } | ForEach-Object {
        "'$_'"
    }
}

Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $s

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

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

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

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

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

$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          # completionText
            $_.Name          # listItemText
            'ParameterValue' # resultType
            $_.Name          # toolTip
        )
    }
}

Register-ArgumentCompleter -CommandName Stop-Service -ParameterName Name -ScriptBlock $s

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

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

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

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

範例 3：註冊自定義 Native 自變數完成項

您可以使用 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(
            $_,               # completionText
            $_,               # listItemText
            'ParameterValue', # resultType
            $_                # toolTip
        )
    }
}

Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock

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

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

參數

-CommandName

指定要註冊自變數完成項的一或多個命令名稱。 這個參數是原生命令的必要參數。

當您指定此參數而不使用 ParameterName 或 Native 參數時，命令的行為就如同您已指定 Native 參數一樣。 註冊 PowerShell 命令的自變數完成項時，請一律指定 ParameterName 參數。

如果您未指定此參數，PowerShell 會針對所有 PowerShell 命令 ParameterName，註冊指定的自變數完成器。

類型:String[]
Position:Named
預設值:None
必要:False
接受管線輸入:False
接受萬用字元:False

-Native

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

類型:SwitchParameter
Position:Named
預設值:None
必要:False
接受管線輸入:False
接受萬用字元:False

-ParameterName

指定自變數完成項所套用的參數名稱。 指定參數的類型不能是列舉，例如 Write-Host Cmdlet 的 ForegroundColor 參數。

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

註冊 PowerShell 命令的自變數完成項時，請一律指定此參數。 當您指定 CommandName 參數，而沒有 ParameterName 或 Native 參數時，命令的行為就如同您指定了 Native 參數一樣。

類型:String
Position:Named
預設值:None
必要:True
接受管線輸入:False
接受萬用字元:False

-ScriptBlock

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

腳本區塊也可以針對每個值傳回 System.Management.Automation.CompletionResult 物件，以增強用戶體驗。 傳回 CompletionResult 物件可讓您定義當使用者 按下 Ctrl+Space 以顯示可用完成清單時所顯示的工具提示和自定義清單專案。

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

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

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

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

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

類型:ScriptBlock
Position:Named
預設值:None
必要:True
接受管線輸入:False
接受萬用字元:False

輸入

None

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

輸出

None

此 Cmdlet 不會傳回任何輸出。