about_Splatting

Artykuł
01/29/2024

Krótki opis

Opisuje sposób używania splattingu do przekazywania parametrów do poleceń w programie PowerShell.

Długi opis

Splatting to metoda przekazywania kolekcji wartości parametrów do polecenia jako jednostki. Program PowerShell kojarzy każdą wartość w kolekcji z parametrem polecenia. Wartości parametrów splatted są przechowywane w nazwanych zmiennychplattingu, które wyglądają jak zmienne standardowe, ale zaczynają się od symbolu At (@) zamiast znaku dolara ($). Symbol At informuje program PowerShell, że przekazujesz kolekcję wartości zamiast pojedynczej wartości.

Splatting sprawia, że polecenia są krótsze i łatwiejsze do odczytania. Możesz ponownie użyć wartości rozplatania w różnych wywołaniach poleceń i użyć splatting, aby przekazać wartości parametrów z zmiennej automatycznej $PSBoundParameters do innych skryptów i funkcji.

Począwszy od programu Windows PowerShell 3.0, można również użyć splattingu do reprezentowania wszystkich parametrów polecenia.

Składnia

<CommandName> <optional parameters> @<HashTable> <optional parameters>
<CommandName> <optional parameters> @<Array> <optional parameters>

Aby podać wartości parametrów dla parametrów pozycyjnych, w których nazwy parametrów nie są wymagane, użyj składni tablicy. Aby podać pary nazw parametrów i wartości, użyj składni tabeli skrótów. Wartość splatted może być wyświetlana w dowolnym miejscu na liście parametrów.

Podczas przeplatania nie trzeba używać tabeli skrótu ani tablicy do przekazywania wszystkich parametrów. Niektóre parametry można przekazać przy użyciu splattingu i przekazać inne według pozycji lub nazwy parametru. Ponadto można umieścić wiele obiektów w jednym poleceniu, aby nie przekazywać więcej niż jednej wartości dla każdego parametru.

Od programu PowerShell 7.1 można zastąpić splatted parametr, jawnie definiując parametr w poleceniu.

Splatting z tabelami skrótów

Użyj tabeli skrótów, aby splat nazwy parametrów i par wartości. Można użyć tego formatu dla wszystkich typów parametrów, w tym parametrów pozycyjnych i przełączników. Parametry pozycyjne muszą być przypisywane według nazwy.

W poniższych przykładach porównamy dwa Copy-Item polecenia, które kopiują plik Test.txt do pliku Test2.txt w tym samym katalogu.

W pierwszym przykładzie użyto tradycyjnego formatu, w którym uwzględniono nazwy parametrów.

Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf

W drugim przykładzie użyto splattingu tabeli skrótów. Pierwsze polecenie tworzy tabelę skrótów par parametrów i parametr-wartość i zapisuje ją w zmiennej $HashArguments . Drugie polecenie używa zmiennej $HashArguments w poleceniu z rozplatania. Symbol At (@HashArguments) zastępuje znak dolara ($HashArguments) w poleceniu .

Aby podać wartość parametru przełącznika WhatIf , użyj polecenia $True lub $False.

$HashArguments = @{
  Path = "test.txt"
  Destination = "test2.txt"
  WhatIf = $true
}
Copy-Item @HashArguments

Uwaga

W pierwszym poleceniu symbol At (@) wskazuje tabelę skrótów, a nie wartość splatted. Składnia tabel skrótów w programie PowerShell to: @{<name>=<value>; <name>=<value>; ...}

Splatting z tablicami

Użyj tablicy, aby umieścić wartości dla parametrów pozycyjnych, które nie wymagają nazw parametrów. Wartości muszą być w kolejności numerów pozycji w tablicy.

W poniższych przykładach porównamy dwa Copy-Item polecenia, które kopiują plik Test.txt do pliku Test2.txt w tym samym katalogu.

W pierwszym przykładzie użyto tradycyjnego formatu, w którym pominięto nazwy parametrów. Wartości parametrów są wyświetlane w kolejności pozycji w poleceniu.

Copy-Item "test.txt" "test2.txt" -WhatIf

W drugim przykładzie użyto platania tablicy. Pierwsze polecenie tworzy tablicę wartości parametrów i przechowuje ją w zmiennej $ArrayArguments . Wartości są w kolejności położenia w tablicy. Drugie polecenie używa zmiennej $ArrayArguments w poleceniu w skrypcie. Symbol At (@ArrayArguments) zastępuje znak dolara ($ArrayArguments) w poleceniu .

$ArrayArguments = "test.txt", "test2.txt"
Copy-Item @ArrayArguments -WhatIf

Używanie parametru ArgumentList

Kilka poleceń cmdlet ma parametr ArgumentList , który służy do przekazywania wartości parametrów do bloku skryptu wykonywanego przez polecenie cmdlet. Parametr ArgumentList przyjmuje tablicę wartości przekazywanych do bloku skryptu. Program PowerShell skutecznie używa splattingu tablicowego, aby powiązać wartości z parametrami bloku skryptu. Jeśli używasz argumentlist, jeśli musisz przekazać tablicę jako pojedynczy obiekt powiązany z pojedynczym parametrem, musisz owinąć tablicę jako jedyny element innej tablicy.

Poniższy przykład zawiera blok skryptu, który przyjmuje pojedynczy parametr, który jest tablicą ciągów.

$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
  param([string[]]$words) $words -join ' '
  } -ArgumentList $array

W tym przykładzie tylko pierwszy element w $array pliku jest przekazywany do bloku skryptu.

