Sdílet prostřednictvím

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. 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 PowerShell 3.0 můžete použít také 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 a [switch] parametrů. 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 skriptublock, který je spuštěn rutinou. Parametr ArgumentList přebírá pole hodnot, které jsou předány skriptublock. PowerShell efektivně používá maticové splatting k vytvoření vazby hodnot na parametry skriptublock. 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 skriptblock, 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 skriptublock jako jeden objekt.

Hello World!

Examples

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 v 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)

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.

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é

  • Last updated on