sobre_Variáveis_Automáticas

Breve descrição

Descreve variáveis que armazenam informações de estado para e são criadas e mantidas pelo PowerShell.

Descrição longa

Conceitualmente, a maioria dessas variáveis é considerada apenas de leitura. Mesmo que eles possam ser gravados, para compatibilidade com versões anteriores eles não devem ser gravados.

Aqui está uma lista das variáveis automáticas no 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

`$$`

Contém o último token na última linha recebida pela sessão.

`$?`

Contém o status de execução do último comando. Contém True se o último comando foi bem-sucedido e False se não foi. Os erros de análise não resultam em execução, portanto, não afetam o valor de $?.

Para cmdlets e funções avançadas que são executadas em vários estágios em um pipeline, por exemplo, em blocos process e end, chamar this.WriteError() ou $PSCmdlet.WriteError(), respectivamente, em qualquer ponto define $? para False, assim como this.ThrowTerminatingError() e $PSCmdlet.ThrowTerminatingError().

O cmdlet Write-Error sempre define $? como False imediatamente após sua execução, mas não definirá $?False para uma função que o chame:

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

Para este último efeito, deve ser utilizado $PSCmdlet.WriteError().

Para comandos nativos (executáveis), $? é definido como True quando $LASTEXITCODE é 0 e definido como False quando $LASTEXITCODE é qualquer outro valor.

Observação

Até ao PowerShell 7, encapsular uma instrução entre parênteses (...), sintaxe de sub-expressão $(...)ou uma expressão de matriz @(...) redefinia sempre $? para True. Por exemplo, (Write-Error) mostra $? como True. Esse comportamento foi alterado no PowerShell 7, para que $? sempre reflita o sucesso real do último comando executado nessas expressões.

`$^`

Contém o primeiro token na última linha recebida pela sessão.

`$_`

O mesmo que $PSItem. Contém o objeto atual no objeto de pipeline. Você pode usar essa variável em comandos que executam uma ação em cada objeto em um pipeline.

Para obter mais informações, consulte about_PSItem.

`$args`

Contém um array de valores para parâmetros não declarados que são passados para uma função, script ou bloco de script. Ao criar uma função, você pode declarar os parâmetros com a palavra-chave param ou adicionando uma lista separada por vírgulas de parâmetros entre parênteses após o nome da função.

Em uma ação de evento, a variável $args contém objetos que representam os argumentos de evento do evento que está sendo processado. Essa variável é preenchida somente dentro do bloco Action de um comando de registro de eventos. O valor dessa variável também pode ser encontrado na propriedade SourceArgs do objeto PSEventArgs que 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ê inicia o PowerShell com o parâmetro PSConsoleFile ou quando usa o cmdlet Export-Console para exportar 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 usado mais recentemente na sessão. Você pode usar essa variável automática para determinar o arquivo a ser atualizado.

`$EnabledExperimentalFeatures`

Contém uma lista de nomes dos recursos experimentais habilitados.

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

`$Event`

Contém um objeto PSEventArgs que representa o evento que está sendo processado. Essa variável é preenchida somente dentro do bloco Action de um comando de registro de evento, como Register-ObjectEvent. O valor dessa variável é o mesmo objeto que o cmdlet Get-Event retorna. Pode usar as propriedades da Event variável, como $Event.TimeGenerated, num Action bloco de script.

`$EventArgs`

Contém um objeto que representa o primeiro argumento de evento que deriva de EventArgs do evento que está sendo processado. Essa variável é preenchida somente dentro do bloco Action de um comando de registro de eventos. O valor dessa variável também pode ser encontrado na propriedade SourceEventArgs do objeto PSEventArgs que Get-Event retorna.

`$EventSubscriber`

Contém um objeto PSEventSubscriber que representa o assinante do evento que está sendo processado. Essa variável é preenchida somente dentro do bloco Action de um comando de registro de eventos. 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 PowerShell host. Você pode usar essa variável para localizar os objetos de execução que estão disponíveis para cmdlets.

`$false`

Contém Falso. 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 em uma cadeia de caracteres não vazia ou em um inteiro diferente de zero.

