о_автоматических_переменных

Краткое описание

Описывает переменные, которые хранят информацию о состоянии и создаются и поддерживаются средой PowerShell.

Длинное описание

Концептуально большинство этих переменных считаются доступны только для чтения. Несмотря на то, что на них можно записывать, для обеспечения обратной совместимости на них не следует записывать.

Ниже приведен список автоматических переменных в PowerShell:

$$
$?
$^
$_
$args
$ConsoleFileName
$EnabledExperimentalFeatures
$Error
$Event
$EventArgs
$EventSubscriber
$ExecutionContext
$false
$foreach
$HOME
$Host
$input
$IsCoreCLR
$IsLinux
$IsMacOS
$IsWindows
$LASTEXITCODE
$Matches
$MyInvocation
$NestedPromptLevel
$null
$PID
$PROFILE
$PSBoundParameters
$PSCmdlet
$PSCommandPath
$PSCulture
$PSDebugContext
$PSEdition
$PSHOME
$PSItem
$PSScriptRoot
$PSSenderInfo
$PSUICulture
$PSVersionTable
$PWD
$Sender
$ShellId
$StackTrace
$switch
$this
$true

`$$`

Содержит последний токен в последней строке, полученной в ходе сеанса.

`$?`

Содержит состояние выполнения последней команды. Он содержит True, если последняя команда завершилась успешно и False, если она завершилась ошибкой. Ошибки синтаксического разбора не приводят к выполнению, поэтому они не влияют на значение $?.

Для командлетов и расширенных функций, выполняемых на нескольких этапах конвейера, например в блоках process и end, вызов this.WriteError() или $PSCmdlet.WriteError() соответственно в любой точке задает $? значение False, как и this.ThrowTerminatingError() и $PSCmdlet.ThrowTerminatingError().

Командлет Write-Error всегда устанавливает $? в False сразу после его выполнения, но не будет устанавливать $? в False для функции, которая его вызывает:

function Test-WriteError
{
    Write-Error "Bad"
    "The `$? variable is: $?"
}

Test-WriteError
"Now the `$? variable is: $?"

Test-WriteError:
Line |
   7 |  Test-WriteError
     |  ~~~~~~~~~~~~~~~
     | Bad
The $? variable is: False
Now the $? variable is: True

Для последней цели вместо этого следует использовать $PSCmdlet.WriteError().

Для собственных команд (исполняемых файлов) $? устанавливается в True, когда $LASTEXITCODE равно 0, и в False, когда $LASTEXITCODE имеет любое другое значение.

Заметка

До PowerShell 7 оборачивание инструкции в круглые скобки (...), синтаксис вложенных выражений $(...)или выражение массива @(...) всегда приводило $? к true. Например, (Write-Error) отображает $? как True. Это поведение изменилось в PowerShell 7, поэтому $? всегда отражает фактическое успешное выполнение последней команды в этих выражениях.

`$^`

Содержит первый токен в последней строке, полученной сеансом.

`$_`

То же, что и $PSItem. Содержит текущий объект в объекте конвейера. Эту переменную можно использовать в командах, выполняющих действие для каждого объекта в конвейере.

Для получения дополнительной информации см. about_PSItem.

`$args`

Содержит массив значений для необъявленных параметров, передаваемых функции, скрипта или скрипта. При создании функции можно объявить параметры с помощью ключевого слова param или добавить разделенный запятыми список параметров в скобках после имени функции.

В действии события переменная $args содержит объекты, представляющие аргументы события обрабатываемого события. Эта переменная заполняется только в блоке Action команды регистрации событий. Значение этой переменной также можно найти в свойстве SourceArgs SourceArgs объекта PSEventArgs, возвращаемого Get-Event.

`$ConsoleFileName`

Содержит путь к файлу консоли (.psc1), который был недавно использован в сеансе. Эта переменная заполняется при запуске PowerShell с параметром PSConsoleFile или при использовании командлета Export-Console для экспорта имен оснасток в файл консоли.

