Bagikan melalui

about_Functions_Advanced_Methods

Deskripsi singkat

Menjelaskan bagaimana fungsi yang menentukan CmdletBinding atribut dapat menggunakan metode dan properti yang tersedia untuk cmdlet yang dikompilasi.

Deskripsi panjang

Fungsi yang menentukan CmdletBinding atribut dapat mengakses metode dan properti tambahan melalui $PSCmdlet variabel . Metode ini mencakup metode berikut:

  • Metode pemrosesan input yang sama tersedia untuk semua fungsi.
  • Metode ShouldProcess dan ShouldContinue yang digunakan untuk mendapatkan umpan balik pengguna sebelum tindakan dilakukan.
  • Metode ThrowTerminatingError untuk menghasilkan rekaman kesalahan.
  • Beberapa Write metode yang mengembalikan berbagai jenis output.

Semua metode dan properti kelas PSCmdlet tersedia untuk fungsi tingkat lanjut. Untuk informasi selengkapnya, lihat System.Management.Automation.PSCmdlet.

Untuk informasi selengkapnya tentang CmdletBinding atribut , lihat about_Functions_CmdletBindingAttribute. Untuk kelas CmdletBindingAttribute, lihat System.Management.Automation.Cmdlet.CmdletBindingAttribute.

Metode pemrosesan input

Metode yang dijelaskan di bagian ini disebut sebagai metode pemrosesan input. Untuk fungsi, ketiga metode ini diwakili oleh beginprocess, , dan end blok fungsi. PowerShell 7.3 menambahkan clean metode proses blok.

Anda tidak diharuskan menggunakan salah satu blok ini dalam fungsi Anda. Jika Anda tidak menggunakan blok bernama, maka PowerShell menempatkan kode di end blok fungsi. Namun, jika Anda menggunakan salah satu blok bernama ini, atau menentukan dynamicparam blok, Anda harus menempatkan semua kode dalam blok bernama.

Contoh berikut menunjukkan kerangka fungsi yang berisi begin blok untuk praproses satu kali, process blok untuk beberapa pemrosesan rekaman, dan end blok untuk pasca-pemrosesan satu kali.

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$true)]
    param ($Parameter1)
    begin{}
    process{}
    end{}
    clean{}
}

Catatan

Blok ini berlaku untuk semua fungsi, bukan hanya fungsi yang menggunakan CmdletBinding atribut .

begin

Blok ini digunakan untuk menyediakan pra-pemrosesan satu kali opsional untuk fungsi tersebut. Runtime PowerShell menggunakan kode dalam blok ini sekali untuk setiap instans fungsi dalam alur.

process

Blok ini digunakan untuk menyediakan pemrosesan rekaman demi rekaman untuk fungsi tersebut. Anda dapat menggunakan process blok tanpa menentukan blok lain. Jumlah process eksekusi blok tergantung pada cara Anda menggunakan fungsi dan input apa yang diterima fungsi.

Variabel $_ otomatis atau $PSItem berisi objek saat ini dalam alur untuk digunakan dalam process blok. Variabel $input otomatis berisi enumerator yang hanya tersedia untuk fungsi dan blok skrip. Untuk informasi selengkapnya, lihat about_Automatic_Variables.

  • Memanggil fungsi di awal, atau di luar alur, menjalankan process blok sekali.
  • Dalam alur, process blok dijalankan sekali untuk setiap objek input yang mencapai fungsi.
  • Jika input alur yang mencapai fungsi kosong, process blok tidak dijalankan.
    • Blok begin, end, dan clean masih dijalankan.

Penting

Jika parameter fungsi diatur untuk menerima input alur, dan process blok tidak ditentukan, pemrosesan rekaman demi rekaman akan gagal. Dalam hal ini, fungsi Anda hanya akan dijalankan sekali, terlepas dari input.

Saat Anda membuat fungsi yang menerima input dan penggunaan CmdletBindingalur , process blok harus menggunakan variabel parameter yang Anda tentukan untuk input alur alih-alih $_ atau $PSItem. Contohnya:

function Get-SumOfNumbers {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory, Position=0, ValueFromPipeline)]
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
       foreach ($n in $Numbers) {
           $retValue += $n
       }
    }

    end { $retValue }
}

PS> Get-SumOfNumbers 1, 2, 3, 4
10
PS> 1,2,3,4 | Get-SumOfNumbers
10

end

Blok ini digunakan untuk menyediakan pasca-pemrosesan satu kali opsional untuk fungsi tersebut.

clean

clean Blok ditambahkan di PowerShell 7.3.

clean Blok ini adalah cara mudah bagi pengguna untuk membersihkan sumber daya yang mencakup blok begin, , processdan end . Ini secara semantik mirip finally dengan blok yang mencakup semua blok bernama lainnya dari fungsi skrip atau cmdlet skrip. Pembersihan sumber daya diberlakukan untuk skenario berikut:

  1. ketika eksekusi alur selesai secara normal tanpa mengakhiri kesalahan
  2. ketika eksekusi alur terganggu karena kesalahan penghentian
  3. ketika alur dihentikan oleh Select-Object -First
  4. ketika alur sedang dihentikan oleh Ctrl+c atau StopProcessing()

Blok bersih membuang output apa pun yang ditulis ke aliran Keberhasilan .

Perhatian

