about_Functions

Artikel
03/13/2024

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. Pernyataan dalam daftar berjalan seolah-olah Anda telah mengetikkannya di prompt perintah.

Fungsi bisa sesinggah:

function Get-PowerShellProcess { Get-Process PowerShell }

Fungsi juga bisa serumit cmdlet atau aplikasi.

Seperti cmdlet, fungsi dapat memiliki parameter. Parameter dapat diberi nama, parameter posisi, sakelar, atau dinamis. Parameter fungsi dapat dibaca dari baris perintah atau dari alur.

Fungsi dapat mengembalikan nilai yang dapat ditampilkan, ditetapkan ke variabel, atau diteruskan ke fungsi atau cmdlet lain. Anda juga dapat menentukan nilai pengembalian menggunakan return kata kunci. 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.

Daftar pernyataan fungsi dapat berisi berbagai jenis daftar pernyataan dengan kata kunci begin, , processdan end. Pernyataan ini mencantumkan menangani input dari alur secara berbeda.

Kata kunci filter digunakan untuk membuat jenis fungsi yang berjalan pada setiap objek dalam alur. Filter menyerupan fungsi dengan semua pernyataannya dalam process blok.

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.

Sintaks

Berikut ini adalah sintaks untuk fungsi:

function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
}

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

Fungsi mencakup item berikut:

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

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

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.

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{}
}

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

`end`

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

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-NewPix
{
  $start = Get-Date -Month 1 -Day 1 -Year 2010
  $allpix = Get-ChildItem -Path $env:UserProfile\*.jpg -Recurse
  $allpix | Where-Object {$_.LastWriteTime -gt $Start}
}

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

Nama Fungsi

Anda dapat menetapkan nama apa pun ke fungsi, tetapi fungsi yang Anda bagikan dengan orang lain harus mengikuti aturan penamaan yang telah dibuat untuk semua perintah PowerShell.

Nama fungsi 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 tindakannya.

Fungsi harus menggunakan kata kerja standar yang telah disetujui untuk semua perintah PowerShell. Kata kerja ini membantu kami menjaga nama perintah kami tetap konsisten dan mudah dipahami 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 dalam topik 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>
}

Di bawah ini adalah contoh sintaks alternatif ini.

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

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

Beralih Parameter

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

Menggunakan Splatting untuk Mewakili Parameter Perintah

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 Objects to Functions

Fungsi apa pun dapat mengambil input dari alur. Anda dapat mengontrol bagaimana fungsi memproses input dari alur menggunakan beginkata kunci , , processdan end . 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 menjalankan pernyataan dengan begin kata kunci sebelum objek apa pun berasal dari alur. Fungsi menjalankan pernyataan dengan end kata kunci setelah semua objek diterima dari alur.

Contoh berikut menunjukkan $input variabel otomatis dengan begin kata kunci dan end .

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

Jika fungsi ini dijalankan menggunakan alur, fungsi ini 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

Filter

Filter adalah jenis fungsi yang berjalan pada setiap objek dalam alur. Filter menyerupan fungsi dengan semua pernyataannya dalam process blok.

Sintaks filter adalah sebagai berikut:

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

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

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

Ini dapat digunakan sebagai berikut:

Get-WinEvent -LogName System -MaxEvents 100 | Get-ErrorLog -Message

Cakupan Fungsi

Fungsi ada dalam cakupan tempat fungsi dibuat.

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 Fungsi: 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 tentang Function: drive, lihat topik bantuan untuk penyedia Fungsi . Ketik Get-Help Function.

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

Menulis Bantuan untuk Fungsi

Get-Help Cmdlet mendapatkan bantuan untuk fungsi, serta untuk 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 topik bantuan menggunakan kata kunci khusus di komentar. Untuk membuat bantuan berbasis komentar untuk fungsi, komentar harus ditempatkan di awal atau akhir isi fungsi atau pada baris sebelum kata kunci fungsi. Untuk informasi selengkapnya tentang bantuan berbasis komentar, lihat about_Comment_Based_Help.
Bantuan Berbasis XML untuk Fungsi

Buat topik bantuan berbasis XML, seperti jenis yang biasanya dibuat untuk cmdlet. Bantuan berbasis XML diperlukan jika Anda melokalisasi topik bantuan ke dalam beberapa bahasa.

Untuk mengaitkan fungsi dengan topik bantuan berbasis XML, gunakan .EXTERNALHELP kata kunci bantuan berbasis komentar. Tanpa kata kunci ini, Get-Help tidak dapat menemukan topik bantuan fungsi dan panggilan ke Get-Help untuk fungsi hanya mengembalikan bantuan yang dihasilkan 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.