Bagikan melalui

Register-ArgumentCompleter

  • Referensi
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.

Saat Anda memanggil perintah ini dengan parameter CommandName dan tanpa parameter ParameterName atau Native , perintah berjalan seolah-olah Anda menentukan parameter Asli . Ini mencegah pengisi argumen bekerja untuk parameter perintah PowerShell. Selalu tentukan parameter ParameterName saat Anda ingin mendaftarkan pengisi argumen untuk perintah PowerShell.

Contoh

Contoh 1: Mendaftarkan penyelesaian argumen kustom

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

$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

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 untuk menangani nilai yang berisi spasi.

Perintah kedua mendaftarkan pengisi argumen dengan meneruskan blokir skrip, Id ParameterName, dan CommandName Set-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          # completionText
            $_.Name          # listItemText
            'ParameterValue' # resultType
            $_.Name          # toolTip
        )
    }
}

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. PowerShell menggunakan ini hanya untuk tampilan. Ini tidak diteruskan ke perintah saat dipilih.
  • resultType (CompletionResultType) - Jenis hasil penyelesaian.
  • toolTip (String) - Teks untuk tipsalat dengan detail untuk ditampilkan tentang objek. Ini terlihat ketika pengguna memilih item setelah menekan Ctrl+Space.

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

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 melakukan penyelesaian tab. Hasilnya disalurkan ke ForEach-Object cmdlet, yang menggunakan metode statis baru dari kelas System.Management.Automation.CompletionResult untuk membuat objek CompletionResult untuk setiap nilai.

Parameter

-CommandName

Menentukan nama satu atau beberapa perintah untuk mendaftarkan pengisi argumen. Parameter ini wajib untuk perintah asli.

Saat Anda menentukan parameter ini tanpa parameter ParameterName atau Native , perintah berperilaku seolah-olah Anda telah menentukan parameter Asli . Saat mendaftarkan penyelesaian argumen untuk perintah PowerShell, selalu tentukan parameter ParameterName .

Jika Anda tidak menentukan parameter ini, PowerShell mendaftarkan pengisi argumen untuk ParameterName yang ditentukan di semua perintah PowerShell.

Jenis:String[]
Position:Named
Nilai default:None
Diperlukan:False
Terima input alur:False
Terima karakter wildcard:False

-Native

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

Jenis:SwitchParameter
Position:Named
Nilai default:None
Diperlukan:False
Terima input alur:False
Terima karakter wildcard:False

-ParameterName

Menentukan nama parameter tempat penyelesaian argumen diterapkan. Jenis untuk parameter yang ditentukan tidak dapat menjadi enumerasi, seperti parameter ForegroundColor cmdlet Write-Host .

Untuk informasi selengkapnya tentang enum, lihat about_Enum.

Saat mendaftarkan pengisi argumen untuk perintah PowerShell, selalu tentukan parameter ini. Saat Anda menentukan parameter CommandName tanpa parameter ParameterName atau Native , perintah berperilaku seolah-olah Anda menentukan parameter Native .

Jenis:String
Position:Named
Nilai default:None
Diperlukan:True
Terima input alur:False
Terima karakter wildcard: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 juga dapat mengembalikan objek System.Management.Automation.CompletionResult untuk setiap nilai untuk meningkatkan pengalaman pengguna. Mengembalikan objek CompletionResult memungkinkan Anda menentukan tipsalat dan entri daftar kustom yang ditampilkan saat pengguna menekan Ctrl+Space untuk menampilkan daftar penyelesaian yang tersedia.

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, String) - Parameter ini diatur ke nama perintah tempat blok skrip menyediakan penyelesaian tab.
  • $parameterName (Posisi 1, String) - Parameter ini diatur ke parameter yang nilainya memerlukan penyelesaian tab.
  • $wordToComplete (Posisi 2, String) - 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, CommandAst) - Parameter ini diatur ke Pohon Sintaks Abstrak (AST) untuk baris input saat ini. Untuk informasi selengkapnya, lihat Kelas CommandAst.
  • $fakeBoundParameters (Posisi 4 IDictionary) - 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, String) - 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, CommandAst) - Parameter ini diatur ke Pohon Sintaks Abstrak (AST) untuk baris input saat ini. Untuk informasi selengkapnya, lihat Kelas CommandAst.
  • $cursorPosition (Posisi 2, Int32) - 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.

Jenis:ScriptBlock
Position:Named
Nilai default:None
Diperlukan:True
Terima input alur:False
Terima karakter wildcard:False

Input

None

Anda tidak dapat menyalurkan objek ke cmdlet ini.

Output

None

Cmdlet ini tidak mengembalikan output.