Tentang Fungsi

2025-04-17

Deskripsi singkat

Menjelaskan cara membuat dan menggunakan fungsi di PowerShell.

Deskripsi panjang

Fungsi adalah daftar pernyataan PowerShell yang memiliki nama yang Anda tetapkan. Saat menjalankan fungsi, Anda mengetikkan nama fungsi.

PowerShell mendefinisikan dua jenis fungsi:

Fungsi adalah blok kode yang dapat dipanggil berdasarkan nama. Ini dapat mengambil input dan mengembalikan output. Fungsi didefinisikan menggunakan function kata kunci.
Filter adalah jenis fungsi yang dirancang untuk memproses data dari alur. Filter didefinisikan menggunakan filter kata kunci.

Anda dapat mengelompokkan pernyataan dalam fungsi ke dalam salah satu dari empat blok skrip berbeda yang telah ditentukan sebelumnya. Blok skrip ini diberi nama menggunakan kata kunci begin, , processend, dan clean. Jika Anda tidak menggunakan kata kunci ini, PowerShell menempatkan pernyataan di blok kode yang sesuai.

Fungsi juga dapat bertindak seperti cmdlet. Anda dapat membuat fungsi yang berfungsi seperti cmdlet tanpa menggunakan C# pemrograman. Untuk informasi selengkapnya, lihat about_Functions_Advanced.

Penting

Dalam file skrip dan modul berbasis skrip, fungsi harus ditentukan sebelum dapat dipanggil.

Sintaksis fungsi

Fungsi didefinisikan menggunakan sintaks berikut:

function [<scope:>]<name> {
  param([type]$Parameter1 [,[type]$Parameter2])
  dynamicparam {<statement list>}
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
  clean {<statement list>}
}

Fungsi mencakup item berikut:

Kata function kunci
Cakupan (opsional)
Nama yang Anda pilih
Sejumlah parameter bernama (opsional), termasuk parameter dinamis
Satu atau beberapa pernyataan PowerShell diapit kurung kurawal {}

Jika Anda tidak menggunakan salah satu kata kunci (begin, , process, endclean) dalam function definisi, PowerShell menempatkan pernyataan di end blok .

Untuk informasi selengkapnya tentang dynamicparam kata kunci dan parameter dinamis dalam fungsi, lihat about_Functions_Advanced_Parameters.

Fungsi bisa sesinggah:

function Get-PowerShellProcess { Get-Process pwsh }

Setelah fungsi ditentukan, Anda dapat menggunakannya seperti cmdlet bawaan. Misalnya, untuk memanggil fungsi yang baru ditentukan Get-PowerShellProcess :

Get-PowerShellProcess

 NPM(K)    PM(M)      WS(M)     CPU(s)      Id  SI ProcessName
 ------    -----      -----     ------      --  -- -----------
    110    78.72     172.39      10.62   10936   1 pwsh

Fungsi juga bisa serumit cmdlet.

Fungsi dapat mengembalikan nilai yang dapat ditampilkan, ditetapkan ke variabel, atau diteruskan ke fungsi atau cmdlet lain. Anda dapat menggunakan return kata kunci untuk mengembalikan output. Kata return kunci tidak memengaruhi atau menekan output lain yang dikembalikan dari fungsi Anda. Namun, return kata kunci keluar dari fungsi pada baris tersebut. Untuk informasi selengkapnya, lihat about_Return.

Sintaks penyaring

Niat fungsi filter ini adalah untuk memberikan cara singkat untuk menentukan fungsi yang berjalan pada setiap objek dalam alur.

Sintaks filter adalah sebagai berikut:

filter [<scope:>]<name> {<statement list>}

Untuk menyederhanakan sintaks untuk filter fungsi, hilangkan kata kunci blok skrip (begin, , processend, clean). PowerShell menempatkan pernyataan di process blok. Anda dapat menggunakan salah satu blok lain dalam fungsi filter, tetapi niatnya adalah untuk memberikan cara singkat untuk menentukan fungsi yang memiliki satu-satunya tujuan untuk memproses setiap objek dalam alur.

Filter berikut mengambil entri log dari alur lalu menampilkan seluruh entri atau hanya bagian pesan dari entri:

