about_Automatic_Variables

Descrição curta

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

Descrição longa

Conceitualmente, a maioria dessas variáveis é considerada somente de leitura. Mesmo que eles possam ser gravados, para compatibilidade com versões anteriores, 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 caso tenha falhado. Erros de análise não resultam em execução, portanto, eles 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 de 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 a execução, mas não definirá $? como False para uma função que a chama:

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 a última finalidade, $PSCmdlet.WriteError() deve ser usado em vez disso.

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

$^

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 uma matriz de valores para parâmetros não declarados que são passados para uma função, script ou scriptblock. 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 no 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 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 você 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 que foi 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 que estão 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 de $Error, use o parâmetro comum ErrorAction com um valor de Ignorar. 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 no 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. Você pode usar as propriedades da Event variável, como $Event.TimeGenerated, em um Action scriptblock.

$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 no bloco Action de um comando de registro de evento. O valor dessa variável também pode ser encontrado na propriedade SourceEventArgs do PSEventArgs objeto 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 no 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 PowerShell. Você pode usar essa variável para localizar os objetos de execução que estão disponíveis para 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 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 somente enquanto o loop foreach está em execução; ele é excluído após a conclusão do loop.

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 do "$Env:USERPROFILE" Windows, normalmente C:\Users\<UserName>. No Unix, essa variável usa o valor da variável de ambiente HOME.

$Host

Contém um objeto que representa o aplicativo host atual para o 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.CurrentCultureou $Host.UI.RawUI.BackGroundColor = "Red".

$input

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

• 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.

  Nota

  Você não pode usar a $input variável dentro do process bloco e 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 estejam mais disponíveis. 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 da linha de comando. O exemplo a seguir é executado no shell do Comando do Windows.

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

$IsCoreCLR

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

$IsLinux

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

$IsMacOS

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

$IsWindows

Contém $true se a sessão atual estiver em execução 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 é configurado para o valor especificado pela palavra-chave exit. Para obter mais informações, consulte about_Language_Keywords.

• Quando um script é chamado diretamente, como ./Test.ps1, ou com o operador de chamada (&) como & ./Test.ps1:

  O valor de $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 foi encerrado devido a uma exceção ou se o resultado do último comando definiu $? para $false
  • 0 se o script foi concluído com êxito e o resultado do último comando definiu $? para $true

Para obter mais informações sobre os parâmetros de Arquivo e Comando , consulte about_Pwsh.

$Matches

A variável $Matches funciona com os operadores -match e -notmatch. Quando você envia entrada escalar para o operador -match ou -notmatch e um deles detecta uma correspondência, ele retorna um valor booleano e preenche a variável automática $Matches com uma tabela de hash de quaisquer valores de cadeia de caracteres correspondentes. 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. Ele é preenchido da mesma forma que os operadores -match e -notmatch. Para mais informações sobre a instrução switch, veja about_Switch.

$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 invocado, como o nome do script que chamou o comando atual.

$MyInvocation é populado apenas para scripts, funções e scriptblocks. 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 localizar 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 invocador ou o script de chamada, não o script atual.

$NestedPromptLevel

Contém o nível de solicitação atual. Um valor de 0 indica o nível de prompt original. O valor aumenta quando você entra em um nível aninhado e diminui quando você sai dele.

Por exemplo, o PowerShell apresenta um prompt de comando aninhado quando você usa o método $Host.EnterNestedPrompt. O PowerShell também apresenta um prompt de comando aninhado quando você 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 controlar o nível do prompt. Você pode criar um prompt de comando alternativo do PowerShell que inclui esse valor para que ele fique 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 usar $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

3

Se você redirecionar a variável $null para o cmdlet ForEach-Object, ela gerará um valor para $null, assim como faz 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 quando não há 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, você pode usá-la em scripts como o seguinte, o 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 PID (identificador de processo) do processo que hospeda 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 no 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 em que os parâmetros são declarados, como um script ou uma função. Você pode usá-lo para exibir ou alterar os valores atuais dos parâmetros ou passar valores de parâmetro 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 Key e Value.

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. Essa variável é válida em todos os scripts.

$PSCulture

A partir do PowerShell 7, $PSCulture reflete a cultura do runspace atual do PowerShell (sessão). Se a cultura for alterada em um runspace do PowerShell, o valor $PSCulture desse runspace 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 Name.

$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 populado, ele contém um objeto PsDebugContext que possui as propriedades de Breakpoints e de InvocationInfo. A propriedade InvocationInfo possui várias características úteis, incluindo a característica Location. A propriedade Location indica o caminho do script que está sendo 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. Essa variável só está disponível 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.

$PSUICulture

Contém o nome da cultura da interface do usuário configurada 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 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 Essa propriedade tem o valor de 'Desktop' para PowerShell 4 e anteriores, assim como o PowerShell 5.1 nas edições completas do Windows. Essa propriedade tem o valor de Core para o PowerShell 6 e superior, assim como para o Windows PowerShell 5.1 em edições de menor pegada, como o Windows Nano Server ou Windows IoT.
• GitCommitId – O ID de commit dos arquivos de origem, no GitHub,
• sistema operacional – Descrição do sistema operacional no qual o PowerShell está em execução.
• Platform – plataforma na qual o sistema operacional está em execução. O valor no Linux e no macOS é Unix. Consulte $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 de versão da pilha de WS-Management

$PWD

Contém um objeto de caminho que representa o caminho completo do diretório atual no runspace atual do PowerShell.

$Sender

Contém o objeto que gerou esse evento. Essa variável é preenchida somente no bloco Ação 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 somente 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 scriptblocks que estendem classes para se referir à instância da própria classe.

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

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 o acesso a propriedades e métodos definidos na classe. Para saber mais, confira about_Classes.

A $this variável também é usada por classes de eventos do .NET que utilizam scriptblocks como delegados para o manipulador de eventos. Nesse cenário, $this representa o objeto originário do evento, conhecido como remetente de 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 enumeradoras usadas para iterar pelos valores processados pelo bloco de código que os contém.

Um enumerador contém propriedades e métodos que você pode usar para avançar ou redefinir a iteração ou recuperar valores de iteração. A manipulação direta de enumeradores não é considerada a melhor prática.

• Em loops, as palavras-chave de controle de fluxo break e continue devem ser preferidas.

• Em funções que aceitam entrada de pipeline, é prática recomendada usar parâmetros com os atributos ValueFromPipeline ou ValueFromPipelineByPropertyName.

  Para obter mais informações, consulte about_Functions_Advanced_Parameters.

MoveNext

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

$input.MoveNext() | Out-Null

[void]$input.MoveNext()

Reset

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

Current

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

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

Exemplos

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 atual do pipeline.

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 se você não acessá-la.

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

• Acessar a variável $input limpa todos os valores.
• O método Reset redefine toda a coleção.
• A propriedade Current nunca é preenchida.
• O método MoveNext retorna falso 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: Usando 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 é populada, a menos que você explicitamente chame MoveNext. A propriedade Current pode ser acessada várias vezes seguidas 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.

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

A propriedade MoveNext não afeta a variável escolhida para iterar através da 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

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

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

$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

• 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