about_Splatting

Cikk
01/29/2024

Rövid leírás

Ez a cikk azt ismerteti, hogyan adhat át paramétereket a powershell-parancsoknak a splatting használatával.

Hosszú leírás

A splatting egy metódus, a paraméterértékek gyűjteményének egy parancsnak egységként való átadására. A PowerShell a gyűjtemény minden értékét egy parancsparaméterrel társítja. A splatted paraméterértékek nevesített szórásváltozókban vannak tárolva, amelyek normál változóknak tűnnek, de a dollárjel () helyett egy At szimbólummal (@$) kezdődnek. A At szimbólum azt jelzi a PowerShellnek, hogy egyetlen érték helyett egy értékgyűjteményt ad át.

A splatting rövidebbé és könnyebben olvashatóvá teszi a parancsokat. A splatting értékeket újra felhasználhatja különböző parancshívásokban, és a splatting használatával paraméterértékeket adhat át az $PSBoundParameters automatikus változóból más szkripteknek és függvényeknek.

A Windows PowerShell 3.0-tól kezdve a parancsok összes paraméterét splatting használatával is ábrázolhatja.

Syntax

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

Ha paraméterértékeket szeretne megadni a pozícióparaméterekhez, amelyekben nincs szükség paraméternevekre, használja a tömb szintaxisát. Paraméternév és értékpárok megadásához használja a kivonattábla szintaxisát. A splatted érték bárhol megjelenhet a paraméterlistában.

A splatting során nem kell kivonattáblát vagy tömböt használnia az összes paraméter átadásához. Bizonyos paramétereket a splatting használatával adhat át, másokat pedig pozíció vagy paraméternév alapján adhat át. Emellett egyetlen parancsban több objektumot is splatálhat, hogy ne adjon át egynél több értéket az egyes paramétereknek.

A PowerShell 7.1-ben felülbírálhat egy splatted paramétert úgy, hogy explicit módon definiál egy paramétert egy parancsban.

Splatting kivonattáblákkal

Használjon kivonattáblát a paraméternév és az értékpárok összeillesztéséhez. Ezt a formátumot minden paramétertípushoz használhatja, beleértve a pozíció- és kapcsolóparamétereket is. A pozícióparamétereket név szerint kell hozzárendelni.

Az alábbi példák két Copy-Item parancsot hasonlítanak össze, amelyek a Test.txt fájlt az ugyanabban a könyvtárban lévő Test2.txt fájlba másolja.

Az első példa a paraméternevek hagyományos formátumát használja.

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

A második példa kivonattáblázat-platformot használ. Az első parancs létrehoz egy paraméternév- és paraméter-érték párok kivonattábláját, és tárolja azt a $HashArguments változóban. A második parancs a változót $HashArguments használja egy splatting parancsban. Az At szimbólum (@HashArguments) a dollárjelet ($HashArguments) helyettesíti a parancsban.

A WhatIf kapcsolóparaméter értékének megadásához használja $True vagy$False.

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

Feljegyzés

Az első parancsban az At szimbólum (@) egy kivonattáblát jelöl, nem pedig a fonott értéket. A PowerShell kivonattábláinak szintaxisa a következő: @{<name>=<value>; <name>=<value>; ...}

Splatting tömbökkel

Egy tömb használatával olyan pozícióparaméterek értékeit splatálhatja, amelyek nem igényelnek paraméterneveket. Az értékeknek pozíció-szám sorrendben kell lenniük a tömbben.

Az alábbi példák két Copy-Item parancsot hasonlítanak össze, amelyek a Test.txt fájlt az ugyanabban a könyvtárban lévő Test2.txt fájlba másolja.

Az első példa azt a hagyományos formátumot használja, amelyben a paraméternevek ki vannak hagyva. A paraméterértékek pozíció sorrendben jelennek meg a parancsban.

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

A második példa tömbplatformot használ. Az első parancs létrehoz egy tömböt a paraméterértékek közül, és tárolja a $ArrayArguments változóban. Az értékek pozíció sorrendben vannak a tömbben. A második parancs a $ArrayArguments splatting parancs változóját használja. Az At szimbólum (@ArrayArguments) a dollárjelet ($ArrayArguments) helyettesíti a parancsban.

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

Az ArgumentList paraméter használata

Több parancsmag rendelkezik egy ArgumentList paraméterrel, amellyel paraméterértékeket ad át a parancsmag által végrehajtott szkriptblokknak. Az Argumentumlista paraméter a szkriptblokknak átadott értékek tömbje. A PowerShell hatékonyan tömbplatform használatával köti össze az értékeket a szkriptblokk paramétereivel. Az Argumentumlista használatakor, ha egyetlen paraméterhez kötött objektumként kell átadnia egy tömböt, akkor a tömböt egy másik tömb egyetlen elemeként kell burkolnia.

