Bagikan melalui

about_Splatting

  • Artikel

Deskripsi singkat

Menjelaskan cara menggunakan splatting untuk meneruskan parameter ke perintah di PowerShell.

Deskripsi panjang

Splatting adalah metode meneruskan kumpulan nilai parameter ke perintah sebagai unit. PowerShell mengaitkan setiap nilai dalam koleksi dengan parameter perintah. Nilai parameter berceceran disimpan dalam variabel splatting bernama, yang terlihat seperti variabel standar, tetapi dimulai dengan simbol At (@) alih-alih tanda dolar ($). Simbol At memberi tahu PowerShell bahwa Anda meneruskan kumpulan nilai, bukan satu nilai.

Splatting membuat perintah Anda lebih pendek dan lebih mudah dibaca. Anda dapat menggunakan kembali nilai splatting dalam panggilan perintah yang berbeda dan menggunakan splatting untuk meneruskan nilai parameter dari $PSBoundParameters variabel otomatis ke skrip dan fungsi lain.

Dimulai di Windows PowerShell 3.0, Anda juga dapat menggunakan splatting untuk mewakili semua parameter perintah.

Sintaks

<CommandName> <optional parameters> @<HashTable> <optional parameters>
<CommandName> <optional parameters> @<Array> <optional parameters>

Untuk menyediakan nilai parameter untuk parameter posisi, di mana nama parameter tidak diperlukan, gunakan sintaks array. Untuk memberikan nama parameter dan pasangan nilai, gunakan sintaks tabel hash. Nilai yang tercecer dapat muncul di mana saja dalam daftar parameter.

Saat melakukan splatting, Anda tidak perlu menggunakan tabel hash atau array untuk meneruskan semua parameter. Anda dapat meneruskan beberapa parameter dengan menggunakan splatting dan meneruskan yang lain berdasarkan posisi atau berdasarkan nama parameter. Selain itu, Anda dapat memercikkan beberapa objek dalam satu perintah sehingga Anda tidak meneruskan lebih dari satu nilai untuk setiap parameter.

Splatting dengan tabel hash

Gunakan tabel hash untuk memercikkan nama parameter dan pasangan nilai. Anda dapat menggunakan format ini untuk semua jenis parameter, termasuk parameter posisi dan pengalihan. Parameter posisi harus ditetapkan berdasarkan nama.

Contoh berikut membandingkan dua Copy-Item perintah yang menyalin file Test.txt dengan file Test2.txt di direktori yang sama.

Contoh pertama menggunakan format tradisional tempat nama parameter disertakan.

Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf

Contoh kedua menggunakan percikan tabel hash. Perintah pertama membuat tabel hash pasangan parameter-name dan parameter-value dan menyimpannya dalam $HashArguments variabel. Perintah kedua menggunakan $HashArguments variabel dalam perintah dengan splatting. Simbol At (@HashArguments) menggantikan tanda dolar ($HashArguments) dalam perintah.

Untuk memberikan nilai untuk parameter pengalihan WhatIf , gunakan $True atau $False.

$HashArguments = @{
  Path = "test.txt"
  Destination = "test2.txt"
  WhatIf = $true
}
Copy-Item @HashArguments

Catatan

Dalam perintah pertama, simbol At (@) menunjukkan tabel hash, bukan nilai splatted. Sintaks untuk tabel hash di PowerShell adalah: @{<name>=<value>; <name>=<value>; ...}

Splatting dengan array

Gunakan array untuk memercikkan nilai untuk parameter posisi, yang tidak memerlukan nama parameter. Nilai harus dalam urutan nomor posisi dalam array.

Contoh berikut membandingkan dua Copy-Item perintah yang menyalin file Test.txt dengan file Test2.txt di direktori yang sama.

Contoh pertama menggunakan format tradisional di mana nama parameter dihilangkan. Nilai parameter muncul dalam urutan posisi dalam perintah .

Copy-Item "test.txt" "test2.txt" -WhatIf

