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 doorgeven van een verzameling parameterwaarden aan een opdracht als een eenheid. 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 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.
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 anderen doorgeven op positie of op parameternaam. 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 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 hashtabel 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 matrixplatting 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 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 en u een matrix als één object wilt doorgeven dat is gebonden aan één parameter, moet u de matrix verpakken als het enige element van een andere matrix.
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 het scriptblok.
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 console van het hostprogramma 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 gewoon de waarde van de $Colors variabele.
Met de eerste opdracht maakt u een hashtabel met parameternamen en -waarden en slaat u de hash-tabel op in de $Colors variabele.
$Colors = @{ForegroundColor = "black"; BackgroundColor = "white"}
De tweede en derde opdrachten 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 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 $PSBoundParameters variabele om de parameterwaarden door te sturen die zijn doorgegeven aan een script of functie 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 = $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.
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 locatieparameter 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 geplatt.
$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 @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 opdracht wijzigen.
De functie maakt gebruik van de $Args automatische variabele, die alle niet-toegewezen parameterwaarden bevat.
Met de volgende functie wordt bijvoorbeeld de cmdlet aangeroepen Get-Process . 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 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® Windows® 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 parameterkenmerken , 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 Pseudo-Splatting DSC Resources van Gael Colas voor meer informatie.
