about_Splatting
Korte beschrijving
Beschrijft hoe u splatting gebruikt om parameters door te geven aan opdrachten in PowerShell.
Lange beschrijving
Splatting is een methode voor het doorgeven van een verzameling parameterwaarden aan een opdracht als een eenheid. PowerShell koppelt elke waarde in de verzameling aan een opdrachtparameter. Splatted 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 uw opdrachten korter en gemakkelijker te lezen. 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.
Syntax
<CommandName> <optional parameters> @<HashTable> <optional parameters>
<CommandName> <optional parameters> @<Array> <optional parameters>
Als u parameterwaarden wilt opgeven voor positionele parameters, waarin parameternamen niet vereist zijn, gebruikt u de matrixsyntaxis. 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.
Wanneer u splatting uitvoert, hoeft u geen hash-tabel of een matrix te gebruiken om alle parameters door te geven. U kunt bepaalde parameters doorgeven met behulp van splatting en andere doorgeven op positie of op parameternaam. U kunt ook meerdere objecten in één opdracht splaten, 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 gebruikt 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 whatIf-switchparameter , gebruikt $True u 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>; ...}
Splatting met matrices
Gebruik een matrix om waarden te splaten voor positionele parameters, waarvoor geen parameternamen zijn vereist. De waarden moeten in de positie-getalvolgorde in 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 positievolgorde in de opdracht.
Copy-Item "test.txt" "test2.txt" -WhatIf
In het tweede voorbeeld wordt matrixsplatting gebruikt. Met de eerste opdracht wordt een matrix van de parameterwaarden gemaakt en opgeslagen in de $ArrayArguments variabele. De waarden bevinden zich in de positievolgorde van de matrix. De tweede opdracht gebruikt de $ArrayArguments variabele 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. Als u ArgumentList gebruikt als u een matrix als één object wilt doorgeven dat aan één parameter is gebonden, moet u de matrix verpakken als het enige element van een andere matrix.
Het volgende voorbeeld heeft 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 in een matrix verpakt, zodat de hele matrix als één object wordt doorgegeven aan het scriptblok.
Hello World!
Voorbeelden
Voorbeeld 1: Geplatte parameters opnieuw gebruiken in verschillende opdrachten
In dit voorbeeld ziet u hoe u geplatte waarden opnieuw gebruikt in verschillende opdrachten. De opdrachten in dit voorbeeld gebruiken de Write-Host cmdlet om berichten naar de console van het hostprogramma te schrijven. Er wordt splatting gebruikt 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 het $Colors variabledollarteken () wilt 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 hun parameters doorstuurt naar andere opdrachten met behulp van splatting en de $PSBoundParameters automatische variabele.
De $PSBoundParameters automatische variabele is een woordenboekobject (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 $PSBoundParameters variabele om de parameters die zijn doorgegeven aan een script of functie door te sturen van Test2 functie naar de Test1 functie. Beide aanroepen naar de Test1 functie van het gebruik van Test2 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
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.
De $commonParams variabele slaat de parameters op om virtuele machines op de East US locatie te maken. De $allVms variabele is een lijst met virtuele machines die moeten worden gemaakt. We doorlopen de lijst en gebruiken $commonParams om de parameters te splaten om elke virtuele machine te maken. We willen myVM2 echter worden gemaakt in een andere regio dan de andere virtuele machines. In plaats van de $commonParams hashtabel aan te passen, kunt u de parameterNew-AzVm Location 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
}
}
Parameters voor splatting-opdrachten
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 @Args u deze 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 opdrachtwijziging.
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 @Args vertegenwoordigt u alle parameters van de Get-Process cmdlet.
function Get-MyProcess { Get-Process @Args }
Wanneer u de Get-MyProcess functie 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 deze gebruiken @Args in een functie die expliciet parameters heeft gedeclareerd. U kunt deze meer dan één keer gebruiken in een functie, 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
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)
Notities
Als u een functie in een geavanceerde functie maakt met behulp van de cmdletBinding - of parameterkenmerken , is de $args automatische variabele niet meer beschikbaar in de functie. Voor geavanceerde functies is een expliciete parameterdefinitie vereist.
PowerShell Desired State Configuration (DSC) is niet ontworpen om splatting te gebruiken. U kunt splatting niet gebruiken om waarden door te geven aan een DSC-resource. Zie het artikel Pseudo-Splatting DSC Resources van Gael Colas voor meer informatie.