about_Splatting

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. Hodnoty splattovaného parametru jsou uloženy v pojmenovaných proměnných splattingu, 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 zkrátí a usnadní čtení příkazů. Hodnoty splattingu můžete znovu 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 PowerShell 3.0 můžete také použít k reprezentaci všech parametrů příkazu.

Syntax

<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 parametru a hodnoty, použijte syntaxi tabulky hash. Splattovaná hodnota se může zobrazit kdekoli v seznamu parametrů.

Při splattingu 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é umístěním nebo názvem 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řepsatplatný parametr explicitním definováním parametru v příkazu.

Splatting s tabulkami hash

Pomocí hashovací tabulky můžete splatovat páry názvu parametru a hodnoty. 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á dělení tabulky hash. První příkaz vytvoří tabulku hash párů parameter-name a parameter-value a uloží ji do $HashArguments proměnné. Druhý příkaz používá proměnnou $HashArguments v příkazu splattingem. 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

Pomocí pole můžete použít hodnoty pro poziční parametry, které nevyžadují názvy parametrů. Hodnoty musí být v matici 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í umístění.

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í umístění. 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ý se používá k předání hodnot parametrů do bloku skriptu, který rutina spouští. Parametr ArgumentList přebírá pole hodnot, které jsou předány do bloku skriptu. PowerShell efektivně používá k vytvoření vazby hodnot na parametry bloku skriptu použití maticového dělení. Pokud použijete ArgumentList, potřebujete-li předat pole jako jeden objekt vázaný na jeden parametr, 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ých příkazech. Příkazy v tomto příkladu používají rutinu k zápisu Write-Host zpráv do konzoly hostitelského programu. Slouží k určení barev popředí a pozadí.

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í proměnnou $ColorsWrite-Host pro dělení v příkazu. Chcete-li použít $Colors variableznak dolaru ($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 parametrů a hodnoty, které se používají při spuštění skriptu nebo funkce.

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

function Test1
{
    param($a, $b, $c)

    $a
    $b
    $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
    $LimitedParameters = $PSBoundParameters
    $LimitedParameters.Remove("a") | Out-Null
    Test1 @LimitedParameters
}
Test2 -a 1 -b 2 -c 3
1
2
3
2
3

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

Tento příklad ukazuje, jak přepsat splattovaný parametr pomocí explicitně definovaných parametrů. To je užitečné, když nechcete vytvořit novou hashovací tabulku nebo změnit hodnotu v hashovací tabulce, kterou používáte k nasplatová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ž v jiných virtuálních počítačích. Místo úprav $commonParams hashtable můžete explicitně definovat parametr Location , který New-AzVm nahradí 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
    }
}

Parametry příkazu Splatting

Pomocí splattingu můžete znázorňovat parametry příkazu. Tato technika je užitečná při vytváření funkce proxy, tj. funkce, která volá jiný příkaz. Tato funkce je zavedena v Windows PowerShell 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 proměnnou $Args , 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. Ve funkci ji můžete použít více než jednou, ale všechny zadané parametry se předávají všem instancím @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
Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)     Id ProcessName
-------  ------    -----      ----- -----   ------     -- -----------
408      28    75568      83176   620     1.33   1692 powershell

Path               : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e
Extension          : .exe
Definition         : C:\Windows\System32\WindowsPowerShell\v1.0\powershell.e
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.14393.0 (rs1_release.160715-1616
                     FileDescription:  Windows PowerShell
                     Product:          Microsoft Windows Operating System
                     ProductVersion:   10.0.14393.0
                     Debug:            False
                     Patched:          False
                     PreRelease:       False
                     PrivateBuild:     False
                     SpecialBuild:     False
                     Language:         English (United States)

Poznámky

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

PowerShell Desired State Configuration (DSC) nebyl navržen tak, aby používal 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.

Viz také