Register-ArgumentCompleter

Modul:
Microsoft.PowerShell.Core Module

Mendaftarkan penyelesaian argumen kustom.

Sintaks

NativeSet 

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

PowerShellSet 

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

Deskripsi

cmdlet Register-ArgumentCompleter 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 pengisi argumen untuk parameter 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 ketika pengguna menekan Tab. Untuk informasi selengkapnya, lihat deskripsi parameter ScriptBlock .

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

Perintah kedua mendaftarkan pengisi argumen dengan melewati blokir skrip,ParameterName dan CommandName .

Contoh 2: Menambahkan detail ke nilai penyelesaian tab Anda

Contoh berikut menimpa penyelesaian tab untuk parameter 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 ketika pengguna menekan Tab. Untuk informasi selengkapnya, lihat deskripsi parameter ScriptBlock .

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

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+Spasi.

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

Contoh 3: Mendaftarkan penyelesaian argumen Asli kustom

Anda dapat menggunakan parameter Native untuk menyediakan penyelesaian tab untuk perintah asli. Contoh berikut menambahkan penyelesaian tab untuk dotnet Command Line Interface (CLI).

Nota

Perintah dotnet complete hanya tersedia di versi 2.0 dan yang lebih besar dari cli dotnet.

$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 ketika pengguna menekan Tab. Untuk informasi selengkapnya, lihat deskripsi parameter ScriptBlock .

Dalam blok skrip, perintah dotnet complete 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.

Properti parameter

Jenis:

String[]

Nilai default:None
Mendukung wildcard:False
DontShow:False

Kumpulan parameter

NativeSet
Position:Named
Wajib:True
Nilai dari alur:False
Nilai dari alur berdasarkan nama properti:False
Nilai dari argumen yang tersisa:False
PowerShellSet
Position:Named
Wajib:False
Nilai dari alur:False
Nilai dari alur berdasarkan nama properti:False
Nilai dari argumen yang tersisa:False

-Native

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

Properti parameter

Jenis:SwitchParameter
Nilai default:None
Mendukung wildcard:False
DontShow:False

Kumpulan parameter

NativeSet
Position:Named
Wajib:False
Nilai dari alur:False
Nilai dari alur berdasarkan nama properti:False
Nilai dari argumen yang tersisa: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.

Properti parameter

Jenis:String
Nilai default:None
Mendukung wildcard:False
DontShow:False

Kumpulan parameter

PowerShellSet
Position:Named
Wajib:True
Nilai dari alur:False
Nilai dari alur berdasarkan nama properti:False
Nilai dari argumen yang tersisa: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 membuka pendaftaran nilai menggunakan alur (ForEach-Object, Where-Object, dll.), atau metode lain yang sesuai. Mengembalikan array nilai menyebabkan PowerShell memperlakukan seluruh array sebagai satu nilai penyelesaian 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 di mana blok skrip menyediakan pelengkapan 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, lihatKelas 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 Native, 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 diberikan 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, lihatKelas 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.

Properti parameter

Jenis:ScriptBlock
Nilai default:None
Mendukung wildcard:False
DontShow:False

Kumpulan parameter

(All)
Position:Named
Wajib:True
Nilai dari alur:False
Nilai dari alur berdasarkan nama properti:False
Nilai dari argumen yang tersisa:False

CommonParameters

Cmdlet ini mendukung parameter umum: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, dan -WarningVariable. Untuk informasi selengkapnya, lihat about_CommonParameters.

Input

None

Anda tidak dapat menyalurkan objek ke cmdlet ini.

Output

None

Cmdlet ini tidak mengembalikan output.