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.

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: 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

Handles  NPM(K)    PM(K)      WS(K)     CPU(s)     Id  SI ProcessName
-------  ------    -----      -----     ------     --  -- -----------
    830      50   115840      95524      16.75   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.