При использовании командлета Export-Console без параметров он автоматически обновляет файл консоли, который был недавно использован в сеансе. Эту автоматическую переменную можно использовать для определения файла для обновления.

`$EnabledExperimentalFeatures`

Содержит список имен экспериментальных функций, которые включены.

`$Error`

Содержит массив объектов ошибок, представляющих самые последние ошибки. Последняя ошибка — первый объект ошибки в массиве $Error[0].

Чтобы предотвратить добавление ошибки в массив $Error, используйте общий параметр ErrorAction со значением Игнорировать. Дополнительные сведения см. в about_CommonParameters.

`$Event`

Содержит объект PSEventArgs, представляющий событие, которое обрабатывается. Эта переменная заполняется только в блоке Action команды регистрации событий, например Register-ObjectEvent. Значение этой переменной совпадает с объектом, который возвращает командлет Get-Event. Вы можете использовать свойства переменной Event , например $Event.TimeGeneratedв блоке скрипта Action .

`$EventArgs`

Содержит объект, представляющий первый аргумент события, производный от EventArgs события, обрабатываемого. Эта переменная заполняется только в блоке Action команды регистрации событий. Значение этой переменной также можно найти в свойстве SourceEventArgs объекта PSEventArgs, возвращаемого Get-Event.

`$EventSubscriber`

Содержит объект PSEventSubscriber, представляющий подписчика события, которое обрабатывается. Эта переменная заполняется только в блоке Action команды регистрации событий. Значение этой переменной совпадает с объектом, который возвращает командлет Get-EventSubscriber.

`$ExecutionContext`

Содержит объект EngineIntrinsics, представляющий контекст выполнения узла PowerShell. Эту переменную можно использовать для поиска объектов выполнения, доступных для командлетов.

`$false`

Содержит ложь. Эту переменную можно использовать для представления False в командах и скриптах вместо "false"строки. Строка может быть интерпретирована как True, если она преобразуется в непустую строку или в целое число, отличное от нуля.

`$foreach`

Содержит перечислитель (а не полученные значения) цикла foreach. Переменная $foreach существует только во время выполнения цикла foreach; он удаляется после завершения цикла.

Перечислители содержат свойства и методы, которые можно использовать для получения значений цикла и изменения текущей итерации цикла. Дополнительные сведения см. в разделе Использование перечислителей.

`$HOME`

Содержит полный путь к домашнему каталогу пользователя. В Windows эта переменная использует значение переменной среды "$Env:USERPROFILE" Windows, обычно C:\Users\<UserName>. В Unix эта переменная использует значение переменной среды HOME.

Важный

Windows может перенаправить расположение профиля пользователя. Это означает, что $HOME может не иметь того же значения, что и "$Env:HOMEDRIVE$Env:HOMEPATH".

`$Host`

Содержит объект, представляющий текущее хост-приложение для PowerShell. Эту переменную можно использовать для представления текущего узла в командах или отображения или изменения свойств узла, таких как $Host.Version или $Host.CurrentCulture, или $Host.UI.RawUI.BackGroundColor = "Red".

Заметка

Параметры цвета в $Host.PrivateData заменены переменной предпочтения $PSStyle. Дополнительные сведения см. в разделе about_ANSI_Terminals.

`$input`

Содержит перечислитель, который перечисляет все входные данные, передаваемые в функцию. Переменная $input доступна только для функций, скриптблоков (которые являются неименованными функциями) и файлов скриптов (которые сохраняются блоки скриптов).

В функции без блока begin, processили end переменная $input перечисляет коллекцию всех входных данных функции.
В блоке begin переменная $input не содержит данных.
В блоке process переменная $input содержит текущий объект в конвейере.
В блоке end переменная $input перечисляет коллекцию всех входных данных функции.

Заметка

Переменную нельзя использовать $input как внутри блока, так process и end в блоке в одной функции или скрипте.

Так как $input является перечислителем, доступ к любому из его свойств приводит к тому, что $input больше недоступен. Вы можете сохранить $input в другой переменной, чтобы повторно использовать свойства $input.

