Сведения об автоматических переменных

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

Описывает переменные, которые хранят сведения о состоянии для PowerShell. Эти переменные создаются и поддерживаются с помощью PowerShell.

Подробное описание

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

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

$$

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

$?

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

$^

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

$_

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

$args

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

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

$ConsoleFileName

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

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

$Error

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

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

$Event

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

$EventArgs

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

$EventSubscriber

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

$ExecutionContext

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

$false

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

$foreach

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

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

$HOME

Содержит полный путь к домашнему каталогу пользователя. Эта переменная является эквивалентом переменных "$env:homedrive$env:homepath" среды Windows, как правило C:\Users\<UserName>, .

$Host

Содержит объект , представляющий текущее ведущее приложение для PowerShell. Эту переменную можно использовать для представления текущего узла в командах, а также для отображения или изменения свойств узла, таких как $Host.version или $Host.CurrentCulture, или $host.ui.rawui.setbackgroundcolor("Red").

$input

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

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

• В блоке Begin$input переменная не содержит данных.

• В блоке Process$input переменная содержит объект , который в настоящее время находится в конвейере.

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

  Примечание

  Нельзя использовать $input переменную внутри блока Process и End в одном блоке функции или скрипта.

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

$LastExitCode

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

$Matches

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

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

$MyInvocation

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

$MyInvocation заполняется только для скриптов, функций и блоков скриптов. Для идентификации текущей команды можно использовать сведения в объекте System.Management.Automation.InvocationInfo , возвращаемом $MyInvocation в текущем скрипте, например путь и имя файла скрипта ($MyInvocation.MyCommand.Path) или имя функции ($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 — это автоматическая переменная, содержащая пустое или пустое значение. Эту переменную можно использовать для представления отсутствующего или неопределенного значения в командах и скриптах.

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

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

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

3

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

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

Hello one
Hello
Hello three

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

Тем не менее, так как PowerShell рассматривает $null переменную как заполнитель, ее можно использовать в сценариях, подобных приведенному ниже, которые не будут работать, если $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 в формате Ключ и Значение.

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 и Confirm в командлет.

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

$PSCommandPath

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

$PSCulture

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

$PSDebugContext

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

$PSHOME

Содержит полный путь к каталогу установки Для PowerShell, как правило, $env:windir\System32\PowerShell\v1.0 в системах Windows. Эту переменную можно использовать в путях к файлам PowerShell. Например, следующая команда выполняет поиск слова переменная в концептуальных разделах справки:

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

$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, работающей в текущем сеансе. Таблица содержит следующие элементы:

Свойство	Описание
BuildVersion	Номер сборки текущей версии
CLRVersion	Версия среды CLR
	(СРЕДА CLR)
PSCompatibleVersions	Совместимые версии PowerShell
	с текущей версией
PSRemotingProtocolVersion	Версия удаленного репозитория PowerShell
	протокол управления.
PSVersion	Номер версии PowerShell
SerializationVersion	Версия метода сериализации
WSManStackVersion	Номер версии стека WS-Management

$PWD

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

$Sender

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

$ShellId

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

$StackTrace

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

$switch

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

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

$this

В блоке скрипта, определяющем свойство скрипта или метод скрипта $this , переменная ссылается на расширяемый объект.

$true

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

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

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

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

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

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

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

MoveNext

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

Примечание

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

$input.MoveNext() | Out-Null

[void]$input.MoveNext()

Reset

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

Текущие

Свойство 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 можно получить доступ к текущему значению конвейера несколько раз без использования метода 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 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 сбрасывает текущий элемент в коллекции. В следующем примере два первых элемента дважды выполняется цикл, так как вызывается метод 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() | 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

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

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

Примечание

Обратите внимание, что случай NotEvaluated никогда не выполняется, даже если после метода MoveNext нет 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

См. также раздел

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_Advanced_Parameters

about_Functions_OutputTypeAttribute

about_Functions_CmdletBindingAttribute

about_Hash_Tables

about_Preference_Variables

about_Splatting

about_Variables