about_Automatic_Variables

Назначение: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0

Вставьте сюда введение.

РАЗДЕЛ

about_Automatic_Variables

КРАТКОЕ ОПИСАНИЕ

В этом разделе описываются переменные, хранящие сведения о состоянии для Windows PowerShell. Эти переменные создаются и обслуживаются Windows PowerShell.

ПОДРОБНОЕ ОПИСАНИЕ

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

$$

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

$?

Содержит состояние выполнения последней операции. Она содержит значение TRUE, если последняя операция выполнена успешно, и значение FALSE при ошибке.

$^

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

$_

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

$ARGS

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

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

$CONSOLEFILENAME

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

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

$ERROR

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

Чтобы предотвратить добавление ошибки в массив $Error, используйте общий параметр ErrorAction со значением Ignore. Дополнительные сведения см. в разделе about_CommonParameters (https://go.microsoft.com/fwlink/?LinkId=113216).

$EVENT

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

$EVENTARGS

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

$EVENTSUBSCRIBER

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

$EXECUTIONCONTEXT

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

$FALSE

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

$FOREACH

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

$HOME

Содержит полный путь к домашнему каталогу пользователя. Эта переменная — эквивалент переменной среды %homedrive%%homepath%, обычно C:\Users\<имя_пользователя>.

$HOST

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

$INPUT

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

$LASTEXITCODE

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

$MATCHES

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

$MYINVOCATION

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

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

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

       -- PSScriptRoot: Contains the full path to the script that invoked the
          current command. The value of this property is populated only when
          the caller is a script.  

       -- PSCommandPath: Contains the full path and file name of the script that
          invoked the current command. The value of this property is populated
          only when the caller is a script.  

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

$NESTEDPROMPTLEVEL

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

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

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

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

$NULL

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

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

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

           C:\PS> $a = ".dir", $null, ".pdf"
           C:\PS> $a.count
           3

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

           PS C:\ps-test> ".dir", "$null, ".pdf" | Foreach {"Hello"}
           Hello
           Hello
           Hello

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

Но поскольку Windows 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

$OFS

$OFS — это особая переменная, содержащая строку, которую требуется использовать в качестве разделителя полей выходных данных. Используйте эту переменную при преобразовании массива в строку. По умолчанию значение $OFS равно " ", но его можно изменить в текущем сеансе, введя $OFS="<значение>". Если вы ожидаете значение по умолчанию " " в выходных данных скрипта, модуля или конфигурации, будьте внимательны и не меняйте значение $OFS по умолчанию в других местах в коде.

Примеры:

PS> $a="1","2","3","4"
           PS> $a
           1
           2
           3
           4

PS> [string]$a
           1 2 3 4
           PS> $OFS="";[string]$a
           1234

PS> $OFS=",";[string]$a
           1,2,3,4

PS> $OFS="--PowerShellRocks--";[string]$a
           1--PowerShellRocks--2--PowerShellRocks--3--PowerShellRocks--4
           PS> $OFS="`n`n";[string]$a
           1

           2

           3

           4

$PID

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

$PROFILE

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

           test-path $profile

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

           new-item -type file -path $pshome -force

Эту переменную также можно использовать в команде, чтобы открыть профиль в Блокноте:

           notepad $profile

$PSBOUNDPARAMETERS

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

Например:

         function Test {
            param($a, $b)
            
            # Display the parameters in dictionary format.
            $PSBoundParameters
             
            # Call the Test1 function with $a and $b.
            test1 @PSBoundParameters
         }

$PSCMDLET

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

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

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

$PSCOMMANDPATH

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

$PSCULTURE

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

$PSDEBUGCONTEXT

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

$PSHOME

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

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

$PSITEM

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

$PSSCRIPTROOT

Содержит каталог, из которого запускается сценарий.

В версии Windows PowerShell 2.0 эта переменная допустима только в модулях сценариев (PSM1). Начиная с версии Windows 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

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

    CLRVersion:            The version of the common language runtime (CLR)

    BuildVersion:          The build number of the current version

        PSVersion:             The Windows PowerShell version number

          WSManStackVersion:     The version number of the WS-Management stack

    PSCompatibleVersions:  Versions of Windows PowerShell that are
                                 compatible with the current version

          SerializationVersion   The version of the serialization method

          PSRemotingProtocolVersion
                                 The version of the Windows PowerShell remote
                                 management protocol

$PWD

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

$REPORTERRORSHOWEXCEPTIONCLASS

$REPORTERRORSHOWINNEREXCEPTION
$REPORTERRORSHOWSOURCE
$REPORTERRORSHOWSTACKTRACE

Переменные "ReportErrorShow" определены в Windows PowerShell, но они не реализованы. Командлет Get-Variable возвращает их, но они не содержат допустимые данные.

$SENDER

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

$SHELLID

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

$STACKTRACE

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

$THIS

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

$TRUE

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

СМ. ТАКЖЕ

about_Hash_Tables

about_Preference_Variables

about_Variables