Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Kurzbeschreibung
Beschreibt, wie man Splatting verwendet, um Parameter an Befehle in PowerShell zu übergeben.
Lange Beschreibung
Splatting ist eine Methode zum Übergeben einer Auflistung von Parameterwerten an einen Befehl als Einheit. PowerShell ordnet jeden Wert in der Auflistung einem Befehlsparameter zu. Splatted-Parameterwerte werden in benannten Splatting-Variablen gespeichert, die wie Standardvariablen aussehen, beginnen jedoch mit einem At-Symbol (@) anstatt eines Dollarzeichens ($). Das At-Symbol teilt PowerShell mit, dass Sie eine Auflistung von Werten anstelle eines einzelnen Werts übergeben.
Splatting verkürzt und vereinfacht Ihre Befehle, so dass sie leichter lesbar sind. Sie können die Splatting-Werte in verschiedenen Befehlsaufrufen wiederverwenden und Splatting nutzen, um Parameterwerte aus der automatischen Variablen $PSBoundParameters an andere Skripte und Funktionen zu übergeben.
Seit Windows PowerShell 3.0 können Sie auch *Splatting* verwenden, um alle Parameter eines Befehls darzustellen.
Syntax
<CommandName> <optional parameters> @<HashTable> <optional parameters>
<CommandName> <optional parameters> @<Array> <optional parameters>
Verwenden Sie die Arraysyntax, um Parameterwerte für Positionsparameter bereitzustellen, bei denen Parameternamen nicht erforderlich sind. Verwenden Sie die Hashtabellensyntax, um Parameternamen und Wertpaare bereitzustellen. Der gesplattete Wert kann an jeder beliebigen Stelle in der Parameterliste erscheinen.
Beim Splatieren müssen Sie keine Hashtabelle oder ein Array verwenden, um alle Parameter zu übergeben. Sie können einige Parameter mithilfe von 'Splatting' übergeben, andere über Position oder Parameternamen. Außerdem können Sie mehrere Objekte in einem einzigen Befehl splatieren, sodass Sie nicht mehr als einen Wert für jeden Parameter übergeben.
Seit PowerShell 7.1 können Sie einen gesplatteten Parameter überschreiben, indem Sie einen Parameter innerhalb eines Befehls explizit definieren.
Splatting mit Hashtabellen
Verwenden Sie eine Hashtabelle, um Parameternamen und Wertpaare zu splatieren. Sie können dieses Format für alle Parametertypen verwenden, einschließlich Positions- und Schalterparametern. Positionsparameter müssen anhand des Namens zugewiesen werden.
In den folgenden Beispielen werden zwei Copy-Item Befehle verglichen, die die Test.txt Datei in die Test2.txt Datei im selben Verzeichnis kopieren.
Im ersten Beispiel wird das herkömmliche Format verwendet, in dem Parameternamen enthalten sind.
Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf
Im zweiten Beispiel wird das Hashtabellen-Splatting verwendet. Der erste Befehl erstellt eine Hashtabelle mit Parameternamen- und Parameterwertpaaren und speichert sie in der $HashArguments Variablen. Der zweite Befehl verwendet die $HashArguments-Variable in einem Befehl mit *Splatting*. Das At-Symbol (@HashArguments) ersetzt das Dollarzeichen ($HashArguments) im Befehl.
Verwenden Sie oder $True, um einen Wert für den $False Switch-Parameter bereitzustellen.
$HashArguments = @{
Path = "test.txt"
Destination = "test2.txt"
WhatIf = $true
}
Copy-Item @HashArguments
Hinweis
Im ersten Befehl gibt das At-Symbol (@) eine Hashtabelle an, nicht einen Splatted-Wert. Die Syntax für Hashtabellen in PowerShell lautet: @{<name>=<value>; <name>=<value>; ...}
Splatting mit Arrays
Verwenden Sie ein Array, um Werte für Positionsparameter zu splatieren, die keine Parameternamen erfordern. Die Werte müssen in der Reihenfolge der Positionsnummern im Array angeordnet sein.
In den folgenden Beispielen werden zwei Copy-Item Befehle verglichen, die die Test.txt Datei in die Test2.txt Datei im selben Verzeichnis kopieren.
Im ersten Beispiel wird das herkömmliche Format verwendet, in dem Parameternamen weggelassen werden. Die Parameterwerte erscheinen in der Reihenfolge ihrer Position im Befehl.
Copy-Item "test.txt" "test2.txt" -WhatIf
Im zweiten Beispiel wird Array-Splatting verwendet. Der erste Befehl erstellt ein Array der Parameterwerte und speichert es in der $ArrayArguments Variablen. Die Werte sind in der Reihenfolge ihrer Positionen im Array angeordnet. Der zweite Befehl verwendet die $ArrayArguments-Variable in einem Befehl in *Splatting*. Das At-Symbol (@ArrayArguments) ersetzt das Dollarzeichen ($ArrayArguments) im Befehl.
$ArrayArguments = "test.txt", "test2.txt"
Copy-Item @ArrayArguments -WhatIf
Verwenden des ArgumentList-Parameters
Mehrere Cmdlets verfügen über einen ArgumentList- Parameter, der verwendet wird, um Parameterwerte an einen Skriptblock zu übergeben, der vom Cmdlet ausgeführt wird. Der ArgumentList Parameter verwendet ein Array von Werten, die an den Skriptblock übergeben werden. PowerShell verwendet effektiv das Array Splatting, um die Werte an die Parameter des Skriptblocks zu binden. Wenn Sie ArgumentList-verwenden und ein Array als einzelnes Objekt übergeben müssen, das an einen einzelnen Parameter gebunden ist, müssen Sie das Array als einziges Element eines anderen Arrays umschließen.
Im folgenden Beispiel ist ein Skriptblock vorhanden, der einen einzelnen Parameter verwendet, bei dem es sich um ein Array von Zeichenfolgen handelt.
$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
param([string[]]$words) $words -join ' '
} -ArgumentList $array
In diesem Beispiel wird nur das erste Element in $array an den Skriptblock übergeben.
Hello
$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
param([string[]]$words) $words -join ' '
} -ArgumentList (,$array)
In diesem Beispiel wird $array in ein Array eingeschlossen, sodass das gesamte Array als einzelnes Objekt an den Skriptblock übergeben wird.
Hello World!
Beispiele
Beispiel 1: Wiederverwenden von Splatted-Parametern in verschiedenen Befehlen
In diesem Beispiel wird gezeigt, wie aufgesplittete Werte in verschiedenen Befehlen wiederverwendet werden. Die Befehle in diesem Beispiel verwenden das Cmdlet Write-Host, um Nachrichten in die Hostprogrammkonsole zu schreiben. Es verwendet Splatting, um die Vordergrund- und Hintergrundfarben festzulegen.
Wenn Sie die Farben aller Befehle ändern möchten, ändern Sie einfach den Wert der variablen $Colors.
Der erste Befehl erstellt eine Hashtabelle mit Parameternamen und Werten und speichert die Hashtabelle in der $Colors Variablen.
$Colors = @{ForegroundColor = "black"; BackgroundColor = "white"}
Die zweiten und dritten Befehle verwenden die $Colors-Variable zum Splatting in einem Write-Host-Befehl. Um die $Colors variablezu verwenden, ersetzen Sie das Dollarzeichen ($Colors) durch ein At-Symbol (@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."
Beispiel 2: Weiterleiten von Parametern mithilfe von $PSBoundParameters
In diesem Beispiel wird gezeigt, wie ihre Parameter mithilfe von Splatting und der $PSBoundParameters Variablen automatic an andere Befehle weitergeleitet werden.
Die $PSBoundParameters automatische Variable ist ein Wörterbuchobjekt (System.Collections.Generic.Dictionary), das alle Parameternamen und Werte enthält, die beim Ausführen eines Skripts oder einer Funktion verwendet werden.
Im folgenden Beispiel verwenden wir die $PSBoundParameters Variable, um die Parameterwerte, die an ein Skript oder eine Funktion übergeben werden, von Test2 Funktion an die Test1-Funktion weiterzuleiten. Beide Aufrufe der Test1-Funktion von Test2 verwenden Splatting-Technik.
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
Beispiel 3: Überschreiben von Splatted-Parametern mit explizit definierten Parametern
In diesem Beispiel wird gezeigt, wie sie einen Splatted-Parameter mithilfe explizit definierter Parameter außer Kraft setzen. Dies ist nützlich, wenn Sie keine neue Hashtabelle erstellen oder einen Wert in der Hashtabelle ändern möchten, die Sie zum Splat verwenden.
Die Variable $commonParams speichert die Parameter zum Erstellen virtueller Maschinen am Standort East US. Die $allVms Variable ist eine Liste der zu erstellenden virtuellen Computer. Wir durchlaufen die Liste und verwenden $commonParams, um die Parameter zum Erstellen dem einzelnen virtuellen Computer zu splatten. Wir möchten jedoch, dass myVM2 in einer anderen Region als die anderen virtuellen Computer erstellt werden. Anstatt die $commonParams Hashtabelle anzupassen, können Sie den parameter Location in New-AzVm explizit definieren, um den Wert des Location Schlüssels in $commonParamszu ersetzen.
$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
}
}
Parameter für das Splatting von Befehlen
Sie können Splatting verwenden, um die Parameter eines Befehls darzustellen. Diese Technik ist nützlich, wenn Sie eine Proxyfunktion erstellen, d. h. eine Funktion, die einen anderen Befehl aufruft. Dieses Feature wird in Windows PowerShell 3.0 eingeführt.
Um die Parameter eines Befehls aufzuschlüsseln, verwenden Sie @Args, um die Befehlsparameter darzustellen. Diese Technik ist einfacher als das Aufzählen von Befehlsparametern und funktioniert ohne Überarbeitung, auch wenn sich die Parameter der aufgerufenen Befehlsänderung ändern.
Das Feature verwendet die $Args automatische Variable, die alle Werte nicht zugewiesener Parameter enthält.
Die folgende Funktion ruft z. B. das Cmdlet Get-Process auf. In dieser Funktion stellt @Args alle Parameter des cmdlets Get-Process dar.
function Get-MyProcess { Get-Process @Args }
Wenn Sie die Get-MyProcess-Funktion verwenden, werden alle nicht zugewiesenen Parameter und Parameterwerte an @Argsübergeben, wie in den folgenden Befehlen dargestellt.
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\...
Sie können @Args in einer Funktion verwenden, die explizit deklarierte Parameter enthält. Sie können sie mehr als einmal in einer Funktion verwenden, aber alle von Ihnen eingegebenen Parameter werden an alle Instanzen von @Argsübergeben, wie im folgenden Beispiel gezeigt.
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)
Hinweise
Wenn Sie eine Funktion in eine erweiterte Funktion umwandeln, indem Sie entweder die CmdletBinding- oder Parameter- Attribute verwenden, ist die $args automatische Variable in der Funktion nicht mehr verfügbar. Erweiterte Funktionen erfordern eine explizite Parameterdefinition.
PowerShell Desired State Configuration (DSC) wurde nicht für die Verwendung von Splatting entwickelt. Sie können das Splatting nicht verwenden, um Werte an eine DSC-Ressource zu übergeben. Weitere Informationen finden Sie im Artikel von Gael Colas Pseudo-Splatting DSC Resources.