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
danShouldContinue
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 begin
process
, , 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{}
}
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
, danclean
masih dijalankan.
- Blok
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 CmdletBinding
alur , 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
, , process
dan 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:
- ketika eksekusi alur selesai secara normal tanpa mengakhiri kesalahan
- ketika eksekusi alur terganggu karena kesalahan penghentian
- ketika alur dihentikan oleh
Select-Object -First
- 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.