about_Automatic_Variables
Aplica-se a: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0, Windows PowerShell 5.0
Insira a introdução aqui.
TÓPICO
about_Automatic_Variables
DESCRIÇÃO BREVE
Descreve as variáveis que armazenam informações de estado do Windows PowerShell. Essas variáveis são criadas e mantidas pelo Windows PowerShell.
DESCRIÇÃO LONGA
A seguir, há uma lista das variáveis automáticas do Windows PowerShell:
$$
Contém o último token da última linha recebida pela sessão.
$?
Contém o status de execução da última operação. Apresenta TRUE se a última operação foi bem-sucedida e FALSE se ela falhar.
$^
Contém o primeiro token da última linha recebida pela sessão.
$_
Igual a $PSItem. Contém o objeto atual do objeto de pipeline. Você pode usar essa variável em comandos que executam uma ação em cada objeto ou em objetos selecionados de um pipeline.
$ARGS
Contém uma matriz dos parâmetros não declarados e/ou dos valores de parâmetros que são transferidos a uma função, script ou bloco de script. Quando você cria uma função, você pode declarar os parâmetros usando a palavra-chave param ou adicionando uma lista separada por vírgulas de parâmetros entre parênteses depois do nome da função.
Em uma ação de evento, a variável $Args contém objetos que representam os argumentos do evento que está sendo processado. Essa variável somente é preenchida dentro do bloco Action de um comando de registro de evento. O valor dessa variável também pode ser encontrado na propriedade SourceArgs do objeto PSEventArgs (System.Management.Automation.PSEventArgs) que o Get-Event retorna.
$CONSOLEFILENAME
Contém o caminho do arquivo de console (.psc1) que foi usado mais recentemente na sessão. Essa variável é preenchida quando você iniciar o Windows PowerShell com o parâmetro PSConsoleFile ou quando usar o cmdlet Export-Console para exportar os nomes de snap-in para um arquivo de console.
Quando você usa o cmdlet Export-Console sem parâmetros, ele atualiza automaticamente o arquivo de console que foi usado mais recentemente na sessão. Você pode usar essa variável automática para determinar qual arquivo será atualizado.
$ERROR
Contém uma matriz de objetos de erro que representam os erros mais recentes. O erro mais recente é o primeiro objeto de erro na matriz ($Error[0]).
Para impedir que um erro seja adicionado à matriz $Error, use o parâmetro comum ErrorAction com um valor de Ignore. Para obter mais informações, consulte about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).
$EVENT
Contém um objeto PSEventArgs que representa o evento que está sendo processado. Essa variável somente é preenchida somente dentro do bloco Action de um comando de registro de eventos, como Register-ObjectEvent. O valor dessa variável é o mesmo objeto que o cmdlet Get-Event retorna. Portanto, você pode usar as propriedades da variável $Event, como $Event.TimeGenerated, em um bloco de script Action.
$EVENTARGS
Contém um objeto que representa o primeiro argumento de evento derivado do EventArgs do evento que está sendo processado. Essa variável somente é preenchida dentro do bloco Action de um comando de registro de evento. O valor dessa variável também pode ser encontrado na propriedade SourceEventArgs do objeto PSEventArgs (System.Management.Automation.PSEventArgs) que o Get-Event retorna.
$EVENTSUBSCRIBER
Contém um objeto PSEventSubscriber que representa o assinante do evento que está sendo processado. Essa variável somente é preenchida dentro do bloco Action de um comando de registro de evento. O valor dessa variável é o mesmo objeto que o cmdlet Get-EventSubscriber retorna.
$EXECUTIONCONTEXT
Contém um objeto EngineIntrinsics que representa o contexto de execução do host do Windows PowerShell. Você pode usar essa variável para localizar os objetos de execução que estão disponíveis para os cmdlets.
$FALSE
Contém FALSE. Você pode usar essa variável para representar FALSE em comandos e scripts, em vez de usar a cadeia de caracteres "false". A cadeia de caracteres pode ser interpretada como TRUE se for convertida para uma cadeia de caracteres não vazia ou para um número inteiro diferente de zero.
$FOREACH
Contém o enumerador (e não os valores resultantes) de um loop ForEach. Você pode usar as propriedades e métodos dos enumeradores no valor da variável $ForEach. Essa variável somente existe enquanto o loop ForEach estiver sendo executado; ela é excluída depois que o loop for concluído. Para obter informações detalhadas, consulte about_ForEach.
$HOME
Contém o caminho completo do diretório base do usuário. Essa variável é o equivalente das variáveis de ambiente %homedrive%%homepath%, geralmente, C:\Users\<nome de usuário>.
$HOST
Obtém um objeto que representa o aplicativo host atual do Windows PowerShell. Você pode usar essa variável para representar o host atual nos comandos ou para exibir ou alterar as propriedades do host, como $Host.version ou $Host.CurrentCulture, ou $host.ui.rawui.setbackgroundcolor("Red").
$INPUT
Contém um enumerador que enumera todas as entradas que são transmitidas a uma função. A variável $input está disponível somente para funções e blocos de script (que são funções não nomeadas). No bloco Process de uma função, a variável $input enumera o objeto que está no pipeline no momento. Quando o bloco Process for concluído, não haverá nenhum objeto no pipeline e a variável $input enumerará uma coleção vazia. Se a função não tiver um bloco Process, no blocl End, a variável $input enumerará a coleção de todas as entradas da função.
$LASTEXITCODE
Contém o código de saída do último programa baseado no Windows que foi executado.
$MATCHES
A variável $Matches funciona com os operadores -match e -notmatch. Quando você envia uma entrada escalar ao operador -match ou -notmatch e um deles detectar uma correspondência, eles retornam um valor booliano e preenchem a variável automática $Matches com uma tabela de hash de quaisquer valores de cadeia de caracteres que foram correspondidos. Para obter mais informações sobre o operador -match, consulte about_comparison_operators.
$MYINVOCATION
Contém informações sobre o comando atual, como o nome, parâmetros, valores de parâmetro, e informações sobre como o comando foi iniciado, chamado ou "acionado", como o nome do script que chamou o comando atual.
$MyInvocation é preenchida somente para scripts, função e blocos de script. Você pode usar as informações do objeto System.Management.Automation.InvocationInfo que $MyInvocation retorna no script atual, como o caminho e o nome de arquivo do script ($MyInvocation.MyCommand.Path) ou o nome de uma função ($MyInvocation.MyCommand.Name) para identificar o comando atual. Isso é particularmente útil para localizar o nome do script atual.
A partir do Windows PowerShell 3.0, $MyInvocation tem as novas propriedades a seguir.
-- 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.
Ao contrário das variáveis automáticas $PSScriptRoot e $PSCommandPath, as propriedades PSScriptRoot e PSCommandPath da variável automática $MyInvocation contêm informações sobre o chamador ou o script de chamada, e não o script atual.
$NESTEDPROMPTLEVEL
Contém o nível atual do aviso. Um valor de 0 indica o nível de aviso original. O valor é incrementado quando você insere um nível aninhado e diminuído quando você sair dele.
Por exemplo, o Windows PowerShell apresenta um prompt de comando aninhado quando você usa o método $Host.EnterNestedPrompt. O Windows PowerShell também apresenta um prompt de comando aninhado quando você atinge um ponto de interrupção no depurador do Windows PowerShell.
Quando você insere um prompt aninhado, o Windows PowerShell pausa o comando atual, salva o contexto de execução e incrementa o valor da variável $NestedPromptLevel. Para criar prompts de comando aninhados adicionais (até 128 níveis) ou para retornar ao prompt de comando original, conclua o comando ou digite "exit".
A variável $NestedPromptLevel ajuda a controlar o nível de aviso. Você pode criar um prompt de comando alternativo do Windows PowerShell que inclua esse valor para que ele esteja sempre visível.
$NULL
$null é uma variável automática que contém um valor NULL ou vazio. Você pode usar essa variável para representar um valor ausente ou indefinido em comandos e scripts.
O Windows PowerShell trata $null como um objeto com um valor, ou seja, como um espaço reservado explícito, para que você possa usar $null para representar um valor vazio em uma série de valores.
Por exemplo, quando $null é incluído em uma coleção, ele será contado como um dos objetos.
C:\PS> $a = ".dir", $null, ".pdf"
C:\PS> $a.count
3
Se você redirecionar a variável $null para o cmdlet ForEach-Object, ela gerará um valor para $null, assim como faz para outros objetos.
PS C:\ps-test> ".dir", "$null, ".pdf" | Foreach {"Hello"}
Hello
Hello
Hello
Como resultado, você não pode usar $null para dizer "nenhum valor de parâmetro". Um valor de parâmetro $null substitui o valor de parâmetro padrão.
No entanto, como o Windows PowerShell trata a variável $null como um espaço reservado, você pode usá-la em scripts como o seguinte, o que não funcionaria se $null fosse ignorada.
$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 é uma variável especial que armazena uma cadeia de caracteres que você deseja usar como um separador de campos de saída. Use essa variável quando estiver convertendo uma matriz em uma cadeia de caracteres. Por padrão, o valor de $OFS é " ", mas você pode alterar o valor de $OFS em sua sessão digitando $OFS = "<valor>". Se estiver esperando o valor padrão de " " em seu script, módulo ou saída de configuração, verifique se o valor padrão $OFS não foi alterado em outro lugar de seu código.
Exemplos:
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
Contém a PID (identificador do processo) que está hospedando a sessão atual do Windows PowerShell.
$PROFILE
Contém o caminho completo do perfil do Windows PowerShell para o usuário atual e o aplicativo host atual. Você pode usar essa variável para representar o perfil em comandos. Por exemplo, você pode usá-la em um comando para determinar se um perfil foi criado:
test-path $profile
Ou pode usá-la em um comando para criar um perfil:
new-item -type file -path $pshome -force
Você também pode usá-la em um comando para abrir o perfil no bloco de notas:
notepad $profile
$PSBOUNDPARAMETERS
Contém um dicionário dos parâmetros que são transferidos para um script ou função e seus valores atuais. Essa variável tem um valor somente em um escopo em que os parâmetros são declarados, como um script ou uma função. Você pode usá-la para exibir ou alterar os valores atuais dos parâmetros ou transferir valores de parâmetros para outra função ou script.
Por exemplo:
function Test {
param($a, $b)
# Display the parameters in dictionary format.
$PSBoundParameters
# Call the Test1 function with $a and $b.
test1 @PSBoundParameters
}
$PSCMDLET
Contém um objeto que representa o cmdlet ou função avançada que está sendo executada.
Você pode usar as propriedades e métodos do objeto em seu código de cmdlet ou função para responder às condições de uso. Por exemplo, a propriedade ParameterSetName contém o nome do conjunto de parâmetro que está sendo usado, e o método ShouldProcess adiciona dinamicamente os parâmetros WhatIf and Confirm ao cmdlet.
Para obter mais informações sobre a variável automática $PSCmdlet, consulte about_Functions_Advanced.
$PSCOMMANDPATH
Contém o nome de arquivo e o caminho completo do script que está sendo executado. Essa variável é válida em todos os scripts.
$PSCULTURE
Contém o nome da cultura atualmente em uso no sistema operacional. A cultura determina o formato de exibição de itens como números, moedas e datas. Esse é o valor da propriedade System.Globalization.CultureInfo.CurrentCulture.Name do sistema. Para obter o objeto System.Globalization.CultureInfo para o sistema, use o cmdlet Get-Culture.
$PSDEBUGCONTEXT
Durante a depuração, essa variável contém informações sobre o ambiente de depuração. Caso contrário, ela contém um valor NULL. Como resultado, você pode usá-la para indicar se o depurador tem controle. Quando preenchida, ela contém um objeto PsDebugContext que tem propriedades Breakpoints e InvocationInfo. A propriedade InvocationInfo tem diversas propriedades úteis, incluindo a propriedade Location. A propriedade Location indica o caminho do script que está sendo depurado.
$PSHOME
Contém o caminho completo do diretório de instalação do Windows PowerShell, geralmente, %windir%\System32\WindowsPowerShell\v1.0. Você pode usar essa variável nos caminhos dos arquivos do Windows PowerShell. Por exemplo, o comando a seguir pesquisa os tópicos de Ajuda conceituais para a palavra "variável":
Select-String -Pattern Variable -Path $pshome\*.txt
$PSITEM
Igual a $_. Contém o objeto atual do objeto de pipeline. Você pode usar essa variável em comandos que executam uma ação em cada objeto ou em objetos selecionados de um pipeline.
$PSSCRIPTROOT
Contém o diretório no qual um script é executado.
No Windows PowerShell 2.0, essa variável só é válida em módulos de script (.psm1). A partir do Windows PowerShell 3.0, ela é válida em todos os scripts.
$PSSENDERINFO
Contém informações sobre o usuário que iniciou a PSSession, incluindo a identidade do usuário e o fuso horário do computador de origem. Essa variável só está disponível na PSSessions.
A variável $PSSenderInfo inclui uma propriedade configurável pelo usuário, ApplicationArguments, que, por padrão, contém apenas a $PSVersionTable da sessão de origem. Para adicionar dados à propriedade ApplicationArguments, use o parâmetro ApplicationArguments do cmdlet New-PSSessionOption.
$PSUICULTURE
Contém o nome da cultura da UI (interface do usuário) que está sendo usada no momento no sistema operacional. A cultura da interface do usuário determina quais cadeias de caracteres de texto são usadas para elementos de interface do usuário, como menus e mensagens. Esse é o valor da propriedade System.Globalization.CultureInfo.CurrentUICulture.Name do sistema. Para obter o objeto System.Globalization.CultureInfo para o sistema, use o cmdlet Get-UICulture.
$PSVERSIONTABLE
Contém uma tabela de hash somente leitura que exibe detalhes sobre a versão do Windows PowerShell que está em execução na sessão atual. A tabela inclui os seguintes campos:
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
Contém um objeto de caminho que representa o caminho completo do diretório atual.
$REPORTERRORSHOWEXCEPTIONCLASS
$REPORTERRORSHOWINNEREXCEPTION
$REPORTERRORSHOWSOURCE
$REPORTERRORSHOWSTACKTRACE
As variáveis "ReportErrorShow" são definidas no Windows PowerShell, mas não são implementadas. O Get-Variable as utiliza, mas elas não contêm dados válidos.
$SENDER
Contém o objeto que gerou esse evento. Essa variável somente é preenchida dentro do bloco Action de um comando de registro de evento. O valor dessa variável também pode ser encontrado na propriedade Sender do objeto PSEventArgs (System.Management.Automation.PSEventArgs) que o Get-Event retorna.
$SHELLID
Contém o identificador do shell atual.
$STACKTRACE
Contém um rastreamento de pilha do erro mais recente.
$THIS
Em um bloco de script que define uma propriedade de script ou método de script, a variável $This se refere ao objeto que está sendo estendido.
$TRUE
Contém TRUE. Você pode usar essa variável para representar TRUE em comandos e scripts.
CONSULTE TAMBÉM
about_Hash_Tables
about_Preference_Variables
about_Variables