`$foreach`

Contém o enumerador (não os valores resultantes) de um loop de foreach. A variável $foreach existe apenas enquanto o loop foreach está em execução; ele é excluído depois que o loop é concluído.

Os enumeradores contêm propriedades e métodos que você pode usar para recuperar valores de loop e alterar a iteração de loop atual. Para obter mais informações, consulte Usando enumeradores.

`$HOME`

Contém o caminho completo do diretório base do usuário. No Windows, essa variável usa o valor da variável de ambiente "$Env:USERPROFILE" Windows, normalmente C:\Users\<UserName>. No Unix, essa variável usa o valor da variável de ambiente HOME.

Importante

O Windows pode redirecionar o local do perfil do usuário. Isso significa que $HOME pode não ter o mesmo valor que "$Env:HOMEDRIVE$Env:HOMEPATH".

`$Host`

Contém um objeto que representa o aplicativo host atual para PowerShell. Você pode usar essa variável para representar o host atual em comandos ou para exibir ou alterar as propriedades do host, como $Host.Version ou $Host.CurrentCulture, ou $Host.UI.RawUI.BackGroundColor = "Red".

Observação

As configurações de cor no $Host.PrivateData foram substituídas pela variável de preferência $PSStyle. Para obter mais informações, consulte about_ANSI_Terminals.

`$input`

Contém um enumerador que enumera todas as entradas que são passadas para uma função. A $input variável está disponível apenas para funções, blocos de script (que são funções sem nome) e ficheiros de script (que são blocos de script guardados).

Em uma função sem um bloco begin, processou end, a variável $input enumera a coleção de todas as entradas para a função.
No bloco begin, a variável $input não contém dados.
No bloco process, a variável $input contém o objeto atual no pipeline.
No bloco end, a variável $input enumera a coleção de todas as entradas para a função.

Observação

Não podes usar a $input variável dentro do bloco e process do end bloco na mesma função ou bloco de script.

Como $input é um enumerador, acessar qualquer uma de suas propriedades faz com que $input não esteja mais disponível. Você pode armazenar $input em outra variável para reutilizar as propriedades $input.

Os enumeradores contêm propriedades e métodos que você pode usar para recuperar valores de loop e alterar a iteração de loop atual. Para obter mais informações, consulte Usando enumeradores.

A variável $input também está disponível para o comando especificado pelo parâmetro -Command de pwsh quando invocado a partir da linha de comando. O exemplo a seguir é executado a partir do shell de comando do Windows.

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

`$IsCoreCLR`

Contém $true se a sessão atual estiver sendo executada no .NET Core Runtime (CoreCLR). Caso contrário, contém $false.

`$IsLinux`

Contém $true se a sessão atual estiver sendo executada em um sistema operacional Linux. Caso contrário, contém $false.

`$IsMacOS`

Contém $true se a sessão atual estiver sendo executada em um sistema operacional macOS. Caso contrário, contém $false.

`$IsWindows`

Contém $true se a sessão atual estiver sendo executada em um sistema operacional Windows. Caso contrário, contém $false.

`$LASTEXITCODE`

Contém o código de saída do último programa nativo ou script do PowerShell executado.

Para scripts do PowerShell, o valor de $LASTEXITCODE depende de como o script foi chamado e se a palavra-chave exit foi usada:

Quando um script usa a palavra-chave exit:

$LASTEXITCODE é definido para valorizar o especificado pela palavra-chave exit. Para obter mais informações, consulte sobre_Palavras-chave_da_Linguagem.
Quando um script é chamado diretamente, como ./Test.ps1, ou com o operador de chamada (&) como & ./Test.ps1:

O valor do $LASTEXITCODE não é alterado, a menos que:
- O script chama outro script que usa a palavra-chave exit
- O script chama um comando nativo
- O script usa a palavra-chave exit
Quando um script é chamado com pwsh usando o parâmetro File, $LASTEXITCODE é definido como:
- 1 se o script foi encerrado devido a uma exceção
- O valor especificado pela palavra-chave exit, se usado no script
- 0 se o script foi concluído com êxito
Quando um script é chamado com pwsh usando o parâmetro Command, $LASTEXITCODE é definido como:
- 1 se o script terminou devido a uma exceção ou se o resultado do último comando foi $? para $false
- 0 se o script foi concluído com êxito e se o resultado do último comando definiu $? para $true