filter Get-EventMessage ([switch]$MessageOnly) {
  if ($MessageOnly) { Out-Host -InputObject $_.Message }
  else { $_ }
}

Ini dapat digunakan sebagai berikut:

Get-WinEvent -LogName System -MaxEvents 100 | Get-EventMessage -MessageOnly

Metode pemrosesan input

Metode yang dijelaskan di bagian ini disebut sebagai metode pemrosesan input. Untuk fungsi, ketiga metode ini bernama menggunakan 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 data blok dari alur, dan end blok untuk pasca-pemrosesan satu kali.

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

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

Jika fungsi dipanggil tanpa input alur, PowerShell process menjalankan blok hanya 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 menerima input alur, dan process blok tidak ditentukan, pemrosesan rekaman demi rekaman gagal. Dalam hal ini, fungsi Anda hanya dijalankan sekali, terlepas dari input.

`end`

Gunakan blok ini 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:

ketika eksekusi alur selesai tanpa mengakhiri kesalahan
ketika eksekusi alur terganggu karena kesalahan penghentian
saat alur dipotong, misalnya: Select-Object -First
ketika alur 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. Anda masih dapat memanggil perintah menggunakan operator panggilan (& clean).

Fungsi sederhana

Fungsi tidak harus rumit untuk berguna. Fungsi paling sederhana memiliki format berikut:

function <function-name> { statements }

Misalnya, fungsi berikut memulai PowerShell dengan opsi Jalankan sebagai Administrator .

function Start-PSAdmin { Start-Process PowerShell -Verb RunAs }

Untuk menggunakan fungsi , ketik: Start-PSAdmin

Untuk menambahkan pernyataan ke fungsi, ketik setiap pernyataan pada baris terpisah, atau gunakan titik koma (;) untuk memisahkan pernyataan.

Misalnya, fungsi berikut menemukan semua .jpg file di direktori pengguna saat ini yang diubah setelah tanggal mulai.

function Get-NewPicture {
  $start = Get-Date -Month 1 -Day 1 -Year 2010
  $allPics = Get-ChildItem -Path $Env:USERPROFILE\*.jpg -Recurse
  $allPics | Where-Object {$_.LastWriteTime -gt $Start}
}

Anda dapat membuat kotak alat dari fungsi kecil yang berguna. Tambahkan fungsi ini ke profil PowerShell Anda, seperti yang dijelaskan dalam about_Profiles dan yang lebih baru dalam artikel ini.

Nama fungsi

Anda dapat menetapkan nama apa pun ke fungsi. Namun, untuk fungsi yang Anda bagikan dengan orang lain, Anda harus mengikuti aturan penamaan PowerShell standar.

Nama harus terdiri dari pasangan kata kerja-kata benda di mana kata kerja mengidentifikasi tindakan yang dilakukan fungsi dan kata benda mengidentifikasi item tempat cmdlet melakukan tindakan.
Nama harus menggunakan kata kerja yang disetujui untuk semua perintah PowerShell. Menggunakan kata kerja yang disetujui menciptakan konsistensi bagi pengguna.

Untuk informasi selengkapnya tentang kata kerja PowerShell standar, lihat Kata Kerja yang Disetujui.

Fungsi dengan parameter

Anda dapat menggunakan parameter dengan fungsi, termasuk parameter bernama, parameter posisi, parameter sakelar, dan parameter dinamis. Untuk informasi selengkapnya tentang parameter dinamis dalam fungsi, lihat about_Functions_Advanced_Parameters.

Parameter bernama

Anda dapat menentukan sejumlah parameter bernama. Anda dapat menyertakan nilai default untuk parameter bernama, seperti yang dijelaskan nanti di artikel ini.

Anda dapat menentukan parameter di dalam kurung kurawal menggunakan param kata kunci, seperti yang ditunjukkan dalam sintaks sampel berikut:

function <name> {
  param ([type]$Parameter1 [,[type]$Parameter2])
  <statement list>
}

Anda juga dapat menentukan parameter di luar kurung kurawal tanpa param kata kunci, seperti yang ditunjukkan dalam sintaks sampel berikut:

function <name> [([type]$Parameter1[,[type]$Parameter2])] {
  <statement list>
}

