about_Automatic_Variables

Krótki opis

Opisuje zmienne, które przechowują informacje o stanie programu PowerShell. Te zmienne są tworzone i obsługiwane przez program PowerShell.

Długi opis

Koncepcyjnie te zmienne są uważane za tylko do odczytu. Mimo że można je zapisać, w celu zapewnienia zgodności z poprzednimi wersjami nie powinny być zapisywane.

Oto lista zmiennych automatycznych w programie PowerShell:

$$

Zawiera ostatni token w ostatnim wierszu odebrany przez sesję.

$?

Zawiera stan wykonania ostatniego polecenia. Zawiera wartość True , jeśli ostatnie polecenie powiodło się i False , jeśli nie powiodło się.

W przypadku poleceń cmdlet i zaawansowanych funkcji, które są uruchamiane na wielu etapach w potoku, na przykład w obu process i end blokach, wywołanie this.WriteError() lub $PSCmdlet.WriteError() odpowiednio w dowolnym punkcie zostanie ustawione $? na Wartość False, jak i this.ThrowTerminatingError()$PSCmdlet.ThrowTerminatingError().

Polecenie Write-Error cmdlet zawsze ustawia $? wartość False natychmiast po jego wykonaniu, ale nie ustawi $? wartości False dla funkcji wywołującej ją:

function Test-WriteError
{
    Write-Error "Bad"
    $? # $false
}

Test-WriteError
$? # $true

W tym ostatnim celu $PSCmdlet.WriteError() należy zamiast tego użyć.

W przypadku poleceń natywnych (wykonywalnych) $? ustawiono wartość True , gdy $LASTEXITCODE ma wartość 0, i ustawiono wartość False , jeśli $LASTEXITCODE jest dowolną inną wartością.

Uwaga

Dopóki program PowerShell 7 nie zawiera instrukcji w nawiasach (...), składnia $(...) subexpressionu lub wyrażenie @(...) tablicy zawsze resetuje $? wartość True, tak aby (Write-Error) pokazywała $? wartość True. Ta zmiana została zmieniona w programie PowerShell 7, dzięki czemu $? zawsze będzie odzwierciedlać rzeczywisty sukces ostatniego uruchomienia polecenia w tych wyrażeniach.

$^

Zawiera pierwszy token w ostatnim wierszu odebrany przez sesję.

$_

Tak samo jak $PSItem. Zawiera bieżący obiekt w obiekcie potoku. Tej zmiennej można użyć w poleceniach, które wykonują akcję na każdym obiekcie lub na wybranych obiektach w potoku.

$args

Zawiera tablicę wartości dla niezdecydowanych parametrów przekazywanych do funkcji, skryptu lub bloku skryptu. Podczas tworzenia funkcji można zadeklarować parametry przy użyciu param słowa kluczowego lub dodając rozdzielaną przecinkami listę parametrów w nawiasach po nazwie funkcji.

W przypadku akcji zmienna $args zawiera obiekty reprezentujące argumenty zdarzenia, które są przetwarzane. Ta zmienna jest wypełniana tylko w Action bloku polecenia rejestracji zdarzeń. Wartość tej zmiennej można również znaleźć we właściwości SourceArgs obiektu PSEventArgs , który Get-Event zwraca.

$ConsoleFileName

Zawiera ścieżkę pliku konsoli (.psc1), który był ostatnio używany w sesji. Ta zmienna jest wypełniana podczas uruchamiania programu PowerShell za pomocą parametru PSConsoleFile lub podczas eksportowania nazw przystawki do pliku konsoli za pomocą Export-Console polecenia cmdlet.

Gdy używasz Export-Console polecenia cmdlet bez parametrów, automatycznie aktualizuje plik konsoli, który był ostatnio używany w sesji. Tej zmiennej automatycznej można użyć do określenia, który plik zostanie zaktualizowany.

$Error

Zawiera tablicę obiektów błędów, które reprezentują najnowsze błędy. Ostatni błąd to pierwszy obiekt błędu w tablicy $Error[0].

Aby zapobiec dodawaniu błędu do tablicy, użyj wspólnego parametru $ErrorErrorAction z wartością Ignoruj. Aby uzyskać więcej informacji, zobacz about_CommonParameters.

$Event

