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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Переменная $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 содержат сведения о вызывающем объекте или скрипте, а не текущем скрипте.

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

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

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

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

$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 по умолчанию в других местах в коде.

Примеры:

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), в котором размещается текущий сеанс Windows PowerShell.

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

           test-path $profile

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

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

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

           notepad $profile

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

Например:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Содержит доступную только для чтения хэш-таблицу, в которой отображаются сведения о версии 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

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

$REPORTERRORSHOWINNEREXCEPTION
$REPORTERRORSHOWSOURCE
$REPORTERRORSHOWSTACKTRACE

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

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

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

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

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

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

about_Hash_Tables

about_Preference_Variables

about_Variables