Informationen zum Splatting
Kurze Beschreibung
Beschreibt, wie Mithilfe von Splatting Parameter an Befehle in PowerShell übergeben werden.
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 anstelle eines einzelnen Werts eine Sammlung von Werten übergeben.
Durch das Splatting werden Ihre Befehle kürzer und einfacher zu lesen. Sie können die Splattingwerte in verschiedenen Befehlsaufrufen wiederverwenden und die Splatting verwenden, um Parameterwerte aus der $PSBoundParameters automatischen Variablen an andere Skripts und Funktionen zu ü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, in denen keine Parameternamen erforderlich sind. Verwenden Sie die Hashtabellensyntax, um Parameternamen- und Wertpaare bereitzustellen. Der geplattete Wert kann an einer beliebigen Stelle in der Parameterliste angezeigt werden.
Beim Splatting 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 nach Position oder nach Parametername übergeben. Außerdem können Sie mehrere Objekte in einem einzelnen 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 Switchparametern. 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 aus Parameter-Name- und Parameter-Wert-Paaren 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-Switchparameter bereitzustellen, verwenden Sie $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 und keinen Splatted-Wert an. 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, für die keine Parameternamen erforderlich sind. Die Werte müssen sich im Array in der Reihenfolge der Positionsnummern befinden.
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 im Befehl in der Reihenfolge der Position 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 Reihenfolge der Position im Array. Der zweite Befehl verwendet die $ArrayArguments Variable in einem Befehl beim 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, das an den Skriptblock übergeben wird. PowerShell verwendet effektiv Arraysplatting, um die Werte an die Parameter des Skriptblocks zu binden. Wenn Sie bei Verwendung von ArgumentList 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.
Das folgende Beispiel enthält einen Skriptblock, der einen einzelnen Parameter akzeptiert, der ein Array von Zeichenfolgen ist.
$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 in ein Array umschlossen, $array sodass das gesamte Array als einzelnes Objekt an den Skriptblock übergeben wird.
Hello World!
Beispiele
In diesem Beispiel wird gezeigt, wie Sie plattete Werte in verschiedenen Befehlen wiederverwenden. 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.
Um die Farben aller Befehle zu ändern, ä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"}
Der zweite und dritte Befehl verwenden die $Colors Variable zum Splatting in einem Write-Host Befehl. Um das $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."
In diesem Beispiel wird gezeigt, wie Die Parameter mithilfe von Splatting und der $PSBoundParameters automatischen Variablen 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 der Funktion an die Test1 Funktion weiterzuleiten. Beide Aufrufe der Test1 Funktion von Test2 verwenden 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
Splatting von Befehlsparametern
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.
Verwenden @Args Sie zum Splatieren der Parameter eines Befehls, um die Befehlsparameter darzustellen. Diese Technik ist einfacher als das Aufzählen von Befehlsparametern und funktioniert ohne Revision, auch wenn sich die Parameter des aufgerufenen Befehls ändern.
Das Feature verwendet die $Args automatische Variable, die alle nicht zugewiesenen Parameterwerte enthält.
Beispielsweise ruft die folgende Funktion das Get-Process Cmdlet auf. In dieser Funktion @Args stellt 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 @Argsübergeben, wie in den folgenden Befehlen gezeigt.
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 Parameter deklariert hat. Sie können es mehr als einmal in einer Funktion verwenden, aber alle Parameter, die Sie eingeben, 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 mithilfe der Attribute CmdletBinding oder Parameter in eine erweiterte Funktion verwandeln, 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 splatting nicht verwenden, um Werte an eine DSC-Ressource zu übergeben. Weitere Informationen finden Sie im Gael Colas-Artikel Pseudo-Splatting DSC-Ressourcen.