Sdílet prostřednictvím

informace_o_Splatting

Krátký popis

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

Dlouhý popis

Splatting je metoda, která umožňuje předat kolekci hodnot parametrů jako celek příkazu. PowerShell přidruží každou hodnotu v kolekci k parametru příkazu. Hodnoty splatted parametru jsou uloženy v pojmenovaných proměnných splatting, 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 příkazy a usnadňuje jejich čtení. 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é jiným skriptům a funkcím.

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. Rozbalená hodnota se může objevit kdekoli v seznamu parametrů.

Při použití operátoru splatting 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é zadat více objektů najednou, abyste pro každý parametr předali maximálně jednu hodnotu.

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

Předávání parametrů pomocí hash tabulek

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 příkazy Copy-Item, 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á rozprostření hodnot v tabulce hash. První příkaz vytvoří tabulku hash párů parameter-name a parameter-value a uloží ji do proměnné $HashArguments. Druhý příkaz používá proměnnou $HashArguments v příkazu se splattingem. Symbol At (@HashArguments) nahradí znak dolaru ($HashArguments) v příkazu.

Pokud chcete zadat hodnotu parametru přepínače WhatIf, použijte $True nebo $False.

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

Poznámka:

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

Rozkládání pomocí polí

Použijte pole k rozbalení hodnot pro poziční parametry, které nevyžadují názvy parametrů. Hodnoty musí být v poli v pořadí čísel pozice.

Následující příklady porovnávají dva příkazy Copy-Item, 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á operaci rozložení pole. První příkaz vytvoří pole hodnot parametrů a uloží ho do proměnné $ArrayArguments. Hodnoty jsou v poli seřazeny podle pozice. Druhý příkaz používá proměnnou $ArrayArguments 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ý rutina spouští. Parametr ArgumentList přebírá pole hodnot předaných bloku skriptu. PowerShell efektivně používá splatting pole pro navázání hodnot na parametry bloku skriptu. Při použití ArgumentList, pokud potřebujete předat pole jako jeden objekt vázaný na jeden parametr, musíte pole vložit 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 v $array.

Hello

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

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

Hello World!

Příklady

Příklad 1: Opětovné použití rozbalených parametrů v různých příkazech

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

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

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

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

Druhý a třetí příkaz používají proměnnou $Colors pro splatting v příkazu Write-Host. Chcete-li použít $Colors variable, nahraďte znak 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 a $PSBoundParameters automatické proměnné.

$PSBoundParameters automatická 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ání hodnot parametrů skriptu nebo funkci z Test2 funkce do Test1 funkce. Obě volání funkce Test1 z Test2 používají splatting.

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í rozbalených parametrů explicitně definovanými parametry

Tento příklad ukazuje, jak přepsat „splatted“ parametr pomocí explicitně zadaných parametrů. To je užitečné v případě, že nechcete vytvořit hashovací tabulku novou nebo změnit hodnotu v hashovací 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 ke rozložení parametrů pro vytvoření jednotlivých virtuálních počítačů. Chceme ale myVM2 vytvořit v jiné oblasti než ostatní virtuální počítače. Místo úpravy $commonParams hashtable můžete explicitně definovat parametr Location v New-AzVm a nahradit hodnotu klíče Location 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 příkazu Write-Host.

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

Parametry příkazu Splatting

Pro 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 rozložit, 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í.

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

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

function Get-MyProcess { Get-Process @Args }

Když použijete funkci Get-MyProcess, všechny nepřiřazené parametry a hodnoty parametrů se předají @Args, 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\...

V funkci, která má explicitně deklarované parametry, můžete použít @Args. Můžete ho použít více než jednou ve funkci, ale všechny parametry, které zadáte, se předají 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

 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)

Poznámky

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.

Viz také

  • Last updated on