Zawiera obiekt PSEventArgs reprezentujący zdarzenie, które jest przetwarzane. Ta zmienna jest wypełniana tylko w Action bloku polecenia rejestracji zdarzeń, na przykład Register-ObjectEvent. Wartość tej zmiennej jest tym samym obiektem, który Get-Event zwraca polecenie cmdlet. W związku z tym można użyć właściwości zmiennej Event , takiej jak $Event.TimeGenerated, w bloku skryptu Action .

$EventArgs

Zawiera obiekt reprezentujący pierwszy argument zdarzenia, który pochodzi z eventArgs zdarzenia, które jest przetwarzane. Ta zmienna jest wypełniana tylko w Action bloku polecenia rejestracji zdarzeń. Wartość tej zmiennej można również znaleźć we właściwości SourceEventArgs obiektu PSEventArgs , który Get-Event zwraca.

$EventSubscriber

Zawiera obiekt PSEventSubscriber reprezentujący subskrybenta zdarzenia, które jest przetwarzane. Ta zmienna jest wypełniana tylko w Action bloku polecenia rejestracji zdarzeń. Wartość tej zmiennej jest tym samym obiektem, który Get-EventSubscriber zwraca polecenie cmdlet.

$ExecutionContext

Zawiera obiekt EngineIntrinsics , który reprezentuje kontekst wykonywania hosta programu PowerShell. Tej zmiennej można użyć do znajdowania obiektów wykonywania, które są dostępne dla poleceń cmdlet.

$false

Zawiera wartość False. Za pomocą tej zmiennej można reprezentować wartość False w poleceniach i skryptach zamiast używać ciągu "false". Ciąg może być interpretowany jako True , jeśli jest konwertowany na ciąg inny niż pusty lub do liczby całkowitej innej niż zero.

$foreach

Zawiera moduł wyliczający (a nie wynikowe wartości) pętli ForEach . Zmienna $ForEach istnieje tylko wtedy, gdy ForEach pętla jest uruchomiona; jest usuwana po zakończeniu pętli.

Moduły wyliczania zawierają właściwości i metody, których można użyć do pobierania wartości pętli i zmiany iteracji bieżącej pętli. Aby uzyskać więcej informacji, zobacz Using Enumerators (Używanie modułów wyliczania).

$HOME

Zawiera pełną ścieżkę katalogu macierzystego użytkownika. Ta zmienna jest odpowiednikiem "$env:homedrive$env:homepath" zmiennych środowiskowych systemu Windows, zazwyczaj C:\Users\<UserName>.

$Host

Zawiera obiekt reprezentujący bieżącą aplikację hosta dla programu PowerShell. Tej zmiennej można użyć do reprezentowania bieżącego hosta w poleceniach lub wyświetlania lub zmieniania właściwości hosta, takich jak $Host.version lub $Host.CurrentCulture, lub $host.ui.rawui.setbackgroundcolor("Red").

$input

Zawiera moduł wyliczający, który wylicza wszystkie dane wejściowe przekazywane do funkcji. Zmienna $input jest dostępna tylko dla funkcji i bloków skryptów (które są nienazwanych funkcjami).

  • W funkcji bez Beginelementu , Processlub End bloku $input zmienna wylicza kolekcję wszystkich danych wejściowych funkcji.

  • W bloku zmienna Begin$input nie zawiera żadnych danych.

  • Process W bloku zmienna $input zawiera obiekt, który znajduje się obecnie w potoku.

  • End W bloku zmienna $input wylicza kolekcję wszystkich danych wejściowych funkcji.

    Uwaga

    Nie można użyć zmiennej $input wewnątrz bloku Proces i bloku Koniec w tej samej funkcji lub bloku skryptu.

Ponieważ $input jest modułem wyliczającym, uzyskiwanie dostępu do dowolnej z jego właściwości powoduje $input , że nie będzie już dostępny. Możesz przechowywać $input w innej zmiennej w celu ponownego $input użycia właściwości.

Moduły wyliczania zawierają właściwości i metody, których można użyć do pobierania wartości pętli i zmiany iteracji bieżącej pętli. Aby uzyskać więcej informacji, zobacz Using Enumerators (Używanie modułów wyliczania).

