about_Splatting

Makale
01/29/2024

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&reg; Windows&reg; 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.