Hello

$array = 'Hello', 'World!'
Invoke-Command -ScriptBlock {
  param([string[]]$words) $words -join ' '
} -ArgumentList (,$array)

W tym przykładzie element jest opakowany w tablicę, $array aby cała tablica została przekazana do bloku skryptu jako pojedynczy obiekt.

Hello World!

Przykłady

Przykład 1. Ponowne używanie parametrów splatted w różnych poleceniach

W tym przykładzie pokazano, jak używać ponownie splatted wartości w różnych poleceniach. Polecenia w tym przykładzie Write-Host używają polecenia cmdlet do zapisywania komunikatów w konsoli programu hosta. Używa plattingu, aby określić pierwszy plan i kolory tła.

Aby zmienić kolory wszystkich poleceń, wystarczy zmienić wartość zmiennej $Colors .

Pierwsze polecenie tworzy tabelę skrótów nazw parametrów i wartości oraz przechowuje tabelę skrótów w zmiennej $Colors .

$Colors = @{ForegroundColor = "black"; BackgroundColor = "white"}

Drugie i trzecie polecenia używają zmiennej $Colors do przeplatania w poleceniu Write-Host . Aby użyć $Colors variableznaku , zastąp znak dolara ($Colors) symbolem At (@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."

Przykład 2. Przekazywanie parametrów przy użyciu $PSBoundParameters

W tym przykładzie pokazano, jak przekazywać parametry do innych poleceń przy użyciu splattingu i zmiennej automatycznej $PSBoundParameters .

Zmienna automatyczna $PSBoundParameters jest obiektem słownika (System.Collections.Generic.Dictionary), który zawiera wszystkie nazwy parametrów i wartości używane podczas uruchamiania skryptu lub funkcji.

W poniższym przykładzie używamy zmiennej $PSBoundParameters do przekazywania wartości parametrów przekazanych do skryptu lub funkcji z Test2 funkcji do Test1 funkcji. Oba wywołania Test1 funkcji używają Test2 splattingu.

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

Przykład 3. Zastępowanie parametrów rozdzielonych jawnie zdefiniowanymi parametrami

W tym przykładzie pokazano, jak zastąpić splatted parametr przy użyciu jawnie zdefiniowanych parametrów. Jest to przydatne, gdy nie chcesz tworzyć nowej tabeli skrótów ani zmieniać wartości w tabeli skrótów używanej do splat.

Zmienna $commonParams przechowuje parametry do tworzenia maszyn wirtualnych w East US lokalizacji. Zmienna $allVms jest listą maszyn wirtualnych do utworzenia. Przechodzimy przez listę i używamy $commonParams polecenia , aby utworzyć każdą maszynę wirtualną. myVM2 Chcemy jednak utworzyć w innym regionie niż inne maszyny wirtualne. Zamiast dostosowywać tabelę skrótów $commonParams , można jawnie zdefiniować parametr Location w New-AzVm , aby zastąpić wartość Location klucza w pliku $commonParams.

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

Przykład 4: Używanie wielu splatted obiektów w jednym poleceniu

W jednym poleceniu można użyć wielu splatted obiektów. W tym przykładzie różne parametry są definiowane w osobnych tabelach skrótów. Tabele skrótów są splatted w jednym Write-Host poleceniu.

$a = @{
    Message         = 'Hello', 'World!'
}
$b = @{
    Separator       = '|'
}
$c = @{
    BackgroundColor = 'Cyan'
    ForegroundColor = 'Black'
}
Write-Host @a @b @c

Parametry poleceniaplatting

Do reprezentowania parametrów polecenia można użyć splattingu. Ta technika jest przydatna podczas tworzenia funkcji serwera proxy, czyli funkcji, która wywołuje inne polecenie. Ta funkcja jest wprowadzana w programie Windows PowerShell 3.0.

Aby splat parametry polecenia, użyj polecenia @Args , aby reprezentować parametry polecenia. Ta technika jest łatwiejsza niż wyliczanie parametrów polecenia i działa bez poprawki, nawet jeśli parametry o nazwie polecenie zmieniają się.

Funkcja używa zmiennej automatycznej $Args , która zawiera wszystkie nieprzypisane wartości parametrów.

Na przykład następująca funkcja wywołuje Get-Process polecenie cmdlet . W tej funkcji @Args reprezentuje wszystkie parametry Get-Process polecenia cmdlet.

function Get-MyProcess { Get-Process @Args }

W przypadku korzystania z Get-MyProcess funkcji wszystkie nieprzypisane parametry i wartości parametrów są przekazywane do @Argsmetody , jak pokazano w poniższych poleceniach.

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\...

Można użyć @Args w funkcji, która ma jawnie zadeklarowane parametry. Można go używać więcej niż raz w funkcji, ale wszystkie wprowadzone parametry są przekazywane do wszystkich wystąpień klasy @Args, jak pokazano w poniższym przykładzie.

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)

Uwagi

Jeśli ustawisz funkcję w funkcję zaawansowaną przy użyciu atrybutów CmdletBinding lub Parameter , $args zmienna automatyczna nie jest już dostępna w funkcji. Funkcje zaawansowane wymagają jawnej definicji parametru.

Konfiguracja żądanego stanu programu PowerShell (DSC) nie została zaprojektowana do używania splattingu. Nie można użyć splattingu, aby przekazać wartości do zasobu DSC. Aby uzyskać więcej informacji, zobacz artykuł Gael Colas Pseudo-Splatting DSC Resources.