Zmienna $input jest również dostępna dla polecenia określonego -Command przez parametr pwsh w przypadku wywołania z wiersza polecenia. Poniższy przykład jest uruchamiany z powłoki poleceń systemu Windows.

echo Hello | pwsh -Command """$input World!"""

$IsCoreCLR

Zawiera $True , czy bieżąca sesja jest uruchomiona w środowisku uruchomieniowym platformy .NET Core (CoreCLR). W przeciwnym razie zawiera wartość $False.

$IsLinux

Zawiera $True , czy bieżąca sesja jest uruchomiona w systemie operacyjnym Linux. W przeciwnym razie zawiera wartość $False.

$IsMacOS

Zawiera $True , czy bieżąca sesja jest uruchomiona w systemie operacyjnym MacOS. W przeciwnym razie zawiera wartość $False.

$IsWindows

Zawiera $TRUE , czy bieżąca sesja jest uruchomiona w systemie operacyjnym Windows. W przeciwnym razie zawiera wartość $FALSE.

$LastExitCode

Zawiera kod zakończenia ostatniego natywnego programu, który został uruchomiony.

$Matches

Zmienna $Matches działa z operatorami -match i -notmatch . Po przesłaniu -match danych wejściowych skalarnych do operatora or -notmatch i wykryciu dopasowania zwracają wartość logiczną i wypełniają $Matches zmienną automatyczną tabelą skrótów pasujących wartości ciągów. Tabelę $Matches skrótów można również wypełnić przy użyciu przechwytywania, gdy używasz wyrażeń regularnych z operatorem -match .

Aby uzyskać więcej informacji na temat -match operatora, zobacz about_Comparison_Operators. Aby uzyskać więcej informacji na temat wyrażeń regularnych, zobacz about_Regular_Expressions.

Zmienna $Matches działa również w instrukcji switch z parametrem -Regex . Jest wypełniany w taki sam sposób jak -match operatory i -notmatch . Aby uzyskać więcej informacji na temat instrukcji switch , zobacz about_Switch.

Uwaga

Gdy $Matches jest wypełniana w sesji, zachowuje dopasowaną wartość, dopóki nie zostanie zastąpiona przez inne dopasowanie. Jeśli -match zostanie użyty ponownie i nie zostanie znalezione dopasowanie, nie zostanie ono zresetowane $Matches do elementu $null. Wcześniej dopasowana wartość jest przechowywana do $Matches momentu znalezienia innego dopasowania.

$MyInvocation

Zawiera informacje o bieżącym poleceniu, takie jak nazwa, parametry, wartości parametrów i informacje o sposobie uruchomienia, wywołania lub wywołania polecenia, takie jak nazwa skryptu, który nazwał bieżące polecenie.

$MyInvocation jest wypełniany tylko dla skryptów, funkcji i bloków skryptów. Informacje można użyć w obiekcie System.Management.Automation.InvocationInfo zwracanym $MyInvocation w bieżącym skrypcie, takim jak ścieżka i nazwa pliku skryptu ($MyInvocation.MyCommand.Path) lub nazwa funkcji ($MyInvocation.MyCommand.Name), aby zidentyfikować bieżące polecenie. Jest to szczególnie przydatne w przypadku znajdowania nazwy bieżącego skryptu.

Począwszy od programu PowerShell 3.0, MyInvocation ma następujące nowe właściwości.

  • PSScriptRoot — zawiera pełną ścieżkę do skryptu, który wywołał bieżące polecenie. Wartość tej właściwości jest wypełniana tylko wtedy, gdy obiekt wywołujący jest skryptem.
  • PSCommandPath — zawiera pełną ścieżkę i nazwę pliku skryptu, który wywołał bieżące polecenie. Wartość tej właściwości jest wypełniana tylko wtedy, gdy obiekt wywołujący jest skryptem.

$PSScriptRoot W przeciwieństwie do zmiennych automatycznych i $PSCommandPath właściwości $MyInvocationPSScriptRoot i PSCommandPath zmiennej automatycznej zawierają informacje o wywołaniu lub skrypcie wywołującym, a nie bieżącym skrypcie.

$NestedPromptLevel

Zawiera bieżący poziom monitu. Wartość 0 wskazuje oryginalny poziom monitu. Wartość jest zwiększana po wprowadzeniu zagnieżdżonego poziomu i dekrementacji po jej zakończeniu.

