about_Splatting

Artikel
01/29/2024

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.

Ab PowerShell 7.1 können Sie einen Splatted-Parameter überschreiben, indem Sie einen Parameter in einem Befehl 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 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 variableDollarzeichens () 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: Ü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 $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 die Parameter, 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 den Location-Parameter New-AzVm explizit definieren, um den Wert des Location Schlüssels zu $commonParamsersetzen.

$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
    }
}

Beispiel 4: 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

 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&reg; Windows&reg; 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.