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 jedem Wert in der Auflistung einen 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.
Splatting macht Ihre Befehle kürzer und einfacher zu lesen. Sie können die Splattingwerte in verschiedenen Befehlsaufrufen wiederverwenden und die Splatting verwenden, um Parameterwerte von 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 Splatted-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 einzigen Befehl splatieren, sodass Sie nicht mehr als einen Wert für jeden Parameter übergeben.
Ab PowerShell 7.1 können Sie einen Splatted-Parameter überschreiben, indem Sie einen Parameter explizit in einem Befehl 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 nach Name 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. Mit dem ersten Befehl wird eine Hashtabelle mit Parameternamen- und Parameter-Wert-Paaren erstellt und in der $HashArguments Variablen gespeichert. Der zweite Befehl verwendet die $HashArguments Variable in einem Befehl mit Splatting. Das At-Symbol (@HashArguments) ersetzt das Dollarzeichen ($HashArguments) im Befehl.
Verwenden Sie $True oder$False, um einen Wert für den WhatIf-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, keinen 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, 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 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
Beispiel 1: Wiederverwenden von beplatteten Parametern in verschiedenen Befehlen
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."
Beispiel 2: Weiterleiten von Parametern mithilfe von $PSBoundParameters
In diesem Beispiel wird gezeigt, wie ihre 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 weiterzuleiten, die an ein Skript oder eine Funktion Test2 von der Funktion an die Test1 Funktion übergeben werden. 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
Beispiel 3: Überschreiben von überschriebenen Parametern mit explizit definierten Parametern
In diesem Beispiel wird gezeigt, wie ein splatted-Parameter mit explizit definierten Parametern überschrieben wird. 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 $commonParams Variable speichert die Parameter zum Erstellen virtueller Computer am East US Speicherort. Die $allVms Variable ist eine Liste der zu erstellenden virtuellen Computer. Wir durchlaufen die Liste und verwenden $commonParams , um die Parameter zu splatieren, um jeden virtuellen Computer zu erstellen. Wir möchten myVM2 jedoch in einer anderen Region als die anderen virtuellen Computer erstellt werden. Anstatt die $commonParams Hashtabelle anzupassen, können Sie explizit den Location-Parameter in New-AzVm 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
}
}
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 Auflisten 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. 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 @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 explizite 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 des CmdletBinding- oder parameter-Attributs 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 konzipiert. Sie können keine Splatting verwenden, um Werte an eine DSC-Ressource zu übergeben. Weitere Informationen finden Sie im Artikel Pseudo-Splatting DSC Resources von Gael Colas.