Bagikan melalui

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.

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 pengisi argumen untuk parameter 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 blokir 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 cmdlet . cmdlet Where-Object 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 cmdlet ForEach-Object, yang mencakup setiap nilai dalam tanda kutip untuk menangani nilai yang 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          # completionText
            $_.Name          # listItemText
            'ParameterValue' # resultType
            $_.Name          # toolTip
        )
    }
}

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

Perintah pertama membuat blokir 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 sedang berjalan menggunakan Where-Object cmdlet. 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. 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+Spasi.

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

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

Perintah pertama membuat blokir 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 cmdlet ForEach-Object, yang menggunakan metode statis baruSystem.Management.Automation.CompletionResult kelas 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 Native. 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.

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

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. Blokir skrip yang Anda berikan harus mengembalikan nilai yang menyelesaikan input. Blok skrip harus membuka pendaftaran nilai menggunakan alur (ForEach-Object, , Where-Objectdll.), atau metode lain yang sesuai. Mengembalikan array nilai menyebabkan PowerShell memperlakukan seluruh array sebagai satu nilai penyelesaian tab.

Blok skrip juga dapat mengembalikan objek System.Management.Automation.CompletionResult untuk setiap nilai untuk meningkatkan pengalaman pengguna. Mengembalikan completionResult objek memungkinkan Anda menentukan tipsalat dan entri daftar kustom yang ditampilkan saat pengguna menekan Ctrl+Space untuk menampilkan daftar penyelesaian yang tersedia.

Blokir 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 CommandAst Class.
  • $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 CommandAst Class.
  • $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.

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.