Delen via

about_Splatting

Korte beschrijving

Hierin wordt beschreven hoe u splatting gebruikt om parameters door te geven aan opdrachten in PowerShell.

Lange beschrijving

Splatting is een methode voor het overdragen van een verzameling parameterwaarden aan een opdracht in één geheel. PowerShell koppelt elke waarde in de verzameling aan een opdrachtparameter. Geplatte parameterwaarden worden opgeslagen in benoemde splatting-variabelen, die eruitzien als standaardvariabelen, maar beginnen met een At-symbool (@) in plaats van een dollarteken ($). Het at-symbool vertelt PowerShell dat u een verzameling waarden doorgeeft in plaats van één waarde.

Splatting maakt dat uw opdrachten korter en gemakkelijker te lezen zijn. U kunt de splattingwaarden in verschillende opdrachtoproepen opnieuw gebruiken en splatting gebruiken om parameterwaarden van de $PSBoundParameters automatische variabele door te geven aan andere scripts en functies.

Vanaf Windows PowerShell 3.0 kunt u ook splatting gebruiken om alle parameters van een opdracht weer te geven.

Syntaxis

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

Als u parameterwaarden wilt opgeven voor positionele parameters, waarbij parameternamen niet vereist zijn, gebruikt u de syntaxis van de matrix. Als u parameternaam en waardeparen wilt opgeven, gebruikt u de syntaxis van de hashtabel. De geplatte waarde kan overal in de lijst met parameters worden weergegeven.

Bij splatting hoeft u geen hash-tabel of matrix te gebruiken om alle parameters door te geven. U kunt bepaalde parameters doorgeven met behulp van splatting en andere via positie of via parameternaam doorgeven. U kunt ook meerdere objecten in één opdracht splatten, zodat u niet meer dan één waarde doorgeeft voor elke parameter.

Vanaf PowerShell 7.1 kunt u een geplatte parameter overschrijven door expliciet een parameter in een opdracht te definiëren.

Splatting met hash-tabellen

Gebruik een hash-tabel om parameternaam en waardeparen te splaten. U kunt deze indeling gebruiken voor alle parametertypen, inclusief positionele en switchparameters. Positionele parameters moeten op naam worden toegewezen.

In de volgende voorbeelden worden twee Copy-Item opdrachten vergeleken waarmee het Test.txt bestand wordt gekopieerd naar het Test2.txt-bestand in dezelfde map.

In het eerste voorbeeld wordt de traditionele indeling gebruikt waarin parameternamen worden opgenomen.

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

In het tweede voorbeeld wordt hashtabel-splatting gebruikt. Met de eerste opdracht maakt u een hash-tabel met parameternaam- en parameterwaardeparen en slaat u deze op in de $HashArguments variabele. De tweede opdracht maakt gebruik van de $HashArguments variabele in een opdracht met splatting. Het at-symbool (@HashArguments) vervangt het dollarteken ($HashArguments) in de opdracht.

Als u een waarde wilt opgeven voor de parameter WhatIf switch, gebruikt u $true of $false.

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

Notitie

In de eerste opdracht geeft het at-symbool (@) een hash-tabel aan, niet een geplatte waarde. De syntaxis voor hash-tabellen in PowerShell is: @{<name>=<value>; <name>=<value>; ...}

Afplatting met matrices

Gebruik een matrix om waarden te splaten voor positionele parameters, waarvoor geen parameternamen zijn vereist. De waarden moeten in de positienummervolgorde van de matrix staan.

In de volgende voorbeelden worden twee Copy-Item opdrachten vergeleken waarmee het Test.txt bestand wordt gekopieerd naar het Test2.txt-bestand in dezelfde map.

In het eerste voorbeeld wordt de traditionele indeling gebruikt waarin parameternamen worden weggelaten. De parameterwaarden worden weergegeven in de positievolgorde in de opdracht.

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

In het tweede voorbeeld wordt arraysplatting gebruikt. Met de eerste opdracht maakt u een matrix van de parameterwaarden en slaat u deze op in de $ArrayArguments variabele. De waarden bevinden zich in de positievolgorde van de matrix. De tweede opdracht maakt gebruik van de variabele $ArrayArguments in een opdracht in splatting. Het at-symbool (@ArrayArguments) vervangt het dollarteken ($ArrayArguments) in de opdracht.

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

De parameter ArgumentList gebruiken

Verschillende cmdlets hebben een ArgumentList-parameter die wordt gebruikt om parameterwaarden door te geven aan een scriptblok dat wordt uitgevoerd door de cmdlet. De parameter ArgumentList gebruikt een matrix met waarden die worden doorgegeven aan het scriptblok. PowerShell maakt effectief gebruik van matrixsplatting om de waarden te binden aan de parameters van het scriptblok. Wanneer u ArgumentListgebruikt, en u een array als één object, gebonden aan één parameter, moet doorgeven, moet u de array verpakken als het enige element van een andere array.

Het volgende voorbeeld bevat een scriptblok dat één parameter gebruikt die een matrix met tekenreeksen is.

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

In dit voorbeeld wordt alleen het eerste item $array doorgegeven aan het scriptblok.

Hello

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

