Bagikan melalui

about_Functions_Advanced_Methods

Deskripsi singkat

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

Deskripsi panjang

Fungsi yang menentukan atribut CmdletBinding dapat mengakses metode dan properti tambahan melalui variabel $PSCmdlet. 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 metode Write yang mengembalikan berbagai jenis output.

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

Untuk informasi selengkapnya tentang atribut CmdletBinding, 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 blok fungsi begin, process, dan end. PowerShell 7.3 menambahkan metode proses blok clean.

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

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

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

Nota

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

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 blok process tanpa menentukan blok lain. Jumlah eksekusi blok process tergantung pada cara Anda menggunakan fungsi dan input apa yang diterima fungsi.

Variabel otomatis $_ atau $PSItem berisi objek saat ini dalam alur untuk digunakan di blok process. 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 blok process sekali.
  • Dalam alur, blok process dijalankan sekali untuk setiap objek input yang mencapai fungsi.
  • Jika input alur yang mencapai fungsi kosong, blok processtidak dijalankan.
    • Blok begin, end, dan clean masih dijalankan.

Penting

Jika parameter fungsi diatur untuk menerima input alur, dan blok process 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 alur dan menggunakan CmdletBinding, blok process harus menggunakan variabel parameter yang Anda tentukan untuk input alur alih-alih $_ atau $PSItem. Misalnya:

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

Blok clean ditambahkan di PowerShell 7.3.

Blok clean adalah cara mudah bagi pengguna untuk membersihkan sumber daya yang mencakup blok begin, process, dan end. Ini secara semantik mirip dengan blok finally 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. saat alur dihentikan oleh Ctrl+c atau StopProcessing()

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

Hati

Menambahkan blok clean adalah perubahan yang melanggar. Karena clean diuraikan 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 blok process {} 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 metode ShouldProcess 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 yang tidak mengakhiri terjadi, fungsi harus memanggil metode WriteError, yang dijelaskan di bagian metode Write. Ketika terjadi kesalahan penghentian dan fungsi tidak dapat dilanjutkan, fungsi harus memanggil metode ThrowTerminatingError. Anda juga dapat menggunakan pernyataan throw untuk mengakhiri kesalahan dan cmdlet Kesalahan Tulis 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 cmdlet Write, seperti Write-Error.

WriteCommandDetail

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

WriteDebug

Untuk memberikan informasi yang dapat digunakan untuk memecahkan masalah fungsi, buat fungsi memanggil metode WriteDebug. Metode 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.

Nota

Jika terjadi kesalahan penghentian, fungsi harus memanggil metode ThrowTerminatingError.

WriteObject

Metode WriteObject memungkinkan fungsi 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 metode WriteProgress 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 metode WriteVerbose 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.

Nota

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

Metode dan properti lainnya

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

Misalnya, properti ParameterSetName memungkinkan Anda melihat kumpulan 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