about_Splatting
Kısa açıklama
PowerShell'deki komutlara parametre geçirmek için splatting'in nasıl kullanılacağını açıklar.
Uzun açıklama
Splatting, parametre değerleri koleksiyonunu bir komuta birim olarak geçirme yöntemidir. PowerShell koleksiyondaki her değeri bir komut parametresiyle ilişkilendirir. Splatted parametre değerleri, standart değişkenler gibi görünen ancak dolar işareti$ () yerine At simgesi (@) ile başlayan adlandırılmış splatting değişkenlerinde depolanır. At simgesi PowerShell'e tek bir değer yerine bir değer koleksiyonu geçirdiğiniz bildirir.
Splatting, komutlarınızın daha kısa ve okunmasını kolaylaştırır. Splatting 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 splatting kullanabilirsiniz.
Windows PowerShell 3.0'da başlayarak, bir komutun tüm parametrelerini göstermek için splatting de kullanabilirsiniz.
Sözdizimi
<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. Splatting kullanarak bazı parametreleri geçirebilir ve diğerlerini konuma veya parametre adına göre geçirebilirsiniz. Ayrıca, her parametre için birden fazla değer geçirmemesi için tek bir komutta birden çok nesne sıçratabilirsiniz.
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 splatmak 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 eklendiği 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 tablo 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 $Falsekullanı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ğer değil. PowerShell'de karma tabloların söz dizimi şöyledir: @{<name>=<value>; <name>=<value>; ...}
Dizilerle sıçrama
Parametre adları gerektirmeyen konumsal parametrelerin değerlerini splatmak 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 sarmalanı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ıçramayı 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 tablo 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 variableiç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şkeni 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şlevden işleve Test2 geçirilen parametre değerlerini işleve iletmek için değişkenini Test1 kullanırız$PSBoundParameters. İşleve Test1 yapılan her iki çağrı da Test2 splatting işlevini kullanır.
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 kullanışlıdır.
değişkeni, $commonParams konumda sanal makine 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ı yapıyoruz $commonParams . Ancak, diğer sanal makinelerden farklı bir bölgede oluşturulmasını istiyoruz myVM2 . Hashtable'ı ayarlamak $commonParams yerine, içindeki anahtarın $commonParamsdeğerinin Location yerini almak için içindeki Location parametresini New-AzVm 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ımlanı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 splatting kullanabilirsiniz. Bu teknik, başka bir komutu çağıran bir proxy işlevi, yani bir işlev oluştururken kullanışlıdır. Bu özellik Windows PowerShell 3.0'da kullanıma sunulmuştur.
Bir komutun parametrelerini splatmak için komutunu kullanarak @Args komut parametrelerini temsil edin. Bu teknik, komut parametrelerini numaralandırmaktan 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 , aşağıdaki komutlarda gösterildiği gibi atanmamış tüm parametreler ve parametre değerleri öğesine @Argsgeçirilir.
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 . İşlevde birden çok kez kullanabilirsiniz, ancak girdiğiniz tüm parametreler, aşağıdaki örnekte gösterildiği gibi tüm örneklerine @Argsgeç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 İstenen Durum Yapılandırması (DSC), sıçrama kullanacak şekilde tasarlanmamıştır. Değerleri bir DSC kaynağına geçirmek için splatting kullanamazsınız. Daha fazla bilgi için Gael Colas'ın DSC Kaynaklarını Sahte Platforma Alma makalesine bakın.
Ayrıca bkz.
PowerShell