Na przykład program PowerShell wyświetla zagnieżdżony wiersz polecenia podczas korzystania z $Host.EnterNestedPrompt metody . Program PowerShell wyświetla również zagnieżdżony wiersz polecenia po osiągnięciu punktu przerwania w debugerze programu PowerShell.

Po wprowadzeniu wiersza polecenia zagnieżdżonego program PowerShell wstrzymuje bieżące polecenie, zapisuje kontekst wykonywania i zwiększa wartość zmiennej $NestedPromptLevel . Aby utworzyć dodatkowe zagnieżdżone wiersze polecenia (do 128 poziomów) lub wrócić do oryginalnego wiersza polecenia, ukończ polecenie lub wpisz exit.

Zmienna $NestedPromptLevel ułatwia śledzenie poziomu monitu. Możesz utworzyć alternatywny wiersz polecenia programu PowerShell zawierający tę wartość, aby był zawsze widoczny.

$null

$null jest zmienną automatyczną zawierającą wartość null lub pustą. Tej zmiennej można użyć do reprezentowania nieobecnej lub niezdefiniowanej wartości w poleceniach i skryptach.

Program PowerShell traktuje $null jako obiekt z wartością, czyli jako jawny symbol zastępczy, dzięki czemu można użyć $null elementu do reprezentowania pustej wartości w serii wartości.

Na przykład jeśli $null element jest uwzględniony w kolekcji, jest on liowany jako jeden z obiektów.

$a = "one", $null, "three"
$a.count
3

W przypadku potoku zmiennej $null do ForEach-Object polecenia cmdlet generuje wartość $null, tak samo jak w przypadku innych obiektów

"one", $null, "three" | ForEach-Object { "Hello " + $_}
Hello one
Hello
Hello three

W związku z tym nie można użyć $null polecenia , aby nie oznaczać żadnej wartości parametru. Wartość parametru zastępuje wartość parametru $null domyślnego.

Jednak ponieważ program PowerShell traktuje $null zmienną jako symbol zastępczy, można jej użyć w skryptach takich jak poniższy, co nie działałoby, gdyby $null zostały zignorowane.

$calendar = @($null, $null, "Meeting", $null, $null, "Team Lunch", $null)
$days = "Sunday","Monday","Tuesday","Wednesday","Thursday",
        "Friday","Saturday"
$currentDay = 0
foreach($day in $calendar)
{
    if($day -ne $null)
    {
        "Appointment on $($days[$currentDay]): $day"
    }

    $currentDay++
}
Appointment on Tuesday: Meeting
Appointment on Friday: Team lunch

$PID

Zawiera identyfikator procesu (PID) procesu, który hostuje bieżącą sesję programu PowerShell.

$PROFILE

Zawiera pełną ścieżkę profilu programu PowerShell dla bieżącego użytkownika i bieżącej aplikacji hosta. Tej zmiennej można użyć do reprezentowania profilu w poleceniach. Można na przykład użyć go w poleceniu, aby określić, czy profil został utworzony:

Test-Path $PROFILE

Możesz też użyć go w poleceniu , aby utworzyć profil:

New-Item -ItemType file -Path $PROFILE -Force

Możesz go użyć w poleceniu , aby otworzyć profil w notepad.exe:

notepad.exe $PROFILE

$PSBoundParameters

Zawiera słownik parametrów przekazywanych do skryptu lub funkcji i ich bieżących wartości. Ta zmienna ma wartość tylko w zakresie, w którym są deklarowane parametry, takie jak skrypt lub funkcja. Służy do wyświetlania lub zmieniania bieżących wartości parametrów lub przekazywania wartości parametrów do innego skryptu lub funkcji.

W tym przykładzie funkcja Test2 przekazuje $PSBoundParameters element do funkcji Test1 . Wartości $PSBoundParameters są wyświetlane w formacie Klucz i Wartość.

function Test1 {
   param($a, $b)

   # Display the parameters in dictionary format.
   $PSBoundParameters
}

function Test2 {
   param($a, $b)

   # Run the Test1 function with $a and $b.
   Test1 @PSBoundParameters
}
Test2 -a Power -b Shell
Key   Value
---   -----
a     Power
b     Shell

$PSCmdlet