In dit voorbeeld $array wordt deze verpakt in een matrix, zodat de hele matrix als één object wordt doorgegeven aan de scriptblock.

Hello World!

Voorbeelden

Voorbeeld 1: Geplatte parameters opnieuw gebruiken in verschillende opdrachten

In dit voorbeeld ziet u hoe u geplatte waarden opnieuw kunt gebruiken in verschillende opdrachten. De opdrachten in dit voorbeeld gebruiken de Write-Host cmdlet om berichten naar de hostprogrammaconsole te schrijven. Het maakt gebruik van splatting om de voorgrond- en achtergrondkleuren op te geven.

Als u de kleuren van alle opdrachten wilt wijzigen, wijzigt u de waarde van de $Colors variabele.

Met de eerste opdracht maakt u een hash-tabel met parameternamen en -waarden en slaat u de hash-tabel op in de $Colors variabele.

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

De tweede en derde opdracht gebruiken de $Colors variabele voor splatting in een Write-Host opdracht. Als u de $Colors variablewilt gebruiken, vervangt u het dollarteken ($Colors) door een At-symbool (@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."

Voorbeeld 2: Parameters doorsturen met behulp van $PSBoundParameters

In dit voorbeeld ziet u hoe u de parameters doorstuurt naar andere opdrachten met behulp van splatting en de $PSBoundParameters automatische variabele.

De $PSBoundParameters automatische variabele is een woordenlijstobject (System.Collections.Generic.Dictionary) dat alle parameternamen en waarden bevat die worden gebruikt wanneer een script of functie wordt uitgevoerd.

In het volgende voorbeeld gebruiken we de variabele $PSBoundParameters om de parameterwaarden die zijn doorgegeven aan een script of functie van Test2 functie door te sturen naar de Test1-functie. Beide aanroepen naar de Test1-functie vanuit Test2 maken gebruik van 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

Voorbeeld 3: Geplatte parameters overschrijven met expliciet gedefinieerde parameters

In dit voorbeeld ziet u hoe u een geplatte parameter overschrijft met behulp van expliciet gedefinieerde parameters. Dit is handig als u geen nieuwe hashtabel wilt maken of een waarde wilt wijzigen in de hashtabel die u gebruikt om te splaten.

Met de variabele $commonParams worden de parameters opgeslagen om virtuele machines te maken op de East US locatie. De $allVms variabele is een lijst met virtuele machines die moeten worden gemaakt. We doorlopen de lijst en gebruiken $commonParams om de parameters te verspreiden voor het maken van elke virtuele machine. We willen echter dat myVM2 worden gemaakt in een andere regio dan de andere virtuele machines. In plaats van de $commonParams hashtabel aan te passen, kunt u de parameter Location in New-AzVm expliciet definiëren om de waarde van de Location-sleutel in $commonParamste vervangen.

$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
    }
}

Voorbeeld 4: Meerdere geplatte objecten gebruiken in één opdracht

U kunt meerdere geplatte objecten in één opdracht gebruiken. In dit voorbeeld worden verschillende parameters gedefinieerd in afzonderlijke hashtabellen. De hashtables worden in één Write-Host-opdracht verwerkt.

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

Parameters voor de Splatting-opdracht

U kunt splatting gebruiken om de parameters van een opdracht weer te geven. Deze techniek is handig wanneer u een proxyfunctie maakt, dat wil gezegd, een functie die een andere opdracht aanroept. Deze functie wordt geïntroduceerd in Windows PowerShell 3.0.

Als u de parameters van een opdracht wilt splaten, gebruikt u @args om de opdrachtparameters weer te geven. Deze techniek is eenvoudiger dan het inventariseren van opdrachtparameters en werkt zonder revisie, zelfs als de parameters van de aangeroepen opdracht wijzigen.

De functie maakt gebruik van de $args automatische variabele, die alle niet-toegewezen parameterwaarden bevat.

Met de volgende functie wordt bijvoorbeeld de Get-Process-cmdlet aangeroepen. In deze functie vertegenwoordigt @args alle parameters van de Get-Process cmdlet.

function Get-MyProcess { Get-Process @args }

Wanneer u de functie Get-MyProcess gebruikt, worden alle niet-toegewezen parameters en parameterwaarden doorgegeven aan @args, zoals wordt weergegeven in de volgende opdrachten.

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

U kunt @args gebruiken in een functie die expliciet parameters heeft gedeclareerd. U kunt deze meer dan één keer in een functie gebruiken, maar alle parameters die u invoert, worden doorgegeven aan alle exemplaren van @args, zoals wordt weergegeven in het volgende voorbeeld.

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)

Opmerkingen

Als u een functie in een geavanceerde functie maakt met behulp van de CmdletBinding of Parameter kenmerken, is de $args automatische variabele niet meer beschikbaar in de functie. Voor geavanceerde functies is expliciete parameterdefinitie vereist.

PowerShell Desired State Configuration (DSC) is niet ontworpen voor het gebruik van splatting. U kunt splatting niet gebruiken om waarden door te geven aan een DSC-resource. Zie het artikel van Gael Colas Pseudo-Splatting DSC Resourcesvoor meer informatie.

Zie ook

  • Last updated on