about_Splatting

Článek
01/29/2024

Krátký popis

Popisuje, jak pomocí splattingu předat parametry příkazům v PowerShellu.

Dlouhý popis

Splatting je metoda předání kolekce hodnot parametrů příkazu jako jednotky. PowerShell přidruží každou hodnotu v kolekci k parametru příkazu. Splatted hodnoty parametrů jsou uloženy v pojmenovaných splatting proměnných, které vypadají jako standardní proměnné, ale začínají symbolem At (@) místo znaku dolaru ($). Symbol At říká PowerShellu, že předáváte kolekci hodnot místo jedné hodnoty.

Splatting zkracuje a usnadňuje čtení příkazů. Hodnoty splattingu můžete použít v různých voláních příkazů a pomocí splattingu předávat hodnoty parametrů z $PSBoundParameters automatické proměnné do jiných skriptů a funkcí.

Počínaje windows PowerShellem 3.0 můžete také použít splatting k reprezentaci všech parametrů příkazu.

Syntaxe

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

Pokud chcete zadat hodnoty parametrů pro poziční parametry, ve kterých se názvy parametrů nevyžadují, použijte syntaxi pole. Pokud chcete zadat páry názvu a hodnoty parametru, použijte syntaxi tabulky hash. Splattovaná hodnota se může zobrazit kdekoli v seznamu parametrů.

Při dělení nemusíte k předávání všech parametrů použít tabulku hash ani pole. Některé parametry můžete předat pomocí splattingu a předat jiné podle pozice nebo názvu parametru. V jednom příkazu můžete také splatovat více objektů, abyste pro každý parametr nepředáli více než jednu hodnotu.

Od PowerShellu 7.1 můžete přepsat splattovaný parametr explicitním definováním parametru v příkazu.

Splatting with hash tables

Ke spárování názvu parametru a hodnoty použijte tabulku hash. Tento formát můžete použít pro všechny typy parametrů, včetně pozičních parametrů a parametrů přepínače. Poziční parametry musí být přiřazeny názvem.

Následující příklady porovnávají dva Copy-Item příkazy, které zkopírují Test.txt soubor do Test2.txt souboru ve stejném adresáři.

První příklad používá tradiční formát, ve kterém jsou zahrnuty názvy parametrů.

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

Druhý příklad používá splatting tabulky hash. První příkaz vytvoří tabulku hash párů parametr-name a parametr-value a uloží ji do $HashArguments proměnné. Druhý příkaz používá $HashArguments proměnnou v příkazu s dělením. Symbol At (@HashArguments) nahradí znak dolaru ($HashArguments) v příkazu.

Chcete-li zadat hodnotu parametru WhatIf switch, použijte $True nebo $False.

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

Poznámka:

V prvním příkazu symbol At (@) označuje tabulku hash, nikoli splattovanou hodnotu. Syntaxe pro tabulky hash v PowerShellu je: @{<name>=<value>; <name>=<value>; ...}

Splatting with arrays

Hodnoty pozičních parametrů, které nevyžadují názvy parametrů, použijte matici. Hodnoty musí být v poli v pořadí pozice.

Následující příklady porovnávají dva Copy-Item příkazy, které zkopírují Test.txt soubor do Test2.txt souboru ve stejném adresáři.

První příklad používá tradiční formát, ve kterém jsou názvy parametrů vynechány. Hodnoty parametrů se v příkazu zobrazí v pořadí pozice.

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

Druhý příklad používá dělení polí. První příkaz vytvoří pole hodnot parametrů a uloží ho $ArrayArguments do proměnné. Hodnoty jsou v poli v pořadí pozice. Druhý příkaz používá $ArrayArguments proměnnou v příkazu v splattingu. Symbol At (@ArrayArguments) nahradí znak dolaru ($ArrayArguments) v příkazu.

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

Použití parametru ArgumentList

Několik rutin má parametr ArgumentList , který slouží k předání hodnot parametrů do bloku skriptu, který je spuštěn rutinou. Parametr ArgumentList přebírá pole hodnot, které jsou předány do bloku skriptu. PowerShell efektivně používá maticové splatting k vytvoření vazby hodnot na parametry bloku skriptu. Při použití ArgumentList, pokud potřebujete předat pole jako jeden objekt svázaný s jedním parametrem, musíte pole zabalit jako jediný prvek jiného pole.

Následující příklad obsahuje blok skriptu, který přebírá jeden parametr, který je polem řetězců.

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