Zawiera obiekt reprezentujący polecenie cmdlet lub funkcję zaawansowaną, która jest uruchamiana.

Aby odpowiedzieć na warunki użytkowania, możesz użyć właściwości i metod obiektu w kodzie polecenia cmdlet lub funkcji. Na przykład właściwość ParameterSetName zawiera nazwę używanego zestawu parametrów, a metoda ShouldProcess dodaje parametry WhatIf i Confirm do polecenia cmdlet dynamicznie.

Aby uzyskać więcej informacji na temat zmiennej automatycznej $PSCmdlet , zobacz about_Functions_CmdletBindingAttribute i about_Functions_Advanced.

$PSCommandPath

Zawiera pełną ścieżkę i nazwę pliku skryptu, który jest uruchamiany. Ta zmienna jest prawidłowa we wszystkich skryptach.

$PSCulture

Począwszy od programu PowerShell 7, $PSCulture odzwierciedla kulturę bieżącej przestrzeni uruchomieniowej programu PowerShell (sesji). Jeśli kultura zostanie zmieniona w przestrzeni uruchomieniowej programu PowerShell, zostanie zaktualizowana $PSCulture wartość dla tego obszaru uruchomieniowego.

Kultura określa format wyświetlania elementów, takich jak liczby, waluta i daty, i jest przechowywany w obiekcie System.Globalization.CultureInfo . Służy Get-Culture do wyświetlania kultury komputera. $PSCulture zawiera wartość właściwości Name .

$PSDebugContext

Podczas debugowania ta zmienna zawiera informacje o środowisku debugowania. W przeciwnym razie zawiera wartość null . W związku z tym można go użyć, aby wskazać, czy debuger ma kontrolę. Po wypełnieniu zawiera on obiekt PsDebugContext zawierający właściwości Punkty przerwania i InvocationInfo . Właściwość InvocationInfo ma kilka przydatnych właściwości, w tym właściwość Location . Właściwość Location wskazuje ścieżkę skryptu, który jest debugowany.

$PSHOME

Zawiera pełną ścieżkę katalogu instalacyjnego programu PowerShell, zazwyczaj w $env:windir\System32\PowerShell\v1.0 systemach Windows. Tej zmiennej można używać w ścieżkach plików programu PowerShell. Na przykład następujące polecenie wyszukuje tematy pomocy koncepcyjnej dla zmiennej wyrazu:

Select-String -Pattern Variable -Path $pshome\*.txt

$PSItem

Tak samo jak $_. Zawiera bieżący obiekt w obiekcie potoku. Tej zmiennej można użyć w poleceniach, które wykonują akcję na każdym obiekcie lub na wybranych obiektach w potoku.

$PSScriptRoot

Zawiera pełną ścieżkę katalogu nadrzędnego wykonywania skryptu.

W programie PowerShell 2.0 ta zmienna jest prawidłowa tylko w modułach skryptów (.psm1). Począwszy od programu PowerShell 3.0, jest on prawidłowy we wszystkich skryptach.

$PSSenderInfo

Zawiera informacje o użytkowniku, który uruchomił program PSSession, w tym tożsamość użytkownika i strefę czasową komputera źródłowego. Ta zmienna jest dostępna tylko w plikach PSSessions.

Zmienna $PSSenderInfo zawiera właściwość konfigurowalną użytkownika ApplicationArguments, która domyślnie zawiera tylko $PSVersionTable element z sesji źródłowej. Aby dodać dane do właściwości ApplicationArguments, użyj parametru New-PSSessionOptionApplicationArguments polecenia cmdlet .

$PSUICulture

Zawiera nazwę kultury interfejsu użytkownika używanej obecnie w systemie operacyjnym. Kultura interfejsu użytkownika określa, które ciągi tekstowe są używane dla elementów interfejsu użytkownika, takich jak menu i komunikaty. Jest to wartość Elementu System.Globalization.CultureInfo.Current UICulture.Name właściwość systemu. Aby uzyskać obiekt System.Globalization.CultureInfo dla systemu, użyj Get-UICulture polecenia cmdlet .

$PSVersionTable

