Aracılığıyla paylaş


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 $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ğ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 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ş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 $commonParamsdeğerinin yerini almak için içindeki Location parametresini New-AzVmLocation 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 @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 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.

Ayrıca bkz.