Переменная $input также доступна команде, указанной параметром -Commandpwsh при вызове из командной строки. Следующий пример выполняется из командной оболочки Windows.

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

`$IsCoreCLR`

Содержит $true, если текущий сеанс запущен в среде выполнения .NET Core (CoreCLR). В противном случае содержит $false.

`$IsLinux`

Содержит $true, если текущий сеанс работает в операционной системе Linux. В противном случае содержит $false.

`$IsMacOS`

Содержит $true, если текущий сеанс запущен в операционной системе macOS. В противном случае содержит $false.

`$IsWindows`

Содержит $true, если текущий сеанс работает в операционной системе Windows. В противном случае содержит $false.

`$LASTEXITCODE`

Содержит код выхода последней собственной программы или скрипта PowerShell, запущенного.

Для сценариев PowerShell значение $LASTEXITCODE зависит от того, как был вызван скрипт и использовался ли ключевое слово exit:

Если скрипт использует ключевое слово exit:

$LASTEXITCODE задано значение, указанное ключевым словом exit. Дополнительные сведения см. в разделе about_Language_Keywords.
При вызове скрипта напрямую, как в случае с ./Test.ps1, или с использованием оператора вызова (&), как пример: & ./Test.ps1.

Значение $LASTEXITCODE не изменяется, если только не указано:
- Скрипт вызывает другой сценарий, использующий ключевое слово exit
- Сценарий вызывает встроенную команду
- Сценарий использует ключевое слово exit
При вызове скрипта с pwsh с помощью параметра File$LASTEXITCODE задано значение:
- 1, если скрипт завершился из-за исключения
- Значение, указанное ключевым словом exit, если используется в скрипте
- 0, если скрипт выполнен успешно
При вызове скрипта с pwsh с использованием команды , $LASTEXITCODE задано значение:
- 1, если скрипт завершился из-за исключения или если результат последнего набора команд установил $? на $false
- 0, если скрипт успешно завершен и результат последнего набора команд $?$true

Дополнительные сведения о параметрах файла и команд см. в about_Pwsh.

`$Matches`

Переменная $Matches работает с операторами -match и -notmatch. При отправке скалярных входных данных в оператор -match или -notmatch, и один обнаруживает совпадение, они возвращают логическое значение и заполняют логическое значение и заполняют автоматическую переменную $Matches хэш-таблицей всех сопоставленных строковых значений. Хэш-таблица $Matches также может быть заполнена захватами при использовании регулярных выражений с оператором -match.

Дополнительные сведения о операторе -match см. в about_Comparison_Operators. Дополнительные сведения о регулярных выражениях см. в about_Regular_Expressions.

Переменная $Matches также работает в инструкции switch с параметром -Regex. Он заполняется так же, как и операторы -match и -notmatch. Более подробную информацию об инструкции switch можно найти в about_Switch.

Заметка

В случае заполнения поля $Matches в сеансе оно сохраняет соответствующее значение, пока это значение не будет перезаписано другим совпадением. Если -match используется снова и совпадение не найдено, это не приводит к сбросу $Matches на $null. Ранее соответствующее значение хранится в $Matches до тех пор, пока не будет найдено другое совпадение.

`$MyInvocation`

Содержит сведения о текущей команде, такие как имя, параметры, значения параметров, а также информацию о том, как команда была запущена или вызвана, например, имя сценария, который вызвал текущую команду.

$MyInvocation заполняется только скриптами, функциями и блоками скриптов. Вы можете использовать сведения в объекте System.Management.Automation.InvocationInfo, который возвращается $MyInvocation в текущем скрипте, для идентификации текущей команды, например, по имени функции ($MyInvocation.MyCommand.Name). Это полезно для поиска имени текущего скрипта.

Начиная с PowerShell 3.0, MyInvocation имеет следующие новые свойства.

PSScriptRoot — содержит полный путь к скрипту, который вызвал текущую команду. Значение этого свойства заполняется только в том случае, если вызывающий объект является скриптом.
PSCommandPath — содержит полный путь и имя файла скрипта, вызвавого текущую команду. Значение этого свойства заполняется только в том случае, если вызывающий объект является скриптом.