Zawiera tabelę skrótów tylko do odczytu, która wyświetla szczegółowe informacje o wersji programu PowerShell uruchomionej w bieżącej sesji. Tabela zawiera następujące elementy:

  • PSVersion — numer wersji programu PowerShell
  • PsEdition Ta właściwość ma wartość "Desktop" dla programu PowerShell 4 i poniżej, a także program PowerShell 5.1 w pełnych wersjach systemu Windows. Ta właściwość ma wartość Core dla programu PowerShell 6 lub nowszego, a także programu PowerShell PowerShell 5.1 w wersjach o zmniejszonym zasięgu, takich jak Windows Nano Server lub Windows IoT.
  • GitCommitId — identyfikator zatwierdzenia plików źródłowych w usłudze GitHub
  • System operacyjny — opis systemu operacyjnego, na którym działa program PowerShell.
  • Platforma — platforma , na którą działa system operacyjny. Wartość w systemach Linux i macOS to Unix. Zobacz $IsMacOs i $IsLinux.
  • PSCompatibleVersions — wersje programu PowerShell zgodne z bieżącą wersją
  • PSRemotingProtocolVersion — wersja protokołu zdalnego zarządzania programu PowerShell.
  • SerializationVersion — wersja metody serializacji
  • WSManStackVersion — numer wersji stosu WS-Management

$PWD

Zawiera obiekt ścieżki, który reprezentuje pełną ścieżkę bieżącej lokalizacji katalogu dla bieżącej przestrzeni uruchomieniowej programu PowerShell.

Uwaga

Program PowerShell obsługuje wiele obszarów runspace na proces. Każdy obszar runspace ma swój własny bieżący katalog. Nie jest to samo co bieżący katalog procesu: [System.Environment]::CurrentDirectory.

$Sender

Zawiera obiekt, który wygenerował to zdarzenie. Ta zmienna jest wypełniana tylko w bloku Akcja polecenia rejestracji zdarzeń. Wartość tej zmiennej można również znaleźć we właściwości Sender obiektu PSEventArgs , który Get-Event zwraca.

$ShellId

Zawiera identyfikator bieżącej powłoki.

$StackTrace

Zawiera ślad stosu dla najnowszego błędu.

$switch

Zawiera moduł wyliczający, a nie wynikowe wartości instrukcji Switch . Zmienna $switch istnieje tylko wtedy, gdy Switch instrukcja jest uruchomiona; jest usuwana po zakończeniu switch wykonywania instrukcji. Aby uzyskać więcej informacji, zobacz about_Switch.

Moduły wyliczania zawierają właściwości i metody, których można użyć do pobierania wartości pętli i zmiany iteracji bieżącej pętli. Aby uzyskać więcej informacji, zobacz Using Enumerators (Używanie modułów wyliczania).

$this

Zmienna $this jest używana w blokach skryptów, które rozszerzają klasy, aby odwoływać się do wystąpienia samej klasy.

Rozszerzalny system typów programu PowerShell (ETS) umożliwia dodawanie właściwości do klas przy użyciu bloków skryptów. W bloku skryptu definiującym właściwość skryptu lub metodę $this skryptu zmienna odwołuje się do wystąpienia obiektu klasy, która jest rozszerzana. Na przykład program PowerShell używa systemu ETS do dodawania właściwości BaseName do klasy FileInfo .

PS> Get-ChildItem .\README.md | Get-Member BaseName | Format-List

TypeName   : System.IO.FileInfo
Name       : BaseName
MemberType : ScriptProperty
Definition : System.Object BaseName {get=if ($this.Extension.Length -gt 0){$this.Name.Remove($this.Name.Length -
             $this.Extension.Length)}else{$this.Name};}

Aby uzyskać więcej informacji, zobacz about_Types.ps1xml.

W klasie programu PowerShell zmienna $this odwołuje się do obiektu wystąpienia samej klasy, umożliwiając dostęp do właściwości i metod zdefiniowanych w klasie. Aby uzyskać więcej informacji, zobacz about_Classes.

Zmienna $this jest również używana przez klasy zdarzeń platformy .NET, które przyjmują bloki skryptów jako delegatów dla programu obsługi zdarzeń. W tym scenariuszu $this reprezentuje obiekt pochodzący z zdarzenia, znany jako nadawca zdarzeń.

$true

Zawiera wartość True. Tej zmiennej można użyć do reprezentowania wartości True w poleceniach i skryptach.

Korzystanie z modułów wyliczania