V tomto příkladu se do bloku skriptu předá pouze první položka $array .

Hello

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

V tomto příkladu je zabalena do pole, $array aby se celé pole předalo do bloku skriptu jako jeden objekt.

Hello World!

Příklady

Příklad 1: Opakované použití splattovaných parametrů v různých příkazech

Tento příklad ukazuje, jak opakovaně používat splattované hodnoty v různýchpříkazch Příkazy v tomto příkladu používají rutinu k zápisu Write-Host zpráv do konzoly hostitelského programu. Používá k určení barev popředí a pozadí vrstvení.

Pokud chcete změnit barvy všech příkazů, stačí změnit hodnotu $Colors proměnné.

První příkaz vytvoří tabulku hash názvů parametrů a hodnot a uloží tabulku hash do $Colors proměnné.

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

Druhý a třetí příkazy používají $Colors proměnnou Write-Host pro splatting v příkazu. Chcete-li použít znak dolaru $Colors variable($Colors) symbolem At (@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."

Příklad 2: Předávání parametrů pomocí $PSBoundParameters

Tento příklad ukazuje, jak předat jejich parametry jiným příkazům pomocí splattingu $PSBoundParameters a automatické proměnné.

Automatická $PSBoundParameters proměnná je objekt slovníku (System.Collections.Generic.Dictionary), který obsahuje všechny názvy a hodnoty parametrů, které se používají při spuštění skriptu nebo funkce.

V následujícím příkladu $PSBoundParameters použijeme proměnnou k předání hodnot parametrů skriptu nebo funkci z Test2 funkce do Test1 funkce. Obě volání Test1 funkce z Test2 použití splattingu.

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

Příklad 3: Přepsání splattovaných parametrů explicitně definovanými parametry

Tento příklad ukazuje, jak přepsat splatted parametr pomocí explicitně definovaných parametrů. To je užitečné v případě, že nechcete vytvořit novou hashovací tabulku nebo změnit hodnotu v hashovatelné tabulce, kterou používáte ke splatování.

Proměnná $commonParams ukládá parametry pro vytvoření virtuálních počítačů v East US umístění. Proměnná $allVms je seznam virtuálních počítačů, které se mají vytvořit. Projdeme seznam a použijeme $commonParams k vytvoření jednotlivých virtuálních počítačů parametry. Chceme myVM2 ale vytvořit v jiné oblasti než ostatní virtuální počítače. Místo úprav $commonParams hashtable můžete explicitně definovat parametr Location , aby New-AzVm nahradil hodnotu Location klíče v $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
    }
}

Příklad 4: Použití více splattovaných objektů v jednom příkazu

V jednom příkazu můžete použít více splattovaných objektů. V tomto příkladu jsou různé parametry definovány v samostatných hashtables. Hashtables se splattují v jednom Write-Host příkazu.

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

Parametry příkazu Splatting

K reprezentaci parametrů příkazu můžete použít splatting. Tato technika je užitečná při vytváření funkce proxy, tj. funkce, která volá jiný příkaz. Tato funkce je představena ve Windows PowerShellu 3.0.

Pokud chcete parametry příkazu osplatit, použijte @Args k reprezentaci parametrů příkazu. Tato technika je jednodušší než výčet parametrů příkazu a funguje bez revize, i když se parametry volaného příkazu změní.

Funkce používá automatickou $Args proměnnou, která obsahuje všechny nepřiřazené hodnoty parametrů.

Například následující funkce volá rutinu Get-Process . V této funkci @Args představuje všechny parametry rutiny Get-Process .

function Get-MyProcess { Get-Process @Args }

Při použití Get-MyProcess funkce se předají @Argsvšechny nepřiřazené parametry a hodnoty parametrů, jak je znázorněno v následujících příkazech.

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

Můžete použít @Args ve funkci, která má explicitně deklarované parametry. Můžete ho použít více než jednou ve funkci, ale všechny parametry, které zadáte, se předají do všech instancí @Args, jak je znázorněno v následujícím příkladu.

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)

Notes

Pokud funkci převedete na pokročilou funkci pomocí atributů CmdletBinding nebo Parameter , $args automatická proměnná už nebude ve funkci dostupná. Pokročilé funkce vyžadují explicitní definici parametru.

Konfigurace požadovaného stavu PowerShellu (DSC) nebyla navržena tak, aby používala splatting. K předání hodnot do prostředku DSC nelze použít splatting. Další informace naleznete v článku Gael Colas Pseudo-Splatting DSC Resources.