В отличие от автоматических переменных $PSScriptRoot и $PSCommandPath, свойства PSScriptRoot и PSCommandPath автоматической переменной $MyInvocation содержат сведения о лице, вызвавшем скрипт, или вызывающем скрипте, а не о текущем скрипте.

`$NestedPromptLevel`

Содержит текущий уровень запроса. Значение 0 указывает исходный уровень запроса. Значение увеличивается при входе во вложенный уровень и уменьшается при выходе из него.

Например, PowerShell представляет вложенную командную строку при использовании метода $Host.EnterNestedPrompt. PowerShell также представляет вложенную командную строку при достижении точки останова в отладчике PowerShell.

При вводе вложенного приглашения PowerShell приостанавливает текущую команду, сохраняет контекст выполнения и увеличивает значение переменной $NestedPromptLevel. Чтобы создать дополнительные вложенные командные строки (до 128 уровней) или вернуться в исходную командную строку, выполните команду или введите exit.

Переменная $NestedPromptLevel помогает отслеживать уровень запроса. Можно создать альтернативную командную строку PowerShell, которая включает это значение, чтобы он всегда был видимым.

`$null`

$null — это автоматическая переменная, содержащая null или пустое значение. Эту переменную можно использовать для представления отсутствующего или неопределенного значения в командах и сценариях.

PowerShell обрабатывает $null как объект со значением или заполнителем, поэтому можно использовать $null для представления пустого значения в коллекции значений.

Например, если $null входит в коллекцию, она считается одним из объектов.

$a = "one", $null, "three"
$a.Count

Если переменная $null передана командлету ForEach-Object, он создает значение для $nullтак же, как и для других объектов.

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

Hello one
Hello
Hello three

В результате нельзя использовать $null для обозначения , если для параметранет значения. Значение параметра $null переопределяет значение параметра по умолчанию.

Однако, поскольку PowerShell трактует переменную $null как placeholder, ее можно использовать в скриптах, наподобие следующего, который бы не работал, если бы $null был проигнорирован.

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

Содержит идентификатор процесса (PID) процесса, в котором размещается текущий сеанс PowerShell.

`$PROFILE`

Содержит полный путь к профилю PowerShell для текущего пользователя и текущего ведущего приложения. Эту переменную можно использовать для представления профиля в командах. Например, его можно использовать в команде, чтобы определить, был ли создан профиль:

Test-Path $PROFILE

Вы также можете использовать его в команде для создания профиля:

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

Его можно использовать в команде, чтобы открыть профиль в notepad.exe:

notepad.exe $PROFILE

`$PSBoundParameters`

Содержит словарь параметров, передаваемых скрипту или функции, и их текущим значениям. Эта переменная имеет значение только в области, в которой объявляются параметры, например скрипт или функция. Его можно использовать для отображения или изменения текущих значений параметров или передачи значений параметров другому скрипту или функции.