Zmienne $input, $foreachi $switch to wszystkie moduły wyliczające używane do iterowania wartości przetworzonych przez blok kodu.

Moduł wyliczający zawiera właściwości i metody, których można użyć do przechodzenia lub resetowania iteracji albo pobierania wartości iteracji. Bezpośrednie manipulowanie wyliczeniami nie jest uznawane za najlepsze rozwiązanie.

  • W pętlach słowa kluczowe sterowania przepływem przerywają i powinny być preferowane.

  • W ramach funkcji, które akceptują dane wejściowe potoku, najlepszym rozwiązaniem jest użycie parametrów z atrybutami ValueFromPipeline lub ValueFromPipelineByPropertyName.

    Aby uzyskać więcej informacji, zobacz about_Functions_Advanced_Parameters.

MoveNext

Metoda MoveNext rozwija moduł wyliczający do następnego elementu kolekcji. Funkcja MoveNext zwraca wartość True , jeśli moduł wyliczający został pomyślnie zaawansowany, False jeśli moduł wyliczający przeszedł koniec kolekcji.

Uwaga

Wartość logiczna zwrócona przez funkcję MoveNext jest wysyłana do strumienia wyjściowego. Dane wyjściowe można pominąć przez wpisanie go do [void] lub potokowanie do wartości Out-Null.

$input.MoveNext() | Out-Null
[void]$input.MoveNext()

Reset

Metoda Reset ustawia moduł wyliczający na jego początkowe położenie, czyli przed pierwszym elementem w kolekcji.

Current

Właściwość Current pobiera element w kolekcji lub potoku w bieżącej pozycji modułu wyliczającego.

Właściwość Current nadal zwraca tę samą właściwość, dopóki właściwość MoveNext nie zostanie wywołana.

Przykłady

Przykład 1. Używanie zmiennej $input

W poniższym przykładzie uzyskiwanie dostępu do zmiennej $input usuwa zmienną do następnego uruchomienia bloku procesu. Reset Użycie metody resetuje zmienną $input do bieżącej wartości potoku.

function Test
{
    begin
    {
        $i = 0
    }

    process
    {
        "Iteration: $i"
        $i++
        "`tInput: $input"
        "`tAccess Again: $input"
        $input.Reset()
        "`tAfter Reset: $input"
    }
}

"one","two" | Test
Iteration: 0
    Input: one
    Access Again:
    After Reset: one
Iteration: 1
    Input: two
    Access Again:
    After Reset: two

Blok procesu automatycznie rozwija zmienną $input , nawet jeśli nie uzyskujesz do niej dostępu.

$skip = $true
function Skip
{
    begin
    {
        $i = 0
    }

    process
    {
        "Iteration: $i"
        $i++
        if ($skip)
        {
            "`tSkipping"
            $skip = $false
        }
        else
        {
            "`tInput: $input"
        }
    }
}

"one","two" | Skip
Iteration: 0
    Skipping
Iteration: 1
    Input: two

Przykład 2. Używanie $input poza blokiem procesu

Poza blokiem $input procesu zmienna reprezentuje wszystkie wartości przesyłane potokiem do funkcji.

  • Uzyskiwanie dostępu do zmiennej $input usuwa wszystkie wartości.
  • Metoda Reset resetuje całą kolekcję.
  • Właściwość Current nigdy nie jest wypełniana.
  • Metoda MoveNext zwraca wartość false, ponieważ kolekcja nie może być zaawansowana.
    • Wywołanie metody MoveNext usuwa zmienną $input .
Function All
{
    "All Values: $input"
    "Access Again: $input"
    $input.Reset()
    "After Reset: $input"
    $input.MoveNext() | Out-Null
    "After MoveNext: $input"
}

"one","two","three" | All
All Values: one two three
Access Again:
After Reset: one two three
After MoveNext:

Przykład 3. Używanie $input.Current własność

Za pomocą właściwości bieżąca wartość potoku Current może być uzyskiwana wiele razy bez użycia Reset metody . Blok procesu nie wywołuje automatycznie metody MoveNext .

Właściwość Current nigdy nie zostanie wypełniona, chyba że jawnie wywołasz metodę MoveNext. Dostęp Current do właściwości można uzyskać wiele razy w bloku procesu bez wyczyszczenia jego wartości.