Misalnya, fungsi berikut menggunakan sintaks alternatif untuk menentukan dua parameter:

function Add-Numbers([int]$One, [int]$Two) {
    $One + $Two
}

Meskipun metode pertama lebih disukai, tidak ada perbedaan antara kedua metode ini.

Saat Anda menjalankan fungsi, nilai yang Anda berikan untuk parameter ditetapkan ke variabel yang berisi nama parameter. Nilai variabel tersebut dapat digunakan dalam fungsi .

Contoh berikut adalah fungsi yang disebut Get-SmallFiles. Fungsi ini memiliki $Size parameter . Fungsi ini menampilkan semua file yang lebih kecil dari $Size nilai parameter, dan mengecualikan direktori:

function Get-SmallFiles {
  param ($Size)
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

Dalam fungsi , Anda dapat menggunakan $Size variabel , yang merupakan nama yang ditentukan untuk parameter .

Untuk menggunakan fungsi ini, ketik perintah berikut:

Get-SmallFiles -Size 50

Anda juga dapat memasukkan nilai untuk parameter bernama tanpa nama parameter. Misalnya, perintah berikut memberikan hasil yang sama dengan perintah yang memberi nama parameter Ukuran :

Get-SmallFiles 50

Untuk menentukan nilai default untuk parameter, ketik tanda sama dengan dan nilai setelah nama parameter, seperti yang ditunjukkan dalam variasi Get-SmallFiles contoh berikut:

function Get-SmallFiles ($Size = 100) {
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

Jika Anda mengetik Get-SmallFiles tanpa nilai, fungsi menetapkan 100 ke $size. Jika Anda memberikan nilai, fungsi menggunakan nilai tersebut.

Secara opsional, Anda dapat memberikan string bantuan singkat yang menjelaskan nilai default parameter Anda, dengan menambahkan atribut PSDefaultValue ke deskripsi parameter Anda, dan menentukan properti Bantuan PSDefaultValue. Untuk memberikan string bantuan yang menjelaskan nilai default (100) parameter Ukuran dalam Get-SmallFiles fungsi, tambahkan atribut PSDefaultValue seperti yang ditunjukkan dalam contoh berikut.

function Get-SmallFiles {
  param (
      [PSDefaultValue(Help = '100')]
      $Size = 100
  )
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

Untuk informasi selengkapnya tentang kelas atribut PSDefaultValue , lihat Anggota Atribut PSDefaultValue.

Parameter posisi

Parameter posisi adalah parameter tanpa nama parameter. PowerShell menggunakan urutan nilai parameter untuk mengaitkan setiap nilai parameter dengan parameter dalam fungsi.

Saat Anda menggunakan parameter posisi, ketik satu atau beberapa nilai setelah nama fungsi. Nilai parameter posisi ditetapkan ke $args variabel array. Nilai yang mengikuti nama fungsi ditetapkan ke posisi pertama dalam $args array, $args[0].

Fungsi berikut Get-Extension menambahkan .txt ekstensi nama file ke nama file yang Anda berikan:

function Get-Extension {
  $name = $args[0] + ".txt"
  $name
}

Get-Extension myTextFile

myTextFile.txt

Parameter beralih

Sakelar adalah parameter yang tidak memerlukan nilai. Sebagai gantinya, Anda mengetikkan nama fungsi diikuti dengan nama parameter pengalihan.

Untuk menentukan parameter pengalihan, tentukan jenis [switch] sebelum nama parameter, seperti yang ditunjukkan dalam contoh berikut:

function Switch-Item {
  param ([switch]$On)
  if ($On) { "Switch on" }
  else { "Switch off" }
}

Saat Anda mengetik On parameter sakelar setelah nama fungsi, fungsi akan menampilkan Switch on. Tanpa parameter pengalihan, parameter akan menampilkan Switch off.

Switch-Item -On

Switch on

Switch-Item

Switch off

Anda juga dapat menetapkan nilai Boolean ke sakelar saat menjalankan fungsi, seperti yang diperlihatkan dalam contoh berikut:

Switch-Item -On:$true

Switch on

Switch-Item -On:$false

Switch off

Gunakan splatting untuk meneruskan nilai parameter

Anda dapat menggunakan splatting untuk mewakili parameter perintah. Fitur ini diperkenalkan di Windows PowerShell 3.0.

Gunakan teknik ini dalam fungsi yang memanggil perintah dalam sesi. Anda tidak perlu mendeklarasikan atau menghitung parameter perintah, atau mengubah fungsi saat parameter perintah berubah.

Contoh fungsi berikut memanggil Get-Command cmdlet. Perintah menggunakan @args untuk mewakili parameter Get-Command.

function Get-MyCommand { Get-Command @args }

Anda dapat menggunakan semua parameter Get-Command saat memanggil Get-MyCommand fungsi. Parameter dan nilai parameter diteruskan ke perintah menggunakan @args.

Get-MyCommand -Name Get-ChildItem

CommandType     Name                ModuleName
-----------     ----                ----------
Cmdlet          Get-ChildItem       Microsoft.PowerShell.Management

Fitur ini @args menggunakan $args parameter otomatis, yang mewakili parameter dan nilai cmdlet yang tidak dinyatakan dari argumen yang tersisa.

Untuk informasi selengkapnya, lihat about_Splatting.

Piping objek ke fungsi

Fungsi apa pun dapat mengambil input dari alur. Anda dapat mengontrol bagaimana fungsi memproses input dari alur menggunakan beginkata kunci , , processend, dan clean . Contoh sintaks berikut menunjukkan kata kunci ini:

Daftar process pernyataan berjalan satu kali untuk setiap objek dalam alur. process Saat blok berjalan, setiap objek alur ditetapkan ke $_ variabel otomatis, satu objek alur pada satu waktu.

Fungsi berikut menggunakan process kata kunci. Fungsi menampilkan nilai dari alur:

function Get-Pipeline
{
  process {"The value is: $_"}
}

1, 2, 4 | Get-Pipeline

The value is: 1
The value is: 2
The value is: 4

Jika Anda menginginkan fungsi yang dapat mengambil input atau input alur dari parameter, maka process blok perlu menangani kedua kasus. Contohnya:

function Get-SumOfNumbers {
    param (
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
        if ($null -ne $Numbers) {
           foreach ($n in $Numbers) {
               $retValue += $n
           }
        } else {
           $retValue += $_
        }
    }

    end { $retValue }
}

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

Saat Anda menggunakan fungsi dalam alur, objek yang disalurkan ke fungsi ditetapkan ke $input variabel otomatis. Fungsi ini menjalankan pernyataan dengan begin blok skrip sebelum objek apa pun berasal dari alur. Fungsi ini menjalankan pernyataan dengan end blok skrip ketika tidak ada lagi objek dalam alur.

Contoh berikut menunjukkan variabel otomatis yang $input digunakan di blok skrip dan begin intend.

function Get-PipelineBeginEnd {
    begin   { "Begin: The input is $input" }
    end     { "End:   The input is $input" }
}

Saat Anda menjalankan fungsi dengan input alur, fungsi akan menampilkan hasil berikut:

1, 2, 4 | Get-PipelineBeginEnd

Begin: The input is
End:   The input is 1 2 4

begin Saat pernyataan berjalan, fungsi tidak memiliki input dari alur. Pernyataan end berjalan setelah fungsi memiliki nilai .

Jika fungsi memiliki process kata kunci, setiap objek di $input dihapus dari $input dan ditetapkan ke $_. Contoh berikut memiliki process daftar pernyataan:

function Get-PipelineInput
{
    process {"Processing:  $_ " }
    end     {"End:   The input is: $input" }
}

Dalam contoh ini, setiap objek yang disalurkan ke fungsi dikirim ke process daftar pernyataan. Pernyataan process berjalan pada setiap objek, satu objek pada satu waktu. Variabel $input otomatis kosong ketika fungsi mencapai end kata kunci.

1, 2, 4 | Get-PipelineInput

Processing:  1
Processing:  2
Processing:  4
End:   The input is:

Untuk informasi selengkapnya, lihat Menggunakan Enumerator

PowerShell 7.3 menambahkan clean blok. clean Blok adalah cara mudah bagi pengguna untuk membersihkan sumber daya yang dibuat dan digunakan dalam beginblok , 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
saat alur dipotong, misalnya: Select-Object -First
ketika alur dihentikan oleh Ctrl+C atau StopProcessing()

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

Cakupan fungsi

Fungsi ada dalam cakupan tempat Anda membuatnya.

Jika fungsi adalah bagian dari skrip, fungsi tersedia untuk pernyataan dalam skrip tersebut. Secara default, fungsi dalam skrip tidak tersedia di luar skrip tersebut.

Anda dapat menentukan cakupan fungsi. Misalnya, fungsi ditambahkan ke cakupan global dalam contoh berikut:

function Global:Get-DependentSvs {
  Get-Service | Where-Object {$_.DependentServices}
}

Saat fungsi berada dalam cakupan global, Anda dapat menggunakan fungsi dalam skrip, dalam fungsi, dan di baris perintah.

Functions membuat cakupan baru. Item yang dibuat dalam fungsi, seperti variabel, hanya ada dalam cakupan fungsi.

Untuk informasi selengkapnya, lihat about_Scopes.

Menemukan dan mengelola fungsi menggunakan `Function:` drive

Semua fungsi dan filter di PowerShell secara otomatis disimpan di Function: drive. Drive ini diekspos oleh penyedia Fungsi PowerShell.

Saat merujuk ke Function: drive, ketik titik dua setelah Fungsi, seperti yang akan Anda lakukan saat merujuk C atau D drive komputer.

Perintah berikut menampilkan semua fungsi dalam sesi PowerShell saat ini:

Get-ChildItem Function:

Perintah dalam fungsi disimpan sebagai blok skrip dalam properti definisi fungsi. Misalnya, untuk menampilkan perintah dalam fungsi Bantuan yang disertakan dengan PowerShell, ketik:

(Get-ChildItem Function:help).Definition

Anda juga dapat menggunakan sintaks berikut.

$Function:help

Untuk informasi selengkapnya, lihat about_Function_Provider.

Menggunakan kembali fungsi dalam sesi baru

Saat Anda mengetik fungsi di prompt perintah PowerShell, fungsi menjadi bagian dari sesi saat ini. Fungsi ini tersedia hingga sesi berakhir.

Untuk menggunakan fungsi Anda di semua sesi PowerShell, tambahkan fungsi ke profil PowerShell Anda. Untuk informasi selengkapnya tentang profil, lihat about_Profiles.

Anda juga dapat menyimpan fungsi Anda dalam file skrip PowerShell. Ketik fungsi Anda dalam file teks, lalu simpan file dengan .ps1 ekstensi nama file.

Membuat Bantuan untuk fungsi

Get-Help Cmdlet mendapatkan bantuan untuk fungsi, cmdlet, penyedia, dan skrip. Untuk mendapatkan bantuan untuk fungsi, ketik Get-Help diikuti dengan nama fungsi.

Misalnya, untuk mendapatkan bantuan untuk fungsi, Get-MyDisks ketik:

Get-Help Get-MyDisks

Anda dapat menulis bantuan untuk fungsi menggunakan salah satu dari dua metode berikut:

Bantuan Berbasis Komentar untuk Fungsi

Buat bantuan menggunakan kata kunci khusus di komentar. Untuk membuat bantuan berbasis komentar untuk fungsi, komentar harus ditempatkan di awal, akhir, atau dalam isi fungsi. Untuk informasi selengkapnya tentang bantuan berbasis komentar, lihat about_Comment_Based_Help.
Bantuan Berbasis XML untuk Fungsi

Bantuan berbasis XML diperlukan jika Anda perlu melokalisasi konten bantuan ke dalam beberapa bahasa. Untuk mengaitkan fungsi dengan file bantuan berbasis XML, gunakan .EXTERNALHELP kata kunci bantuan berbasis komentar. Tanpa kata kunci ini, Get-Help tidak dapat menemukan file bantuan fungsi dan hanya mengembalikan bantuan yang dibuat secara otomatis.

Untuk informasi selengkapnya tentang .EXTERNALHELP kata kunci, lihat about_Comment_Based_Help. Untuk informasi selengkapnya tentang bantuan berbasis XML, lihat Cara Menulis Bantuan Cmdlet.