Para obter mais informações sobre os parâmetros File e Command, consulte about_Pwsh.

`$Matches`

A variável $Matches trabalha com os operadores -match e -notmatch. Quando você envia entrada de escalar para o operador -match ou -notmatch e um deles deteta uma correspondência, eles retornam um valor booleano e preenchem a variável automática $Matches com uma tabela de hash de quaisquer valores de cadeia de caracteres que foram correspondidos. A tabela de hash $Matches também pode ser preenchida com capturas quando você usa expressões regulares com o operador -match.

Para obter mais informações sobre o operador -match, consulte about_Comparison_Operators. Para obter mais informações sobre expressões regulares, consulte about_Regular_Expressions.

A variável $Matches também funciona em uma instrução switch com o parâmetro -Regex. É povoado da mesma forma que os operadores de -match e -notmatch. Para obter mais informações sobre a instrução switch, veja about_Switch.

Observação

Quando $Matches é preenchido numa sessão, ele retém o valor correspondente até ser substituído por outro valor. Se -match for usado novamente e nenhuma correspondência for encontrada, ele não irá repor $Matches para $null. O valor correspondido anteriormente é mantido em $Matches até que outra correspondência seja encontrada.

`$MyInvocation`

Contém informações sobre o comando atual, como nome, parâmetros, valores de parâmetro e informações sobre como o comando foi iniciado, chamado ou invocado, como o nome do script que chamou o comando atual.

$MyInvocation é preenchido apenas para scripts, funções e blocos de script. Você pode usar as informações no objeto System.Management.Automation.InvocationInfo que $MyInvocation retorna no script atual, como o nome de uma função ($MyInvocation.MyCommand.Name) para identificar o comando atual. Isso é útil para encontrar o nome do script atual.

A partir do PowerShell 3.0, MyInvocation tem as novas propriedades a seguir.

PSScriptRoot - Contém o caminho completo para o script que invocou o comando atual. O valor dessa propriedade é preenchido somente quando o chamador é um script.
PSCommandPath - Contém o caminho completo e o nome do arquivo do script que invocou o comando atual. O valor dessa propriedade é preenchido somente quando o chamador é um 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 sobre o script atual.

`$NestedPromptLevel`

Contém o nível de prompt atual. Um valor 0 indica o nível de prompt original. O valor é incrementado ao entrar em um nível aninhado e diminuído ao sair dele.

Por exemplo, o PowerShell apresenta um prompt de comando aninhado quando se usa o método $Host.EnterNestedPrompt. O PowerShell também apresenta um prompt de comando aninhado quando se atinge um ponto de interrupção no depurador do PowerShell.

Quando você insere um prompt aninhado, o 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 retornar ao prompt de comando original, conclua o comando ou digite exit.

A variável $NestedPromptLevel ajuda a monitorizar o nível de prompt. Você pode criar um prompt de comando alternativo do PowerShell que inclua esse valor para que ele esteja sempre visível.

`$null`

$null é uma variável automática que contém um valor nulo ou vazio. Você pode usar essa variável para representar um valor ausente ou indefinido em comandos e scripts.

O PowerShell trata $null como um objeto com um valor ou um espaço reservado, para que você possa usá$null para representar um valor vazio em uma coleção de valores.

Por exemplo, quando $null é incluído em uma coleção, ele é contado como um dos objetos.

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

Se você canalizar a variável $null para o cmdlet ForEach-Object, ela gerará um valor para $null, assim como para os outros objetos

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

Hello one
Hello
Hello three

Como resultado, você não pode usar $null para significar nenhum valor de parâmetro. Um valor de parâmetro de $null substitui o valor do parâmetro padrão.

No entanto, como o PowerShell trata a variável $null como um espaço reservado, pode usá-la em scripts como o seguinte, que não funcionaria se $null fosse ignorado.

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

