about_Splatting

  • Artikel

Kort beskrivning

Beskriver hur du använder splatting för att skicka parametrar till kommandon i PowerShell.

Lång beskrivning

Splatting är en metod för att skicka en samling parametervärden till ett kommando som en enhet. PowerShell associerar varje värde i samlingen med en kommandoparameter. Splattade parametervärden lagras i namngivna splattingvariabler, som ser ut som standardvariabler, men börjar med en At-symbol (@) i stället för ett dollartecken ($). Symbolen At anger för PowerShell att du skickar en samling värden i stället för ett enda värde.

Splatting gör dina kommandon kortare och enklare att läsa. Du kan återanvända splatting-värdena i olika kommandoanrop och använda splatting för att skicka parametervärden från den $PSBoundParameters automatiska variabeln till andra skript och funktioner.

Från och med Windows PowerShell 3.0 kan du också använda splatting för att representera alla parametrar i ett kommando.

Syntax

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

Om du vill ange parametervärden för positionsparametrar, där parameternamn inte krävs, använder du matrissyntaxen. Om du vill ange parameternamn och värdepar använder du hashtabellsyntaxen. Det splattade värdet kan visas var som helst i parameterlistan.

När du stänker behöver du inte använda en hash-tabell eller en matris för att skicka alla parametrar. Du kan skicka vissa parametrar med hjälp av splatting och skicka andra efter position eller efter parameternamn. Du kan också splat flera objekt i ett enda kommando så att du inte skickar mer än ett värde för varje parameter.

Från och med PowerShell 7.1 kan du åsidosätta en splattad parameter genom att uttryckligen definiera en parameter i ett kommando.

Splatting med hash-tabeller

Använd en hash-tabell för att splat-parameternamn och värdepar. Du kan använda det här formatet för alla parametertyper, inklusive positions- och växelparametrar. Positionsparametrar måste tilldelas efter namn.

I följande exempel jämförs två Copy-Item kommandon som kopierar Test.txt-filen till den Test2.txt filen i samma katalog.

I det första exemplet används det traditionella format där parameternamn ingår.

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

I det andra exemplet används hashtabellsplattning. Det första kommandot skapar en hash-tabell med parameter-name och parameter-value-par och lagrar den i variabeln $HashArguments . Det andra kommandot använder variabeln $HashArguments i ett kommando med splatting. Symbolen At (@HashArguments) ersätter dollartecknet ($HashArguments) i kommandot .

Om du vill ange ett värde för parametern WhatIf-växel använder du $True eller $False.

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

Kommentar

I det första kommandot anger symbolen At (@) en hash-tabell, inte ett splattat värde. Syntaxen för hash-tabeller i PowerShell är: @{<name>=<value>; <name>=<value>; ...}

Splatting med matriser

Använd en matris för att splat-värden för positionsparametrar, som inte kräver parameternamn. Värdena måste vara i position-nummerordning i matrisen.

I följande exempel jämförs två Copy-Item kommandon som kopierar Test.txt-filen till den Test2.txt filen i samma katalog.

I det första exemplet används det traditionella format där parameternamn utelämnas. Parametervärdena visas i position i kommandot .

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

I det andra exemplet används matrissplattning. Det första kommandot skapar en matris med parametervärdena och lagrar den i variabeln $ArrayArguments . Värdena är i position i matrisen. Det andra kommandot använder variabeln $ArrayArguments i ett kommando i splatting. Symbolen At (@ArrayArguments) ersätter dollartecknet ($ArrayArguments) i kommandot .

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

Använda parametern ArgumentList

Flera cmdletar har en ArgumentList-parameter som används för att skicka parametervärden till ett skriptblock som körs av cmdleten. Parametern ArgumentList tar en matris med värden som skickas till skriptblocket. PowerShell använder effektivt matrissplattning för att binda värdena till parametrarna i skriptblocket. Om du använder ArgumentList, om du behöver skicka en matris som ett enskilt objekt som är bundet till en enskild parameter, måste du omsluta matrisen som det enda elementet i en annan matris.

I följande exempel finns ett skriptblock som tar en enda parameter som är en matris med strängar.

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

I det här exemplet skickas endast det första objektet i $array till skriptblocket.

Hello

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