Contoh kedua menggunakan percikan array. Perintah pertama membuat array nilai parameter dan menyimpannya dalam $ArrayArguments variabel. Nilai berada dalam urutan posisi dalam array. Perintah kedua menggunakan $ArrayArguments variabel dalam perintah dalam splatting. Simbol At (@ArrayArguments) menggantikan tanda dolar ($ArrayArguments) dalam perintah.

$ArrayArguments = "test.txt", "test2.txt"
Copy-Item @ArrayArguments -WhatIf

Menggunakan parameter ArgumentList

Beberapa cmdlet memiliki parameter ArgumentList yang digunakan untuk meneruskan nilai parameter ke blok skrip yang dijalankan oleh cmdlet. Parameter ArgumentList mengambil array nilai yang diteruskan ke blok skrip. PowerShell secara efektif menggunakan array yang berceceran untuk mengikat nilai ke parameter blok skrip. Saat menggunakan ArgumentList, jika Anda perlu meneruskan array sebagai objek tunggal yang terikat ke satu parameter, Anda harus membungkus array sebagai satu-satunya elemen dari array lain.

Contoh berikut memiliki blok skrip yang mengambil satu parameter yang merupakan array string.

$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
  param([string[]]$words) $words -join ' '
  } -ArgumentList $array

Dalam contoh ini, hanya item pertama yang diteruskan $array ke blok skrip.

Hello

$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
  param([string[]]$words) $words -join ' '
} -ArgumentList (,$array)

Dalam contoh ini, $array dibungkus dalam array sehingga seluruh array diteruskan ke blok skrip sebagai objek tunggal.

Hello World!

Contoh

Contoh 1: Menggunakan kembali parameter yang di-splat dalam perintah yang berbeda

Contoh ini menunjukkan cara menggunakan kembali nilai yang di-splat dalam perintah yang berbeda. Perintah dalam contoh ini menggunakan Write-Host cmdlet untuk menulis pesan ke konsol program host. Ini menggunakan splatting untuk menentukan warna latar depan dan latar belakang.

Untuk mengubah warna semua perintah, cukup ubah nilai $Colors variabel.

Perintah pertama membuat tabel hash nama parameter dan nilai dan menyimpan tabel hash dalam $Colors variabel.

$Colors = @{ForegroundColor = "black"; BackgroundColor = "white"}

Perintah kedua dan ketiga menggunakan $Colors variabel untuk splatting dalam Write-Host perintah. Untuk menggunakan $Colors variable, ganti tanda dolar ($Colors) dengan simbol At (@Colors).

#Write a message with the colors in $Colors
Write-Host "This is a test." @Colors

#Write second message with same colors. The position of splatted
#hash table does not matter.
Write-Host @Colors "This is another test."

Contoh 2: Meneruskan parameter menggunakan $PSBoundParameters

Contoh ini menunjukkan cara meneruskan parameter mereka ke perintah lain menggunakan splatting dan $PSBoundParameters variabel otomatis.

Variabel $PSBoundParameters otomatis adalah objek kamus (System.Collections.Generic.Dictionary) yang berisi semua nama parameter dan nilai yang digunakan saat skrip atau fungsi dijalankan.

Dalam contoh berikut, kita menggunakan $PSBoundParameters variabel untuk meneruskan nilai parameter yang diteruskan ke skrip atau fungsi dari Test2 fungsi ke Test1 fungsi. Keduanya memanggil ke fungsi agar Test1Test2 tidak menggunakan splatting.

function Test1
{
    param($a, $b, $c)

    "a = $a"
    "b = $b"
    "c = $c"
}

function Test2
{
    param($a, $b, $c)

    #Call the Test1 function with $a, $b, and $c.
    Test1 @PSBoundParameters

    #Call the Test1 function with $b and $c, but not with $a
    Test1 -b $PSBoundParameters.b -c $PSBoundParameters.c
}

Test2 -a 1 -b 2 -c 3

a = 1
b = 2
c = 3
a =
b = 2
c = 3

Contoh 3: Menggunakan beberapa objek berceceran dalam satu perintah

Anda dapat menggunakan beberapa objek berceceran dalam satu perintah. Dalam contoh ini, parameter yang berbeda didefinisikan dalam hashtable terpisah. Hashtable diceburkan dalam satu Write-Host perintah.