В этом примере функция Test2 передает $PSBoundParameters функции Test1. $PSBoundParameters отображаются в формате Key и Value.

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`

Содержит объект, представляющий командлет или расширенную функцию, выполняемую.

Свойства и методы объекта в коде командлета или функции можно использовать для реагирования на условия использования. Например, свойство ParameterSetName содержит имя используемого набора параметров, а метод ShouldProcess добавляет WhatIf и подтвердить параметры в командлет динамически.

Дополнительные сведения об автоматической переменной $PSCmdlet см. в about_Functions_CmdletBindingAttribute и about_Functions_Advanced.

`$PSCommandPath`

Содержит полный путь и имя файла выполняемого скрипта. Эта переменная допустима во всех сценариях.

`$PSCulture`

Начиная с PowerShell 7, $PSCulture отражает культуру текущего пространства выполнения PowerShell (сеанс). Если культура изменена в пространстве выполнения PowerShell, значение $PSCulture для этого пространства выполнения обновляется.

Культура определяет формат отображения таких элементов, как числа, валюта и даты, и хранится в объекте System.Globalization.CultureInfo. Используйте Get-Culture для отображения культуры компьютера. $PSCulture содержит значение свойства Name.

`$PSDebugContext`

При отладке эта переменная содержит сведения о среде отладки. В противном случае он содержит значение null. В результате его можно использовать для определения того, имеет ли отладчик элемент управления. При заполнении он содержит объект PsDebugContext с точками останова и свойствами InvocationInfo. Свойство InvocationInfo имеет несколько полезных свойств, включая свойство Location. Свойство Location указывает путь к отлаживаемом скрипту.

`$PSEdition`

Содержит то же значение в $PSVersionTable.PSEdition. Эта переменная доступна для использования в файлах манифеста модуля, в то время как $PSVersionTable нет.

`$PSHOME`

Содержит полный путь к каталогу установки для PowerShell, обычно, C:\Program Files\PowerShell\7 в системах Windows. Эту переменную можно использовать в путях файлов PowerShell. Например, следующая команда выполняет поиск концептуальных разделов справки по слову справке:

Select-String -Pattern Help -Path $PSHOME\en-US\*.txt

`$PSItem`

То же, что и $_. Содержит текущий объект в объекте конвейера. Эту переменную можно использовать в командах, выполняющих действие для каждого объекта в конвейере.

Для получения дополнительной информации см. about_PSItem.

`$PSScriptRoot`

Содержит полный путь родительского каталога скрипта.

В PowerShell 2.0 эта переменная действительна только в модулях скриптов (.psm1). Начиная с PowerShell 3.0, он действителен во всех сценариях.

`$PSSenderInfo`

Содержит сведения о пользователе, который запустил PSSession, включая удостоверение пользователя и часовой пояс исходного компьютера. Эта переменная доступна только в PSSessions.

Переменная $PSSenderInfo включает настраиваемое пользователем свойство, ApplicationArguments, которое по умолчанию содержит только $PSVersionTable из исходного сеанса. Чтобы добавить данные в свойство ApplicationArguments, используйте параметр ApplicationArguments командлета New-PSSessionOption.

Важный

Так как это свойство содержит данные, явно предоставленные клиентом, с помощью этого решения безопасности злоумышленники могут обойти элементы управления авторизацией. Никогда не используйте эти данные для решений доверия. Проверьте все входные данные пользователя при использовании для другой логики приложения.

`$PSUICulture`

Содержит имя культуры пользовательского интерфейса, настроенной в операционной системе. Культура пользовательского интерфейса определяет, какие тексты используются для элементов интерфейса, таких как меню и сообщения. Это значение свойства системы System.Globalization.CultureInfo.CurrentUICulture.Name. Чтобы получить объект System.Globalization.CultureInfo для системы, используйте командлет Get-UICulture.

`$PSVersionTable`

Содержит хэш-таблицу только для чтения, которая отображает сведения о версии PowerShell, работающей в текущем сеансе. Таблица содержит следующие элементы:

PSVersion — номер версии PowerShell
PSEdition Это свойство имеет значение 'Desktop' для PowerShell 4 и более старых, а также PowerShell 5.1 на полнофункциональных версиях Windows. Это свойство имеет значение Core для PowerShell 6 и более поздних версий, а также Windows PowerShell 5.1 для выпусков с уменьшенным объемом памяти, таких как Windows Nano Server или Windows IoT.
GitCommitId — идентификатор фиксации исходных файлов в GitHub
ОС — описание операционной системы, в которую работает PowerShell.
платформа — платформа, на которую работает операционная система. Значение в Linux и macOS — Unix. См. $IsMacOS и $IsLinux.
PSCompatibleVersions — версии PowerShell, совместимые с текущей версией.
PSRemotingProtocolVersion — версия протокола удаленного управления PowerShell.
SerializationVersion — версия метода сериализации
WSManStackVersion — номер версии стека WS-Management

`$PWD`

Содержит объект пути, представляющий полный путь к текущему расположению каталога для текущего пространства выполнения PowerShell.

Заметка

PowerShell поддерживает несколько пространств выполнения для каждого процесса. Каждое пространство выполнения имеет собственный текущий каталог. Это не то же самое, что и текущий каталог процесса: [System.Environment]::CurrentDirectory.

`$Sender`

Содержит объект, создающий это событие. Эта переменная заполняется только в блоке действий команды регистрации событий. Значение этой переменной также можно найти в свойстве Sender объекта PSEventArgs, возвращаемого Get-Event.

`$ShellId`

Содержит идентификатор текущей оболочки.

`$StackTrace`

Содержит трассировку стека для наиболее последней ошибки.

`$switch`

Содержит перечислитель, а не полученные значения инструкции switch. Переменная $switch существует только во время выполнения инструкции switch; он удаляется при завершении выполнения инструкции switch. Дополнительные сведения см. в about_Switch.

`$this`

Переменная $this используется в сценариях, расширяющих классы для ссылки на экземпляр самого класса.

Расширяемая система типов PowerShell (ETS) позволяет добавлять свойства в классы с помощью скриптов. В блоке скрипта, определяющем свойство скрипта или метод скрипта, $this переменная ссылается на экземпляр объекта класса, который расширяется. Например, PowerShell использует ETS для добавления свойства BaseName в класс 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};}

Дополнительные сведения см. в разделе about_Types.ps1xml.

В классе PowerShell переменная $this ссылается на объект экземпляра самого класса, разрешая доступ к свойствам и методам, определенным в классе. Дополнительные сведения см. в about_Classes.

Переменная $this также используется классами событий .NET, которые принимают скрипты в качестве делегатов обработчика событий. В этом сценарии $this представляет объект, отправляющий событие, известный как отправитель событий.

`$true`

Содержит True. Эту переменную можно использовать для представления True в командах и сценариях.

Использование перечислителей

Переменные $input, $foreachи $switch являются всеми перечислителями, используемыми для итерации значений, обработанных их содержащим блоком кода.

Перечислитель содержит свойства и методы, которые можно использовать для продвижения или сброса итерации или извлечения значений итерации. Непосредственное манипулирование перечислителями не считается наилучшей практикой.

В циклах ключевые слова управления потоками break и continue следует предпочесть.
В функциях, которые принимают входные данные конвейера, рекомендуется использовать параметры с атрибутами ValueFromPipeline или ValueFromPipelineByPropertyName.

Дополнительные сведения см. в about_Functions_Advanced_Parameters.

Перейти к следующему

Метод MoveNext перемещает перечислитель к следующему элементу коллекции. MoveNext возвращает True, если перечислитель был успешно перемещен вперед, False, если перечислитель прошел конец коллекции.

Заметка

Значение логического , возвращаемое MoveNext, отправляется в выходной поток. Вы можете отключить выходные данные, преобразовав его в [void] или направив его в Out-Null.

$input.MoveNext() | Out-Null

[void]$input.MoveNext()

Reset

Метод Reset задает перечислителю начальную позицию, которая находится перед первым элементом в коллекции.

Current

Свойство Current получает элемент в коллекции или в конвейере на текущей позиции перечислителя.

Свойство Current продолжает возвращать то же свойство до вызова MoveNext.

Примеры

Пример 1. Использование переменной $input

В следующем примере доступ к переменной $input очищает переменную до следующего выполнения блока процесса. Использование метода Reset сбрасывает переменную $input до текущего значения конвейера.

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

Блок процесса автоматически обновляет переменную $input, даже если на неё не обращаются.

$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

Пример 2. Использование $input за пределами блока процесса

Вне блока процесса переменная $input представляет все значения, которые передаются в функцию.

Доступ к переменной $input очищает все значения.
Метод Reset сбрасывает всю коллекцию.
Свойство Current никогда не заполняется.
Метод MoveNext возвращает значение false, так как коллекция не может быть расширена.
- Вызов MoveNext очищает переменную $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:

Пример 3: Использование свойства $input.Current

Используя свойство Current, текущее значение конвейера можно получить несколько раз, не используя метод Reset. Блок процесса не вызывает метод MoveNext автоматически.

Свойство Current никогда не заполняется, если вы явно не вызываете MoveNext. К свойству Current можно получить доступ несколько раз внутри блока процесса, не очищая его значение.

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

Пример 4. Использование переменной $foreach

В отличие от переменной $input, переменная $foreach всегда представляет все элементы коллекции при доступе напрямую. Используйте свойство Current для доступа к текущему элементу коллекции, а также методы Reset и MoveNext, чтобы изменить его значение.

Заметка

Каждая итерация цикла foreach автоматически вызывает метод MoveNext.

Следующий цикл выполняется только дважды. Во второй итерации коллекция перемещается в третий элемент до завершения итерации. После второй итерации теперь нет больше значений для итерации, и цикл завершается.

Свойство MoveNext не влияет на переменную, выбранную для итерации по коллекции ($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 hasn't changed: $num"
    }
}

Iteration: 0
        Num: one
        Current: one
Iteration: 1
        Num: two
        Current: two
Before MoveNext (Current): two
After MoveNext (Current): three
Num hasn't changed: two

Использование метода Reset сбрасывает данный элемент в коллекции. В следующем примере выполняется цикл по первым двум элементам дважды, так как вызывается метод Reset. После первых двух циклов оператор if завершается сбоем, и цикл выполняет итерацию через все три элемента нормально.

Важный

Это может привести к бесконечному циклу.

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

    if ($num -eq "two" -and $stopLoop -lt 2)
    {
        $foreach.Reset()
        ("`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

