Register-ArgumentCompleter

Modul:

Microsoft.PowerShell.Core

Mendaftarkan penyelesaian argumen kustom.

Sintaks

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

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

Deskripsi

Register-ArgumentCompleter Cmdlet mendaftarkan penyelesaian argumen kustom. Pelengkap argumen memungkinkan Anda menyediakan penyelesaian tab dinamis, pada waktu proses untuk perintah apa pun yang Anda tentukan.

Contoh

Contoh 1: Mendaftarkan penyelesaian argumen kustom

Contoh berikut mendaftarkan penyelesaian argumen untuk parameter Set-TimeZone Id cmdlet.

$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

Perintah pertama membuat blok skrip yang mengambil parameter yang diperlukan yang diteruskan saat pengguna menekan Tab. Untuk informasi selengkapnya, lihat deskripsi parameter ScriptBlock .

Dalam blok skrip, nilai yang tersedia untuk Id diambil menggunakan Get-TimeZone cmdlet. Properti Id untuk setiap Zona Waktu disalurkan ke Where-Object cmdlet. Where-Object Cmdlet memfilter id apa pun yang tidak dimulai dengan nilai yang disediakan oleh $wordToComplete, yang mewakili teks yang di ketik pengguna sebelum mereka menekan Tab. Id yang difilter disalurkan ke ForEach-Object cmdlet yang mengapit setiap nilai dalam tanda kutip, jika nilai berisi spasi.

Perintah kedua mendaftarkan pengisi argumen dengan meneruskan blokir skrip, Id ParameterName, dan CommandNameSet-TimeZone.

Contoh 2: Menambahkan detail ke nilai penyelesaian tab Anda

Contoh berikut menimpa penyelesaian tab untuk parameter Stop-Service Nama cmdlet dan hanya mengembalikan layanan yang sedang berjalan.

$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

Perintah pertama membuat blok skrip yang mengambil parameter yang diperlukan yang diteruskan saat pengguna menekan Tab. Untuk informasi selengkapnya, lihat deskripsi parameter ScriptBlock .

Dalam blok skrip, perintah pertama mengambil semua layanan yang Where-Object sedang berjalan menggunakan cmdlet. Layanan disalurkan ke ForEach-Object cmdlet. ForEach-Object Cmdlet membuat objek System.Management.Automation.CompletionResult baru dan mengisinya dengan nama layanan saat ini (diwakili oleh variabel $_.Namealur ).

Objek CompletionResult memungkinkan Anda memberikan detail tambahan untuk setiap nilai yang dikembalikan:

• completionText (String) - Teks yang akan digunakan sebagai hasil penyelesaian otomatis. Ini adalah nilai yang dikirim ke perintah .
• listItemText (String) - Teks yang akan ditampilkan dalam daftar, seperti saat pengguna menekan Ctrl+Space. Ini digunakan hanya untuk tampilan dan tidak diteruskan ke perintah saat dipilih.
• resultType (CompletionResultType) - Jenis hasil penyelesaian.
• toolTip (String) - Teks untuk tipsalat dengan detail yang akan ditampilkan tentang objek. Ini terlihat ketika pengguna memilih item setelah menekan Ctrl+Space.

Perintah terakhir menunjukkan bahwa layanan yang dihentikan masih dapat diteruskan secara manual ke Stop-Service cmdlet. Penyelesaian tab adalah satu-satunya aspek yang terpengaruh.

Contoh 3: Mendaftarkan penyelesaian argumen Asli kustom

Anda dapat menggunakan parameter Asli untuk menyediakan penyelesaian tab untuk perintah asli. Contoh berikut menambahkan penyelesaian tab untuk dotnet Antarmuka Baris Perintah (CLI).

Catatan

Perintah dotnet complete hanya tersedia di versi 2.0 dan yang lebih besar dari 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

Perintah pertama membuat blok skrip yang mengambil parameter yang diperlukan yang diteruskan saat pengguna menekan Tab. Untuk informasi selengkapnya, lihat deskripsi parameter ScriptBlock .

Dalam blok skrip, dotnet complete perintah digunakan untuk melakukan penyelesaian tab. Hasilnya disalurkan ke ForEach-Object cmdlet yang menggunakan metode statis baru dari kelas System.Management.Automation.CompletionResult untuk membuat objek CompletionResult baru untuk setiap nilai.

Parameter

-CommandName

Menentukan nama perintah sebagai array.

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

-Native

Menunjukkan bahwa pengisi argumen adalah untuk perintah asli di mana PowerShell tidak dapat menyelesaikan nama parameter.

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

-ParameterName

Menentukan nama parameter yang argumennya sedang diselesaikan. Nama parameter yang ditentukan tidak boleh berupa nilai enumerasi, seperti parameter ForegroundColor cmdlet Write-Host .

Untuk informasi selengkapnya tentang enum, lihat about_Enum.

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

-ScriptBlock

Menentukan perintah yang akan dijalankan untuk melakukan penyelesaian tab. Blok skrip yang Anda berikan harus mengembalikan nilai yang menyelesaikan input. Blok skrip harus membatalkan pendaftaran nilai menggunakan alur (ForEach-Object, , Where-Objectdll.), atau metode lain yang sesuai. Mengembalikan array nilai menyebabkan PowerShell memperlakukan seluruh array sebagai nilai penyelesaian satu tab.

Blok skrip harus menerima parameter berikut dalam urutan yang ditentukan di bawah ini. Nama parameter tidak penting karena PowerShell meneruskan nilai menurut posisi.

• $commandName (Posisi 0) - Parameter ini diatur ke nama perintah tempat blok skrip menyediakan penyelesaian tab.
• $parameterName (Posisi 1) - Parameter ini diatur ke parameter yang nilainya memerlukan penyelesaian tab.
• $wordToComplete (Posisi 2) - Parameter ini diatur ke nilai yang telah disediakan pengguna sebelum mereka menekan Tab. Blok skrip Anda harus menggunakan nilai ini untuk menentukan nilai penyelesaian tab.
• $commandAst (Posisi 3) - Parameter ini diatur ke Pohon Sintaks Abstrak (AST) untuk baris input saat ini. Untuk informasi selengkapnya, lihat Kelas Ast.
• $fakeBoundParameters (Posisi 4) - Parameter ini diatur ke hashtable yang berisi $PSBoundParameters untuk cmdlet, sebelum pengguna menekan Tab. Untuk informasi selengkapnya, lihat about_Automatic_Variables.

Saat Anda menentukan parameter Asli , blok skrip harus mengambil parameter berikut dalam urutan yang ditentukan. Nama parameter tidak penting karena PowerShell meneruskan nilai menurut posisi.

• $wordToComplete (Posisi 0) - Parameter ini diatur ke nilai yang telah disediakan pengguna sebelum mereka menekan Tab. Blok skrip Anda harus menggunakan nilai ini untuk menentukan nilai penyelesaian tab.
• $commandAst (Posisi 1) - Parameter ini diatur ke Pohon Sintaks Abstrak (AST) untuk baris input saat ini. Untuk informasi selengkapnya, lihat Kelas Ast.
• $cursorPosition (Posisi 2) - Parameter ini diatur ke posisi kursor saat pengguna menekan Tab.

Anda juga dapat menyediakan ArgumentCompleter sebagai atribut parameter. Untuk informasi selengkapnya, lihat about_Functions_Advanced_Parameters.

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

Input

None

Anda tidak dapat menyalurkan objek ke cmdlet ini.

Output

None

Cmdlet ini tidak mengembalikan output.