$a = @{
    Message         = 'Hello', 'World!'
}
$b = @{
    Separator       = '|'
}
$c = @{
    BackgroundColor = 'Cyan'
    ForegroundColor = 'Black'
}
Write-Host @a @b @c

Parameter perintah splatting

Anda dapat menggunakan splatting untuk mewakili parameter perintah. Teknik ini berguna ketika Anda membuat fungsi proksi, yaitu fungsi yang memanggil perintah lain. Fitur ini diperkenalkan di Windows PowerShell 3.0.

Untuk memercikkan parameter perintah, gunakan @Args untuk mewakili parameter perintah. Teknik ini lebih mudah daripada menghitung parameter perintah dan berfungsi tanpa revisi bahkan jika parameter perintah yang disebut berubah.

Fitur ini menggunakan $Args variabel otomatis, yang berisi semua nilai parameter yang tidak ditetapkan.

Misalnya, fungsi berikut memanggil Get-Process cmdlet. Dalam fungsi ini, @Args mewakili semua parameter Get-Process cmdlet.

function Get-MyProcess { Get-Process @Args }

Saat Anda menggunakan fungsi , Get-MyProcess semua parameter dan nilai parameter yang tidak ditetapkan diteruskan ke @Args, seperti yang ditunjukkan pada perintah berikut.

Get-MyProcess -Name PowerShell

Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)     Id ProcessName
-------  ------    -----      ----- -----   ------     -- -----------
    463      46   225484     237196   719    15.86   3228 powershell

Get-MyProcess -Name PowerShell_Ise -FileVersionInfo

ProductVersion   FileVersion      FileName
--------------   -----------      --------
6.2.9200.16384   6.2.9200.1638... C:\Windows\system32\WindowsPowerShell\...

Anda dapat menggunakan @Args dalam fungsi yang memiliki parameter yang dideklarasikan secara eksplisit. Anda dapat menggunakannya lebih dari sekali dalam fungsi, tetapi semua parameter yang Anda masukkan diteruskan ke semua instans @Args, seperti yang ditunjukkan dalam contoh berikut.

function Get-MyCommand
{
    Param ([switch]$P, [switch]$C)
    if ($P) { Get-Process @Args }
    if ($C) { Get-Command @Args }
}

Get-MyCommand -P -C -Name PowerShell

Handles  NPM(K)    PM(K)      WS(K)     CPU(s)     Id  SI ProcessName
-------  ------    -----      -----     ------     --  -- -----------
    830      50   115840      95524      16.75   6880   1 powershell

Path               : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
Extension          : .exe
Definition         : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
Source             : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
Version            : 10.0.22621.3085
Visibility         : Public
OutputType         : {System.String}
Name               : powershell.exe
CommandType        : Application
ModuleName         :
Module             :
RemotingCapability : PowerShell
Parameters         :
ParameterSets      :
HelpUri            :
FileVersionInfo    : File:             C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
                     InternalName:     POWERSHELL
                     OriginalFilename: PowerShell.EXE.MUI
                     FileVersion:      10.0.22621.1 (WinBuild.160101.0800)
                     FileDescription:  Windows PowerShell
                     Product:          Microsoft&reg; Windows&reg; Operating System
                     ProductVersion:   10.0.22621.1
                     Debug:            False
                     Patched:          False
                     PreRelease:       False
                     PrivateBuild:     False
                     SpecialBuild:     False
                     Language:         English (United States)

Catatan

Jika Anda membuat fungsi menjadi fungsi tingkat lanjut dengan menggunakan atribut CmdletBinding atau Parameter , $args variabel otomatis tidak lagi tersedia dalam fungsi. Fungsi tingkat lanjut memerlukan definisi parameter eksplisit.

Konfigurasi Status yang Diinginkan PowerShell (DSC) tidak dirancang untuk menggunakan percikan. Anda tidak dapat menggunakan splatting untuk meneruskan nilai ke sumber daya DSC. Untuk informasi selengkapnya, lihat artikel Gael Colas Pseudo-Splatting DSC Resources.

Lihat juga