about_Splatting
Kısa açıklama
PowerShell'deki komutlara parametre geçirmek için sıçramanın nasıl kullanılacağını açıklar.
Uzun açıklama
Splatting, parametre değerleri koleksiyonunu komuta birim olarak geçirme yöntemidir. PowerShell koleksiyondaki her değeri bir komut parametresiyle ilişkilendirir. Sıçramış parametre değerleri, standart değişkenler gibi görünen ancak dolar işareti$
() yerine At simgesiyle (@
) başlayan adlandırılmış sıçrama değişkenlerinde depolanır. At simgesi, PowerShell'e tek bir değer yerine bir değer koleksiyonu geçirdiğiniz bildirir.
Sıçratmak komutlarınızı daha kısa ve okunmasını kolaylaştırır. Sıçrama değerlerini farklı komut çağrılarında yeniden kullanabilir ve parametre değerlerini otomatik değişkenden $PSBoundParameters
diğer betiklere ve işlevlere geçirmek için sıçramayı kullanabilirsiniz.
Windows PowerShell 3.0'da başlayarak, bir komutun tüm parametrelerini temsil etmek için sıçrama özelliğini de kullanabilirsiniz.
Syntax
<CommandName> <optional parameters> @<HashTable> <optional parameters>
<CommandName> <optional parameters> @<Array> <optional parameters>
Parametre adlarının gerekli olmadığı konumsal parametreler için parametre değerleri sağlamak için dizi söz dizimini kullanın. Parametre adı ve değer çiftleri sağlamak için karma tablo söz dizimini kullanın. Sıçramış değer parametre listesinin herhangi bir yerinde görünebilir.
Sıçrarken, tüm parametreleri geçirmek için bir karma tablo veya dizi kullanmanız gerekmez. Bazı parametreleri, splatting kullanarak geçirebilir ve diğerlerini konuma veya parametre adına göre geçirebilirsiniz. Ayrıca, tek bir komutta birden çok nesne splatabilir ve böylece her parametre için birden fazla değer geçirmeyebilirsiniz.
PowerShell 7.1 itibarıyla, komutta açıkça bir parametre tanımlayarak bir sıçramış parametreyi geçersiz kılabilirsiniz.
Karma tablolarla sıçrama
Parametre adını ve değer çiftlerini sıçratmak için karma tablo kullanın. Konumsal ve anahtar parametreleri de dahil olmak üzere tüm parametre türleri için bu biçimi kullanabilirsiniz. Konumsal parametreler ada göre atanmalıdır.
Aşağıdaki örnekler, Test.txt dosyasını aynı dizindeki Test2.txt dosyasına kopyalayan iki Copy-Item
komutu karşılaştırır.
İlk örnek, parametre adlarının dahil olduğu geleneksel biçimi kullanır.
Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf
İkinci örnekte karma tablo sıçraması kullanılır. İlk komut parametre-adı ve parametre-değer çiftlerinden oluşan bir karma tablosu oluşturur ve bunu değişkende $HashArguments
depolar. İkinci komut, bir komuttaki değişkenini $HashArguments
splatting ile kullanır. At simgesi (@HashArguments
), komutundaki dolar işaretinin ($HashArguments
) yerini alır.
WhatIf anahtar parametresi için bir değer sağlamak için veya $False
kullanın$True
.
$HashArguments = @{
Path = "test.txt"
Destination = "test2.txt"
WhatIf = $true
}
Copy-Item @HashArguments
Not
İlk komutta, At simgesi (@
) bir karma tablo gösterir, sıçramış bir değeri değil. PowerShell'de karma tabloların söz dizimi şöyledir: @{<name>=<value>; <name>=<value>; ...}
Dizilerle sıçrama
Konumsal parametreler için parametre adları gerektirmeyen değerleri sıçratmak için bir dizi kullanın. Değerler dizideki konum-sayı sırasına göre olmalıdır.
Aşağıdaki örnekler, Test.txt dosyasını aynı dizindeki Test2.txt dosyasına kopyalayan iki Copy-Item
komutu karşılaştırır.
İlk örnek, parametre adlarının atlandığı geleneksel biçimi kullanır. Parametre değerleri, komutunda konum sırasına göre görüntülenir.
Copy-Item "test.txt" "test2.txt" -WhatIf
İkinci örnekte dizi sıçraması kullanılır. İlk komut parametre değerlerinin bir dizisini oluşturur ve değişkende $ArrayArguments
depolar. Değerler dizideki konum sırasına göredir. İkinci komut, splatting komutunda değişkenini kullanır $ArrayArguments
. At simgesi (@ArrayArguments
), komutundaki dolar işaretinin ($ArrayArguments
) yerini alır.
$ArrayArguments = "test.txt", "test2.txt"
Copy-Item @ArrayArguments -WhatIf
ArgumentList parametresini kullanma
Çeşitli cmdlet'ler, parametre değerlerini cmdlet tarafından yürütülen bir betik bloğuna geçirmek için kullanılan bir ArgumentList parametresine sahiptir. ArgumentList parametresi, betik bloğuna geçirilen bir değer dizisi alır. PowerShell, değerleri betik bloğunun parametrelerine bağlamak için dizi sıçramasını etkili bir şekilde kullanıyor. ArgumentList kullanırken, bir diziyi tek bir parametreye bağlı tek bir nesne olarak geçirmeniz gerekiyorsa, diziyi başka bir dizinin tek öğesi olarak sarmalamanız gerekir.
Aşağıdaki örnekte, dize dizisi olan tek bir parametreyi alan bir betik bloğu vardır.
$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
param([string[]]$words) $words -join ' '
} -ArgumentList $array
Bu örnekte, betik bloğuna yalnızca içindeki $array
ilk öğe geçirilir.
Hello
$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
param([string[]]$words) $words -join ' '
} -ArgumentList (,$array)
Bu örnekte, $array
dizinin tamamı betik bloğuna tek bir nesne olarak geçirilecek şekilde bir dizi içinde sarmalanmıştır.
Hello World!
Örnekler
Örnek 1: Farklı komutlarda sıçramış parametreleri yeniden kullanma
Bu örnekte, farklı komutlarda sıçramış değerlerin nasıl yeniden kullanılması gösterilmektedir. Bu örnekteki komutlar, konak program konsoluna Write-Host
ileti yazmak için cmdlet'ini kullanır. Ön plan ve arka plan renklerini belirtmek için sıçrama kullanır.
Tüm komutların renklerini değiştirmek için değişkenin $Colors
değerini değiştirmeniz gerekir.
İlk komut parametre adları ve değerlerinden oluşan bir karma tablosu oluşturur ve karma tablosunu değişkende $Colors
depolar.
$Colors = @{ForegroundColor = "black"; BackgroundColor = "white"}
İkinci ve üçüncü komutlar, bir Write-Host
komutta sıçramak için değişkenini $Colors
kullanır. kullanmak $Colors variable
için dolar işaretini ($Colors
) At simgesiyle (@Colors
) değiştirin.
#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."
Örnek 2: $PSBoundParameters kullanarak parametreleri iletme
Bu örnekte, splatting ve otomatik değişken kullanarak parametrelerini diğer komutlara nasıl iletecekleri gösterilmektedir $PSBoundParameters
.
Otomatik $PSBoundParameters
değişken, bir betik veya işlev çalıştırıldığında kullanılan tüm parametre adlarını ve değerlerini içeren bir sözlük nesnesidir (System.Collections.Generic.Dictionary).
Aşağıdaki örnekte, bir betik veya işleve geçirilen parametre değerlerini işlevden Test2
işleve iletmek için değişkenini Test1
kullanırız$PSBoundParameters
. Her iki çağrı da Test1
işleve splatting kullanımından Test2
çağrılar.
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
Örnek 3: Açıkça tanımlanmış parametrelerle sıçramış parametreleri geçersiz kılma
Bu örnekte, açıkça tanımlanmış parametreler kullanılarak bir sıçramış parametrenin nasıl geçersiz kılındığı gösterilmektedir. Bu, yeni bir karma tablo oluşturmak veya sıçramak için kullandığınız karma tablodaki bir değeri değiştirmek istemediğinizde yararlıdır.
değişkeni, $commonParams
konumda sanal makineler oluşturmak için parametreleri depolar East US
. $allVms
değişkeni oluşturulacak sanal makinelerin listesidir. Listede döngü yapıyoruz ve her sanal makineyi oluşturmak için parametrelerin sıçramasını kullanıyoruz $commonParams
. Ancak, diğer sanal makinelerden farklı bir bölgede oluşturulmasını istiyoruz myVM2
. Karma tabloyu $commonParams
ayarlamak yerine içindeki anahtarın $commonParams
değerinin yerini almak için içindeki Location parametresini New-AzVm
Location
açıkça tanımlayabilirsiniz.
$commonParams = @{
ResourceGroupName = "myResourceGroup"
Location = "East US"
VirtualNetworkName = "myVnet"
SubnetName = "mySubnet"
SecurityGroupName = "myNetworkSecurityGroup"
PublicIpAddressName = "myPublicIpAddress"
}
$allVms = @('myVM1','myVM2','myVM3',)
foreach ($vm in $allVms)
{
if ($vm -eq 'myVM2')
{
New-AzVm @commonParams -Name $vm -Location "West US"
}
else
{
New-AzVm @commonParams -Name $vm
}
}
Örnek 4: Tek bir komutta birden çok sıçramış nesne kullanma
Tek bir komutta birden çok sıçramış nesne kullanabilirsiniz. Bu örnekte, farklı parametreler ayrı karma tablolarda tanımlanmıştır. Karma tablolarda tek Write-Host
bir komut bulunur.
$a = @{
Message = 'Hello', 'World!'
}
$b = @{
Separator = '|'
}
$c = @{
BackgroundColor = 'Cyan'
ForegroundColor = 'Black'
}
Write-Host @a @b @c
Komut parametrelerinin sıçraması
Bir komutun parametrelerini temsil etmek için sıçratmayı kullanabilirsiniz. Bu teknik, bir ara sunucu işlevi, başka bir komutu çağıran bir işlev oluştururken yararlıdır. Bu özellik Windows PowerShell 3.0'da kullanıma sunulmuştur.
Bir komutun parametrelerini sıçratmak için komutunu kullanarak @Args
komut parametrelerini temsil edin. Bu teknik, komut parametrelerini listelemekten daha kolaydır ve çağrılan komutun parametreleri değişse bile düzeltme olmadan çalışır.
Özellik, atanmamış tüm parametre değerlerini içeren otomatik değişkeni kullanır $Args
.
Örneğin, aşağıdaki işlev cmdlet'ini Get-Process
çağırır. Bu işlevde, @Args
cmdlet'in Get-Process
tüm parametrelerini temsil eder.
function Get-MyProcess { Get-Process @Args }
işlevini kullandığınızda Get-MyProcess
, atanmamış tüm parametreler ve parametre değerleri, aşağıdaki komutlarda gösterildiği gibi öğesine geçirilir @Args
.
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\...
Açıkça parametreler bildirmiş bir işlevde kullanabilirsiniz @Args
. Bir işlevde birden çok kez kullanabilirsiniz, ancak girdiğiniz tüm parametreler, aşağıdaki örnekte gösterildiği gibi tüm örneklerine @Args
geçirilir.
function Get-MyCommand
{
Param ([switch]$P, [switch]$C)
if ($P) { Get-Process @Args }
if ($C) { Get-Command @Args }
}
Get-MyCommand -P -C -Name PowerShell
NPM(K) PM(M) WS(M) CPU(s) Id SI ProcessName
------ ----- ----- ------ -- -- -----------
50 112.76 78.52 16.64 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® Windows® Operating System
ProductVersion: 10.0.22621.1
Debug: False
Patched: False
PreRelease: False
PrivateBuild: False
SpecialBuild: False
Language: English (United States)
Notlar
CmdletBinding veya Parameter özniteliklerini kullanarak bir işlevi gelişmiş bir işleve dönüştürürseniz, $args
otomatik değişken artık işlevde kullanılamaz. Gelişmiş işlevler için açık parametre tanımı gerekir.
PowerShell Desired State Configuration (DSC), sıçrama kullanacak şekilde tasarlanmamıştır. Değerleri bir DSC kaynağına geçirmek için sıçramayı kullanamazsınız. Daha fazla bilgi için Gael Colas'ın Sahte Splatting DSC Kaynakları makalesine bakın.