about_Splatting
Krótki opis
Opisuje sposób przekazywania parametrów do poleceń w programie PowerShell przy użyciu splattingu.
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 jednej wartości.
Splatting sprawia, że polecenia są krótsze i łatwiejsze do odczytania. Możesz ponownie użyć wartości splattingu w różnych wywołaniach poleceń i użyć splattingu, aby przekazać wartości parametrów z zmiennej automatycznej $PSBoundParameters do innych skryptów i funkcji.
Począwszy od 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 splattingu 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 splatać 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ótu, aby splat nazwa parametru i pary wartości. Można użyć tego formatu dla wszystkich typów parametrów, w tym parametrów pozycyjnych i przełącznikowych. Parametry pozycyjne muszą być przypisane według nazwy.
W poniższych przykładach porównaliśmy 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 znajdują się 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-name i parametr-value i przechowuje ją w zmiennej $HashArguments . Drugie polecenie używa zmiennej $HashArguments w poleceniu ze splattingiem. 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 do splat wartości parametrów pozycyjnych, które nie wymagają nazw parametrów. Wartości muszą być w kolejności numer-pozycji w tablicy.
W poniższych przykładach porównaliśmy 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 splattingu 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, który jest wykonywany przez polecenie cmdlet. Parametr ArgumentList przyjmuje tablicę wartości przekazywanych do bloku skryptu. Program PowerShell skutecznie używa splattingu tablicy, aby powiązać wartości z parametrami bloku skryptu. W przypadku używania argumentlisty, 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 jest opakowana 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 splatted parametrów 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 używają Write-Host polecenia cmdlet do zapisywania komunikatów w konsoli programu hosta. Używa splattingu, aby określić pierwszy plan i kolory tła.
Aby zmienić kolory wszystkich poleceń, po prostu zmień 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 splattingu w poleceniu Write-Host . Aby użyć elementu $Colors variable, 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 to obiekt 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 Test1 lub funkcji z Test2 funkcji do funkcji. Oba wywołania Test1 funkcji używają Test2 splattingu.
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
Przykład 3. Zastępowanie parametrów z 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ótu używanej do splat.
Zmienna $commonParams przechowuje parametry do tworzenia maszyn wirtualnych w East US lokalizacji. Zmienna $allVms jest listą maszyn wirtualnych do utworzenia. Przeplatamy listę i używamy $commonParams jej do splat parametrów w celu utworzenia każdej maszyny wirtualnej. Chcemy myVM2 jednak utworzyć w innym regionie niż inne maszyny wirtualne. Zamiast dostosowywać tabelę skrótów $commonParams , można jawnie zdefiniować parametr Location w pliku , New-AzVm aby zastąpić wartość Location klucza w $commonParamspliku .
$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
}
}
Parametry polecenia Splatting
Możesz użyć splattingu do reprezentowania parametrów polecenia. Ta technika jest przydatna podczas tworzenia funkcji serwera proxy, czyli funkcji, która wywołuje inne polecenie. Ta funkcja jest wprowadzana w wersji 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 wywoływanej zmiany polecenia.
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
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)
Uwagi
Jeśli funkcja zostanie utworzona w funkcję zaawansowaną przy użyciu atrybutów CmdletBinding lub Parametr , $args zmienna automatyczna nie jest już dostępna w funkcji. Funkcje zaawansowane wymagają jawnej definicji parametrów.
Program PowerShell Desired State Configuration (DSC) nie został zaprojektowany 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.