Az alábbi példában egy szkriptblokk található, amely egyetlen paramétert vesz igénybe, amely sztringek tömbje.

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

Ebben a példában $array csak az első elem lesz átadva a szkriptblokknak.

Hello

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

Ebben a példában egy tömbbe van burkolva, $array hogy a teljes tömb egyetlen objektumként legyen átadva a szkriptblokknak.

Hello World!

Példák

1. példa: A kiszúrt paraméterek újrafelhasználása különböző parancsokban

Ez a példa bemutatja, hogyan használhatja újra a fonott értékeket különböző parancsokban. A példában szereplő parancsok a Write-Host parancsmaggal írnak üzeneteket a gazdagép programkonzoljára. Splatting használatával adja meg az előtér- és háttérszíneket.

Az összes parancs színének módosításához módosítsa a változó értékét $Colors .

Az első parancs létrehoz egy paraméternevekből és értékekből álló kivonattáblát, és a kivonattáblát a $Colors változóban tárolja.

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

A második és a harmadik parancs a változót használja a $Colors parancsban való Write-Host splattinghoz. A függvény használatához $Colors variablecserélje le a dollárjelet ($Colors) egy At () jelre.@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."

2. példa: Paraméterek továbbítása $PSBoundParameters

Ez a példa bemutatja, hogyan továbbíthatja a paramétereket más parancsoknak a splatting és az $PSBoundParameters automatikus változó használatával.

Az $PSBoundParameters automatikus változó egy szótárobjektum (System.Collections.Generic.Dictionary), amely tartalmazza a szkriptek vagy függvények futtatásakor használt összes paraméternevet és értéket.

Az alábbi példában a változóval továbbítjuk a $PSBoundParameters szkriptnek vagy függvénynek átadott paraméterértékeket a Test1 függvénynekTest2. Mindkét hívás a Test1 függvényhez Test2 a splatting használatával.

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

3. példa: Splatted paraméterek felülbírálása explicit módon definiált paraméterekkel

Ez a példa bemutatja, hogyan bírálhat felül egy splatted paramétert explicit módon definiált paraméterekkel. Ez akkor hasznos, ha nem szeretne új kivonatolót létrehozni, vagy módosítani egy értéket a splathoz használt kivonatolóban.

A $commonParams változó tárolja a paramétereket, hogy virtuális gépeket hozzon létre a East US helyen. A $allVms változó a létrehozandó virtuális gépek listája. Végigfuttatjuk a listát, és a paramétereket az egyes virtuális gépek létrehozásához használjuk $commonParams . Azonban a többi virtuális gépétől eltérő régióban szeretnénk myVM2 létrehozni. A kivonatoló módosítása $commonParams helyett explicit módon megadhatja a Location paramétert New-AzVm a kulcs értékének felülírásához a Location következőben $commonParams: .

$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
    }
}

4. példa: Több fonott objektum használata egyetlen parancsban

Egyetlen parancsban több fonott objektumot is használhat. Ebben a példában a különböző paraméterek külön kivonattáblákban vannak definiálva. A kivonatolók egyetlen Write-Host parancsban vannak kicsomagolva.

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

Splatting parancsparaméterek

A splatting használatával egy parancs paramétereit jelölheti. Ez a technika akkor hasznos, ha proxyfüggvényt, vagyis egy másik parancsot meghívó függvényt hoz létre. Ez a funkció a Windows PowerShell 3.0-ban jelenik meg.

A parancs paramétereinek splatolásához használja @Args a parancsparamétereket. Ez a technika egyszerűbb, mint a parancsparaméterek számbavétele, és akkor is korrektúra nélkül működik, ha az úgynevezett parancs paraméterei módosulnak.

A funkció az automatikus változót $Args használja, amely az összes hozzárendeletlen paraméterértéket tartalmazza.

Az alábbi függvény például meghívja a Get-Process parancsmagot. Ebben a függvényben @Args a parancsmag összes paraméterét Get-Process jelöli.

function Get-MyProcess { Get-Process @Args }

A függvény használatakor a Get-MyProcess rendszer az összes hozzárendeletlen paramétert és paraméterértéket átadja @Argsa következő parancsoknak.

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\...

Olyan függvényekben is használható @Args , amelyek kifejezetten deklarált paraméterekkel rendelkezik. Egy függvényben többször is használhatja, de a megadott paramétereket a rendszer az alábbi példában látható módon minden példánynak @Argsátadja.

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)

Jegyzetek

Ha a ParancsmagBinding vagy a Paraméter attribútumok használatával speciális függvényt hoz létre, az $args automatikus változó már nem érhető el a függvényben. A speciális függvények explicit paraméterdefiníciót igényelnek.

A PowerShell Desired State Configuration (DSC) nem splatting használatára lett tervezve. Nem használhat splattingot az értékek DSC-erőforrásba való továbbításához. További információkért lásd Gael Colas Pseudo-Splatting DSC Resources című cikkét.