function Current
{
    begin
    {
        $i = 0
    }

    process
    {
        "Iteration: $i"
        $i++
        "`tBefore MoveNext: $($input.Current)"
        $input.MoveNext() | Out-Null
        "`tAfter MoveNext: $($input.Current)"
        "`tAccess Again: $($input.Current)"
    }
}

"one","two" | Current
Iteration: 0
    Before MoveNext:
    After MoveNext: one
    Access Again: one
Iteration: 1
    Before MoveNext:
    After MoveNext: two
    Access Again: two

Przykład 4. Używanie zmiennej $foreach

W przeciwieństwie do zmiennej $input zmienna $foreach zawsze reprezentuje wszystkie elementy w kolekcji po korzystaniu bezpośrednio. Użyj właściwości , Current aby uzyskać dostęp do bieżącego elementu kolekcji, oraz Reset metod MoveNext , aby zmienić jego wartość.

Uwaga

Każda iteracja foreach pętli będzie automatycznie wywoływać metodę MoveNext .

Poniższa pętla jest wykonywana tylko dwa razy. W drugiej iteracji kolekcja zostanie przeniesiona do trzeciego elementu przed ukończeniem iteracji. Po drugiej iteracji nie ma teraz więcej wartości do iteracji, a pętla kończy się.

Właściwość MoveNext nie ma wpływu na zmienną wybraną do iterowania przez kolekcję ($Num).

$i = 0
foreach ($num in ("one","two","three"))
{
    "Iteration: $i"
    $i++
    "`tNum: $num"
    "`tCurrent: $($foreach.Current)"

    if ($foreach.Current -eq "two")
    {
        "Before MoveNext (Current): $($foreach.Current)"
        $foreach.MoveNext() | Out-Null
        "After MoveNext (Current): $($foreach.Current)"
        "Num has not changed: $num"
    }
}
Iteration: 0
        Num: one
        Current: one
Iteration: 1
        Num: two
        Current: two
Before MoveNext (Current): two
After MoveNext (Current): three
Num has not changed: two

Reset Użycie metody resetuje bieżący element w kolekcji. Poniższy przykład dwa razy przechodzi przez pierwsze dwa elementy, ponieważ metoda jest wywoływana Reset . Po dwóch pierwszych pętlach instrukcja kończy się niepowodzeniem, a if pętla wykonuje iterację przez wszystkie trzy elementy normalnie.

Ważne

Może to spowodować nieskończoną pętlę.

$stopLoop = 0
foreach ($num in ("one","two", "three"))
{
    ("`t" * $stopLoop) + "Current: $($foreach.Current)"

    if ($num -eq "two" -and $stopLoop -lt 2)
    {
        $foreach.Reset() | Out-Null
        ("`t" * $stopLoop) + "Reset Loop: $stopLoop"
        $stopLoop++
    }
}
Current: one
Current: two
Reset Loop: 0
        Current: one
        Current: two
        Reset Loop: 1
                Current: one
                Current: two
                Current: three

Przykład 5. Używanie zmiennej $switch

Zmienna $switch ma dokładnie te same reguły co zmienna $foreach . W poniższym przykładzie przedstawiono wszystkie pojęcia modułu wyliczającego.

Uwaga

Zwróć uwagę, że wielkość liter NotEvaluated nigdy nie jest wykonywana, mimo że nie break ma instrukcji po metodzie MoveNext .

$values = "Start", "MoveNext", "NotEvaluated", "Reset", "End"
$stopInfinite = $false
switch ($values)
{
    "MoveNext" {
        "`tMoveNext"
        $switch.MoveNext() | Out-Null
        "`tAfter MoveNext: $($switch.Current)"
    }
    # This case is never evaluated.
    "NotEvaluated" {
        "`tAfterMoveNext: $($switch.Current)"
    }

    "Reset" {
        if (!$stopInfinite)
        {
            "`tReset"
            $switch.Reset()
            $stopInfinite = $true
        }
    }

    default {
        "Default (Current): $($switch.Current)"
    }
}
Default (Current): Start
    MoveNext
    After MoveNext: NotEvaluated
    Reset
Default (Current): Start
    MoveNext
    After MoveNext: NotEvaluated
Default (Current): End

Zobacz też