Contém o identificador de processo (PID) do processo que está hospedando a sessão atual do PowerShell.

`$PROFILE`

Contém o caminho completo do perfil do 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á-lo em um comando para determinar se um perfil foi criado:

Test-Path $PROFILE

Ou, você pode usá-lo em um comando para criar um perfil:

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

Você pode usá-lo em um comando para abrir o perfil em notepad.exe:

notepad.exe $PROFILE

`$PSBoundParameters`

Contém um dicionário dos parâmetros que são passados para um script ou função e seus valores atuais. Essa variável tem um valor somente em um escopo onde os parâmetros são declarados, como um script ou função. Você pode usá-lo para exibir ou alterar os valores atuais dos parâmetros ou para passar valores de parâmetros para outro script ou função.

Neste exemplo, a função Test2 passa o $PSBoundParameters para a função Test1. Os $PSBoundParameters são exibidos no formato de Chave e Valor.

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`

Contém um objeto que representa o cmdlet ou a função avançada que está sendo executada.

Você pode usar as propriedades e os métodos do objeto em seu cmdlet ou código de função para responder às condições de uso. Por exemplo, a propriedade ParameterSetName contém o nome do conjunto de parâmetros que está sendo usado, e o método ShouldProcess adiciona os parâmetros WhatIf e Confirm ao cmdlet dinamicamente.

Para obter mais informações sobre a variável automática $PSCmdlet, consulte about_Functions_CmdletBindingAttribute e about_Functions_Advanced.

`$PSCommandPath`

Contém o caminho completo e o nome do arquivo do script que está sendo executado. Esta variável é válida em todos os scripts.

`$PSCulture`

A partir do PowerShell 7, $PSCulture reflete a cultura do espaço de execução (sessão) atual do PowerShell. Se a cultura for alterada em um espaço de execução do PowerShell, o valor $PSCulture para esse espaço de execução será atualizado.

A cultura determina o formato de exibição de itens como números, moeda e datas e é armazenada em um objeto System.Globalization.CultureInfo . Use Get-Culture para exibir a cultura do computador. $PSCulture contém o valor da propriedade Nome .

`$PSDebugContext`

Durante a depuração, essa variável contém informações sobre o ambiente de depuração. Caso contrário, ele contém um valor nulo. Como resultado, você pode usá-lo para determinar se o depurador tem controle. Quando preenchido, contém um objeto PsDebugContext que tem as propriedades Breakpoints e InvocationInfo. A propriedade InvocationInfo tem várias propriedades úteis, incluindo a propriedade Location. A propriedade Location indica o caminho do script que está a ser depurado.

`$PSEdition`

Contém o mesmo valor em $PSVersionTable.PSEdition. Essa variável está disponível para uso em arquivos de manifesto do módulo, enquanto $PSVersionTable não está.

`$PSHOME`

Contém o caminho completo do diretório de instalação do PowerShell, normalmente, C:\Program Files\PowerShell\7 em sistemas Windows. Você pode usar essa variável nos caminhos dos arquivos do PowerShell. Por exemplo, o comando a seguir pesquisa os tópicos conceituais da Ajuda para a palavra Ajuda:

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

`$PSItem`

O mesmo que $_. Contém o objeto atual no objeto de pipeline. Você pode usar essa variável em comandos que executam uma ação em cada objeto em um pipeline.

Para obter mais informações, consulte about_PSItem.

`$PSScriptRoot`

Contém o caminho completo do diretório pai do script em execução.

No PowerShell 2.0, essa variável é válida somente em módulos de script (.psm1). A partir do PowerShell 3.0, ele é válido 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. Esta variável está disponível apenas em PSSessions.

A variável $PSSenderInfo inclui uma propriedade configurável pelo usuário, ApplicationArguments, que, por padrão, contém apenas o $PSVersionTable da sessão de origem. Para adicionar dados à propriedade ApplicationArguments, use o parâmetro ApplicationArguments do cmdlet New-PSSessionOption.

Importante

Como esta propriedade contém dados explicitamente fornecidos pelo cliente, utilizá-la para decisões de segurança poderia permitir que os atacantes contornassem os controlos de autorização. Nunca use estes dados para decisões de confiança. Validar todas as entradas do utilizador quando usadas para outra lógica de aplicação.

`$PSUICulture`

Contém o nome da cultura da interface do usuário (UI) configurada no sistema operacional. A cultura da interface do usuário determina quais cadeias de texto são usadas para elementos da interface do usuário, como menus e mensagens. Este é 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 hash somente de leitura que exibe detalhes sobre a versão do PowerShell que está em execução na sessão atual. A tabela inclui os seguintes itens:

PSVersion - O número de versão do PowerShell
PSEdition Esta propriedade tem o valor de 'Desktop' para o PowerShell 4 e inferior, bem como para o PowerShell 5.1 em edições completas com todas as funcionalidades do Windows. Esta propriedade tem o valor de Core para o PowerShell 6 e versões superiores, assim como para o Windows PowerShell 5.1 em edições com redução de pegada, como o Windows Nano Server ou o Windows IoT.
GitCommitId - O commit ID dos ficheiros de origem, no GitHub,
OS - Descrição do sistema operacional no qual o PowerShell está sendo executado.
Platform - Plataforma na qual o sistema operacional está sendo executado. O valor no Linux e macOS é Unix. Ver $IsMacOS e $IsLinux.
PSCompatibleVersions - Versões do PowerShell compatíveis com a versão atual
PSRemotingProtocolVersion - A versão do protocolo de gerenciamento remoto do PowerShell.
SerializationVersion - A versão do método de serialização
WSManStackVersion - O número da versão da stack de WS-Management

`$PWD`

Contém um objeto de caminho que representa o caminho completo do diretório atual para o espaço de execução atual do PowerShell.

Observação

O PowerShell oferece suporte a vários espaços de execução por processo. Cada espaço de execução tem o seu próprio diretório atual. Isso não é o mesmo que o diretório atual do processo: [System.Environment]::CurrentDirectory.

`$Sender`

Contém o objeto que gerou esse evento. Essa variável é preenchida somente 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 que Get-Event retorna.

`$ShellId`

Contém o identificador do shell atual.

`$StackTrace`

Contém um rastreamento de pilha para o erro mais recente.

`$switch`

Contém o enumerador e não os valores resultantes de uma instrução switch. A variável $switch existe apenas enquanto a instrução switch está em execução; ele é excluído quando a instrução switch conclui a execução. Para obter mais informações, consulte about_Switch.

Os enumeradores contêm propriedades e métodos que você pode usar para recuperar valores de loop e alterar a iteração de loop atual. Para obter mais informações, consulte Usando enumeradores.

`$this`

A $this variável é usada em blocos de script que estendem classes para se referir à instância da própria classe.

O Sistema de Tipos Extensíveis (ETS) do PowerShell permite adicionar propriedades a classes usando blocos de script. Num bloco de scripts que define uma propriedade de script ou método de script, a $this variável refere-se a uma instância de objeto da classe que está a ser estendida. Por exemplo, o PowerShell usa o ETS para adicionar a propriedade BaseName à classe FileInfo do.

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};}

Para obter mais informações, consulte about_Types.ps1xml.

Em uma classe do PowerShell, a variável $this refere-se ao objeto de instância da própria classe, permitindo acesso a propriedades e métodos definidos na classe. Para obter mais informações, consulte about_Classes.

A $this variável é também usada por classes de eventos .NET que aceitam blocos de script como delegados para o gestor de eventos. Nesse cenário, $this representa o objeto que origina o evento, conhecido como o remetente do evento.

`$true`

Contém True. Você pode usar essa variável para representar True em comandos e scripts.

Usando enumeradores

As variáveis $input, $foreache $switch são todas enumeradores usados para iterar pelos valores processados pelo respetivo bloco de código que as contém.

Um enumerador contém propriedades e métodos que você pode usar para avançar ou redefinir iteração ou recuperar valores de iteração. Manipular diretamente os recenseadores não é considerado uma prática recomendada.

Dentro dos loops, as palavras-chave de controle de fluxo break e continue devem ser preferidas.
Dentro de funções que aceitam entrada de pipeline, é uma prática recomendada usar parâmetros com os atributos ValueFromPipeline ou ValueFromPipelineByPropertyName.

Para obter mais informações, consulte about_Functions_Advanced_Parameters.

Avançar

O método MoveNext avança o enumerador para o próximo elemento da coleção. MoveNext retorna True se o enumerador for avançado com êxito, False se o enumerador passou o final da coleção.

Observação

O valor Boolean retornado pelo MoveNext é enviado para o fluxo de saída. Você pode suprimir a saída digitando-a para [void] ou canalizando-a para Out-Null .

$input.MoveNext() | Out-Null

[void]$input.MoveNext()

Reset

O método Reset define o enumerador para sua posição inicial, que é antes de o primeiro elemento na coleção.

Current

A propriedade Current obtém o elemento na coleção, ou no pipeline, na posição atual do enumerador.

A propriedade Current continua a retornar a mesma propriedade até que MoveNext seja chamada.

Examples

Exemplo 1: Usando a variável $input

No exemplo a seguir, acessar a variável $input limpa a variável até a próxima vez que o bloco de processo for executado. O uso do método Reset redefine a variável $input para o valor do pipeline atual.

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

O bloco de processo avança automaticamente a variável $input, mesmo que você não a acesse.

$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

Exemplo 2: Usando $input fora do bloco de processo

Fora do bloco de processo, a variável $input representa todos os valores canalizados para a função.

O acesso à variável $input limpa todos os valores.
O método Reset redefine toda a coleção.
A propriedade Current nunca é populada.
O método MoveNext retorna false porque a coleção não pode ser avançada.
- Chamar MoveNext limpa a variável $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:

Exemplo 3: Utilizando a propriedade $input.Current

Com a propriedade Current, o valor do pipeline atual pode ser acessado várias vezes sem usar o método Reset. O bloco de processo não chama automaticamente o método MoveNext .

A propriedade Current nunca é preenchida, a menos que você chame explicitamente MoveNext. A propriedade Current pode ser acessada várias vezes dentro do bloco de processo sem limpar seu valor.

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

Exemplo 4: Usando a variável $foreach

Ao contrário da variável $input, a variável $foreach sempre representa todos os itens da coleção quando acessada diretamente. Use a propriedade Current para acessar o elemento de coleção atual e os métodos Reset e MoveNext para alterar seu valor.

Observação

Cada iteração do loop foreach chama automaticamente o método MoveNext.

O loop a seguir só é executado duas vezes. Na segunda iteração, a coleção é movida para o terceiro elemento antes que a iteração seja concluída. Após a segunda iteração, agora não há mais valores para iterar e o loop termina.

A propriedade MoveNext não afeta a variável selecionada para percorrer a coleção ($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

O uso do método Reset redefine o elemento atual na coleção. O exemplo a seguir percorre duas vezes os dois primeiros elementos porque o método Reset é executado. Após os dois primeiros loops, a instrução if falha e o loop itera pelos três elementos normalmente.

Importante

Isso poderia resultar em um loop infinito.

$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

Exemplo 5: Usando a variável $switch

A variável $switch tem exatamente as mesmas regras que a variável $foreach. O exemplo a seguir demonstra todos os conceitos do enumerador.

Observação

Observe como o caso NotEvaluated nunca é executado, mesmo que não haja nenhuma instrução break após o método MoveNext.

$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

Consulte também

Comentários

Esta página foi útil?

Last updated on 2026-02-10

Partilhar via

sobre_Variáveis_Automáticas

Breve descrição

Descrição longa

$$

$?

$^

$_

$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

Usando enumeradores

Avançar

Reset

Current

Examples

Exemplo 1: Usando a variável $input

Exemplo 2: Usando $input fora do bloco de processo

Exemplo 3: Utilizando a propriedade $input.Current

Exemplo 4: Usando a variável $foreach

Exemplo 5: Usando a variável $switch

Consulte também

Comentários

Recursos adicionais

`$$`

`$?`

`$^`

`$_`

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