about_Splatting
Kurze Beschreibung
Beschreibt die Verwendung von Splatting zum Übergeben von Parametern an Befehle in PowerShell.
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 Splattingvariablen gespeichert, die wie Standardvariablen aussehen, aber mit einem At-Symbol () anstelle eines Dollarzeichens (@
$
) beginnen. Das At-Symbol teilt PowerShell mit, dass Sie eine Auflistung von Werten anstelle eines einzelnen Werts übergeben.
Das Splatting vereinfacht das Lesen von Befehlen. Sie können die Splattingwerte in verschiedenen Befehlsaufrufen wiederverwenden und Mithilfe von Splatting Parameterwerte aus der $PSBoundParameters
automatischen Variablen an andere Skripts und Funktionen übergeben.
Ab 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 splatted-Wert kann an einer beliebigen Stelle in der Parameterliste angezeigt werden.
Beim Splatieren müssen Sie keine Hashtabelle oder ein Array verwenden, um alle Parameter zu übergeben. Sie können einige Parameter übergeben, indem Sie splatting verwenden und andere über Position oder parameternamen übergeben. Außerdem können Sie mehrere Objekte in einem einzigen Befehl splatieren, sodass Sie nicht mehr als einen Wert für jeden Parameter übergeben.
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 die Hashtabellensplatting 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.
Um einen Wert für den WhatIf-Switch-Parameter bereitzustellen, verwenden $True
Oder $False
.
$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 Positionsnummer des Arrays 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 werden in der Position im Befehl angezeigt.
Copy-Item "test.txt" "test2.txt" -WhatIf
Im zweiten Beispiel wird die Arraysplatting verwendet. Der erste Befehl erstellt ein Array der Parameterwerte und speichert es in der $ArrayArguments
Variablen. Die Werte befinden sich in der Position im Array. 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 akzeptiert ein Array von Werten, die an den Skriptblock übergeben werden. PowerShell verwendet effektiv arraysplizieren, um die Werte an die Parameter des Skriptblocks zu binden. Wenn Sie argumentList verwenden, müssen Sie das Array als einziges Objekt übergeben, das an einen einzelnen Parameter gebunden ist, 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 an $array
den Skriptblock übergeben.
Hello
$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
param([string[]]$words) $words -join ' '
} -ArgumentList (,$array)
In diesem Beispiel wird ein Array umbrochen, $array
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 Splatted-Werte in verschiedenen Befehlen wiederverwendet werden. Die Befehle in diesem Beispiel verwenden das Write-Host
Cmdlet, um Nachrichten in die Hostprogrammkonsole zu schreiben. Es verwendet Splatting, um die Vordergrund- und Hintergrundfarben anzugeben.
Wenn Sie die Farben aller Befehle ändern möchten, ändern Sie einfach den Wert der $Colors
Variablen.
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. Ersetzen Sie zum Verwenden des $Colors variable
Dollarzeichens () 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 Sie ihre Parameter mithilfe von Splatting und der $PSBoundParameters
automatischen Variablen an andere Befehle weiterleiten.
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 weiterzuleiten, die von Test2
einer Funktion an ein Skript oder eine Funktion an die Test1
Funktion übergeben werden. Beide Aufrufe der Test1
Funktion werden verwendet, um Test2
splatting zu verwenden.
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
Beispiel 3: Verwenden mehrerer Splatted-Objekte in einem einzigen Befehl
Sie können mehrere Splatted-Objekte in einem einzigen Befehl verwenden. In diesem Beispiel werden verschiedene Parameter in separaten Hashtables definiert. Die Hashtables werden in einem einzigen Write-Host
Befehl plattet.
$a = @{
Message = 'Hello', 'World!'
}
$b = @{
Separator = '|'
}
$c = @{
BackgroundColor = 'Cyan'
ForegroundColor = 'Black'
}
Write-Host @a @b @c
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 zu splatieren, verwenden Sie @Args
diese, 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 Nicht zugewiesenen Parameterwerte enthält.
Die folgende Funktion ruft z. B. das Get-Process
Cmdlet auf. Stellt in dieser Funktion @Args
alle Parameter des Get-Process
Cmdlets dar.
function Get-MyProcess { Get-Process @Args }
Wenn Sie die Get-MyProcess
Funktion verwenden, werden alle nicht zugewiesenen Parameter und Parameterwerte an übergeben @Args
, 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 in einer Funktion verwenden @Args
, die explizit deklarierte Parameter enthält. Sie können sie mehr als einmal in einer Funktion verwenden, aber alle parameter, die Sie eingeben, werden an alle Instanzen von @Args
, wie im folgenden Beispiel gezeigt, übergeben.
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) CPU(s) Id SI ProcessName
------- ------ ----- ----- ------ -- -- -----------
830 50 115840 95524 16.75 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)
Hinweise
Wenn Sie eine Funktion mithilfe der Attribute "CmdletBinding " oder "Parameter " in eine erweiterte Funktion umwandeln, 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 "Pseudo-Splatting DSC Resources" von Gael Colas.