I det här exemplet $array omsluts den i en matris så att hela matrisen skickas till skriptblocket som ett enda objekt.

Hello World!

Exempel

Exempel 1: Återanvända splattade parametrar i olika kommandon

Det här exemplet visar hur du återanvänder splattade värden i olika kommandon. Kommandona i det här exemplet använder cmdleten Write-Host för att skriva meddelanden till värdprogramkonsolen. Den använder splatting för att ange förgrunds- och bakgrundsfärgerna.

Om du vill ändra färgerna på alla kommandon ändrar du bara värdet för variabeln $Colors .

Det första kommandot skapar en hash-tabell med parameternamn och värden och lagrar hash-tabellen i variabeln $Colors .

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

De andra och tredje kommandona använder variabeln $Colors för att stänka i ett Write-Host kommando. Om du vill använda $Colors variableersätter du dollartecknet ($Colors) med symbolen 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."

Exempel 2: Vidarebefordra parametrar med hjälp av $PSBoundParameters

Det här exemplet visar hur du vidarebefordrar parametrarna till andra kommandon med hjälp av splatting och den $PSBoundParameters automatiska variabeln.

Den $PSBoundParameters automatiska variabeln är ett ordlisteobjekt (System.Collections.Generic.Dictionary) som innehåller alla parameternamn och värden som används när ett skript eller en funktion körs.

I följande exempel använder vi variabeln $PSBoundParameters för att vidarebefordra de parametrar som skickas till ett skript eller en funktion från Test2 funktion till Test1 funktionen. Båda anropen Test1 till funktionen från Test2 använd 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

Exempel 3: Åsidosätt splattade parametrar med explicit definierade parametrar

Det här exemplet visar hur du åsidosätter en splatted-parameter med explicit definierade parametrar. Detta är användbart när du inte vill skapa en ny hashtable eller ändra ett värde i den hashtable som du använder för att splat.

Variabeln $commonParams lagrar parametrarna för att skapa virtuella datorer på platsen East US . Variabeln $allVms är en lista över virtuella datorer som ska skapas. Vi loopar igenom listan och använder $commonParams för att splat parametrarna för att skapa varje virtuell dator. Vi vill myVM2 dock skapas i en annan region än de andra virtuella datorerna. I stället för att justera hashtabellen $commonParams kan du uttryckligen definiera parametern Plats i New-AzVm för att ersätta värdet för Location nyckeln i $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
    }
}

Exempel 4: Använda flera splattade objekt i ett enda kommando

Du kan använda flera splattade objekt i ett enda kommando. I det här exemplet definieras olika parametrar i separata hashtables. Hashtables är splatted i ett enda Write-Host kommando.

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

Splatting-kommandoparametrar

Du kan använda splatting för att representera parametrarna för ett kommando. Den här tekniken är användbar när du skapar en proxyfunktion, dvs. en funktion som anropar ett annat kommando. Den här funktionen introduceras i Windows PowerShell 3.0.

Om du vill splata parametrarna för ett kommando använder du @Args för att representera kommandoparametrarna. Den här tekniken är enklare än att räkna upp kommandoparametrar och den fungerar utan revision även om parametrarna för den anropade kommandoändringen.

Funktionen använder den $Args automatiska variabeln, som innehåller alla otilldelade parametervärden.

Följande funktion anropar till exempel cmdleten Get-Process . I den här funktionen @Args representerar alla parametrar för cmdleten Get-Process .

function Get-MyProcess { Get-Process @Args }

När du använder Get-MyProcess funktionen skickas alla otilldelade parametrar och parametervärden till @Args, enligt följande kommandon.

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

Du kan använda @Args i en funktion som uttryckligen har deklarerat parametrar. Du kan använda den mer än en gång i en funktion, men alla parametrar som du anger skickas till alla instanser av @Args, som du ser i följande exempel.

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)

Kommentar

Om du gör en funktion till en avancerad funktion med hjälp av attributen CmdletBinding eller Parameter är den $args automatiska variabeln inte längre tillgänglig i funktionen. Avancerade funktioner kräver explicit parameterdefinition.

PowerShell Desired State Configuration (DSC) har inte utformats för att använda splatting. Du kan inte använda splatting för att skicka värden till en DSC-resurs. Mer information finns i Gael Colas artikel Pseudo-Splatting DSC Resources.

Se även