Пример 5. Использование переменной $switch

Переменная $switch имеет те же правила, что и переменная $foreach. В следующем примере показаны все понятия перечислителя.

Заметка

Обратите внимание, что случай NotEvaluated никогда не выполняется, даже если после метода break нет инструкции .

$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

См. также

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-02-10

Поделиться через

о_автоматических_переменных

Краткое описание

Длинное описание

$$

$?

$^

$_

$args

$ConsoleFileName

$EnabledExperimentalFeatures

$Error

$Event

$EventArgs

$EventSubscriber

$ExecutionContext

$false

$foreach

$HOME

$Host

$input

$IsCoreCLR

$IsLinux

$IsMacOS

$IsWindows

$LASTEXITCODE

$Matches

$MyInvocation

$NestedPromptLevel

$null

$PID

$PROFILE

$PSBoundParameters

$PSCmdlet

$PSCommandPath

$PSCulture

$PSDebugContext

$PSEdition

$PSHOME

$PSItem

$PSScriptRoot

$PSSenderInfo

$PSUICulture

$PSVersionTable

$PWD

$Sender

$ShellId

$StackTrace

$switch

$this

$true

Использование перечислителей

Перейти к следующему

Reset

Current

Примеры

Пример 1. Использование переменной $input

Пример 2. Использование $input за пределами блока процесса

Пример 3: Использование свойства $input.Current

Пример 4. Использование переменной $foreach

Пример 5. Использование переменной $switch

См. также

Обратная связь

Дополнительные ресурсы

`$$`

`$?`

`$^`

`$_`

`$args`

`$ConsoleFileName`

`$EnabledExperimentalFeatures`

`$Error`

`$Event`

`$EventArgs`

`$EventSubscriber`

`$ExecutionContext`

`$false`

`$foreach`

`$HOME`

`$Host`

`$input`

`$IsCoreCLR`

`$IsLinux`

`$IsMacOS`

`$IsWindows`

`$LASTEXITCODE`

`$Matches`

`$MyInvocation`

`$NestedPromptLevel`

`$null`

`$PID`

`$PROFILE`

`$PSBoundParameters`

`$PSCmdlet`

`$PSCommandPath`

`$PSCulture`

`$PSDebugContext`

`$PSEdition`

`$PSHOME`

`$PSItem`

`$PSScriptRoot`

`$PSSenderInfo`

`$PSUICulture`

`$PSVersionTable`

`$PWD`

`$Sender`

`$ShellId`

`$StackTrace`

`$switch`

`$this`

`$true`