clean Menambahkan blok adalah perubahan yang melanggar. Karena clean diurai sebagai kata kunci, ini mencegah pengguna langsung memanggil perintah bernama clean sebagai pernyataan pertama dalam blok skrip. Namun, itu tidak mungkin menjadi masalah. Perintah masih dapat dipanggil menggunakan operator panggilan (& clean).

Metode konfirmasi

ShouldProcess

Metode ini dipanggil untuk meminta konfirmasi dari pengguna sebelum fungsi melakukan tindakan yang akan mengubah sistem. Fungsi dapat dilanjutkan berdasarkan nilai Boolean yang dikembalikan oleh metode . Metode ini hanya dapat dipanggil dari dalam process {} blok fungsi. Atribut CmdletBinding juga harus menyatakan bahwa fungsi mendukung ShouldProcess (seperti yang ditunjukkan pada contoh sebelumnya).

Untuk informasi selengkapnya tentang metode ini, lihat System.Management.Automation.Cmdlet.ShouldProcess.

Untuk informasi selengkapnya tentang cara meminta konfirmasi, lihat Meminta Konfirmasi.

HarusLanjutkan

Metode ini dipanggil untuk meminta pesan konfirmasi kedua. Ini harus dipanggil ketika ShouldProcess metode mengembalikan $true. Untuk informasi selengkapnya tentang metode ini, lihat System.Management.Automation.Cmdlet.ShouldContinue.

Metode kesalahan

Fungsi dapat memanggil dua metode berbeda ketika kesalahan terjadi. Ketika kesalahan non-penghentian terjadi, fungsi harus memanggil WriteError metode , yang dijelaskan di bagian Write metode. Ketika kesalahan penghentian terjadi dan fungsi tidak dapat dilanjutkan, itu harus memanggil ThrowTerminatingError metode . Anda juga dapat menggunakan throw pernyataan untuk mengakhiri kesalahan dan cmdlet Write-Error untuk kesalahan yang tidak mengakhiri.

Untuk informasi selengkapnya, lihat System.Management.Automation.Cmdlet.ThrowTerminatingError.

Metode tulis

Fungsi dapat memanggil metode berikut untuk mengembalikan berbagai jenis output. Perhatikan bahwa tidak semua output masuk ke perintah berikutnya dalam alur. Anda juga dapat menggunakan berbagai Write cmdlet, seperti Write-Error.

WriteCommandDetail

Untuk informasi tentang metode ini WriteCommandDetails , lihat System.Management.Automation.Cmdlet.WriteCommandDetail.

WriteDebug

Untuk memberikan informasi yang dapat digunakan untuk memecahkan masalah fungsi, buat fungsi memanggil WriteDebug metode . Metode ini WriteDebug menampilkan pesan debug kepada pengguna. Untuk informasi selengkapnya, lihat System.Management.Automation.Cmdlet.WriteDebug.

WriteError

Fungsi harus memanggil metode ini ketika kesalahan yang tidak mengakhiri terjadi dan fungsi dirancang untuk terus memproses rekaman. Untuk informasi selengkapnya, lihat System.Management.Automation.Cmdlet.WriteError.

Catatan

Jika terjadi kesalahan penghentian, fungsi harus memanggil metode ThrowTerminatingError .

WriteObject

Metode ini WriteObject memungkinkan fungsi untuk mengirim objek ke perintah berikutnya dalam alur. Dalam kebanyakan kasus, WriteObject adalah metode yang digunakan saat fungsi mengembalikan data. Untuk informasi selengkapnya, lihat System.Management.Automation.PSCmdlet.WriteObject.

WriteProgress

Untuk fungsi dengan tindakan yang membutuhkan waktu lama untuk diselesaikan, metode ini memungkinkan fungsi untuk memanggil WriteProgress metode sehingga informasi kemajuan ditampilkan. Misalnya, Anda dapat menampilkan persentase yang selesai. Untuk informasi selengkapnya, lihat System.Management.Automation.PSCmdlet.WriteProgress.

WriteVerbose

Untuk memberikan informasi terperinci tentang apa yang dilakukan fungsi, buat fungsi memanggil WriteVerbose metode untuk menampilkan pesan verbose kepada pengguna. Secara default, pesan verbose tidak ditampilkan. Untuk informasi selengkapnya, lihat System.Management.Automation.PSCmdlet.WriteVerbose.

WriteWarning

Untuk memberikan informasi tentang kondisi yang dapat menyebabkan hasil yang tidak terduga, buat fungsi memanggil metode WriteWarning untuk menampilkan pesan peringatan kepada pengguna. Secara default, pesan peringatan ditampilkan. Untuk informasi selengkapnya, lihat System.Management.Automation.PSCmdlet.WriteWarning.

Catatan

Anda juga dapat menampilkan pesan peringatan dengan mengonfigurasi $WarningPreference variabel atau dengan menggunakan Verbose opsi baris perintah dan Debug . untuk informasi selengkapnya tentang $WarningPreference variabel, lihat about_Preference_Variables.

Metode dan properti lainnya

Untuk informasi tentang metode dan properti lain yang dapat diakses melalui $PSCmdlet variabel, lihat System.Management.Automation.PSCmdlet.

Misalnya, properti ParameterSetName memungkinkan Anda melihat set parameter yang sedang digunakan. Set parameter memungkinkan Anda membuat fungsi yang melakukan tugas berbeda berdasarkan parameter yang ditentukan saat fungsi dijalankan.

Lihat juga

  • Last updated on