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 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. Ele contém True se o último comando foi bem-sucedido e False se ele falhou. 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 ambos e processend blocos, chamar this.WriteError() ou $PSCmdlet.WriteError() , respectivamente, em qualquer ponto é definido $? como False, como faz this.ThrowTerminatingError() e $PSCmdlet.ThrowTerminatingError().

O Write-Error cmdlet sempre é definido $? como False imediatamente após ser executado, mas não será definido $? como False para uma função que o 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 o último propósito, $PSCmdlet.WriteError() deve ser usado em seu lugar.

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

Observação

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

`$^`

Contém o primeiro token na última linha recebida pela sessã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 param palavra-chave ou adicionando uma lista de parâmetros separados por vírgulas entre parênteses após o nome da função.

Em uma ação de evento, a $args variável contém objetos que representam os argumentos de evento do evento que está sendo processado. Essa variável é preenchida somente dentro do Action bloco de um comando de registro de evento. O valor dessa variável também pode ser encontrado na propriedade SourceArgs do PSEventArgs objeto 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 Export-Console cmdlet para exportar nomes de snap-in para um arquivo de console.

Quando você usa o Export-Console cmdlet 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 à $Error matriz, use o parâmetro comum ErrorAction com um valor de Ignore. Para obter mais informações, confira about_CommonParameters.

`$Event`

Contém um PSEventArgs objeto que representa o evento que está sendo processado. Essa variável é preenchida somente dentro do Action bloco de um comando de registro de evento, como Register-ObjectEvent. O valor dessa variável é o mesmo objeto que o Get-Event cmdlet 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 derivado de EventArgs do evento que está sendo processado. Essa variável é preenchida somente dentro do Action bloco 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 PSEventSubscriber objeto que representa o assinante do evento que está sendo processado. Essa variável é preenchida somente dentro do Action bloco de um comando de registro de evento. O valor dessa variável é o mesmo objeto que o Get-EventSubscriber cmdlet 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 string "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 $foreach variável existe apenas enquanto o foreach loop está em execução; ela é excluída 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 inicial do usuário. No Windows, essa variável usa o valor da variável de ambiente Windows "$Env:USERPROFILE" , normalmente C:\Users\<UserName>. No Unix, essa variável usa o valor da variável de HOME ambiente.

Importante

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

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

Observação

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

`$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 beginbloco , process, ou end , a $input variável enumera a coleção de todas as entradas para a função.
begin No bloco, a $input variável não contém dados.
No bloco process, a variável $input contém o objeto atual no pipeline.
end No bloco, a $input variável enumera a coleção de todas as entradas para a função.

Observação

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 esteja mais disponível. Você pode armazenar $input em outra variável para reutilizar as $input propriedades.

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 $input variável também está disponível para o comando especificado pelo -Command parâmetro de quando invocado pwsh a partir da linha de comando. O exemplo a seguir é executado no shell de 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 que foi executado.

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

Quando um script usa a exit palavra-chave:

$LASTEXITCODE é definido como o valor especificado pela exit palavra-chave. 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 exit palavra-chave
- O script chama um comando nativo
- O script usa a exit palavra-chave
Quando um script é chamado usando pwsh o parâmetro File , $LASTEXITCODE é definido como:
- 1 se o script foi encerrado devido a uma exceção
- O valor especificado pela exit palavra-chave, se usado no script
- 0 Se o script foi concluído com êxito
Quando um script é chamado usando pwsh 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 definido $? como $false
- 0 se o script for concluído com êxito e o resultado do último comando definido $? como $true

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

`$Matches`

A $Matches variável funciona com os -match operadores and -notmatch . Quando você envia uma entrada escalar para o -match operador or -notmatch e qualquer um deles detecta uma correspondência, eles retornam um valor booliano e preenchem a $Matches variável automática com uma tabela de hash de todos os valores de cadeia de caracteres correspondentes. A $Matches tabela de hash também pode ser preenchida com capturas quando você usa expressões regulares com o -match operador.

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

A $Matches variável também funciona em uma switch instrução com o -Regex parâmetro. Ele é preenchido da mesma forma que os -match operadores and -notmatch . Para obter mais informações sobre a instrução, consulte about_Switchswitch.

Observação

Quando $Matches é preenchido em uma sessão, ele retém o valor correspondente até que seja substituído por outra correspondência. Se -match for usado novamente e nenhuma correspondência for encontrada, isso não redefinirá $Matches como $null. O valor correspondente anteriormente é mantido até $Matches que outra correspondência seja encontrada.

`$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 é incrementado quando você insere um nível aninhado e decrementado quando você sai dele.

Por exemplo, o PowerShell apresenta um prompt de comando aninhado quando você usa o $Host.EnterNestedPrompt método. 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 para retornar ao prompt de comando original, conclua o comando ou digite exit.

A $NestedPromptLevel variável ajuda a rastrear 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 como $null 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

Se você canalizar a $null variável para o ForEach-Object cmdlet, 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 nenhum valor de parâmetro. Um valor de parâmetro substitui o valor do $null parâmetro padrão.

No entanto, como o PowerShell trata a variável como um espaço reservado $null , você 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 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 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 em que 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 passar valores de parâmetro para outro script ou função.

Neste exemplo, a função Test2 passa a $PSBoundParameters função para a função Test1 . Eles $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 $PSCmdlet variável automática, 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 $PSCulture valor 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 preenchido, ele 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á 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`

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 o PSSession, incluindo a identidade do usuário e o fuso horário do computador de origem. Essa variável está disponível apenas em PSSessions.

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

`$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 Get-UICulture cmdlet.

`$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 da versão do PowerShell
PSEdition Essa propriedade tem o valor de 'Área de Trabalho' para o PowerShell 4 e inferior, bem como o PowerShell 5.1 em edições completas do Windows. Essa propriedade tem o valor de Core para o PowerShell 6 e superior, bem como para o Windows PowerShell 5.1 em edições de volume reduzido, como o Windows Nano Server ou o Windows IoT.
GitCommitId - O ID de confirmação dos arquivos de origem, no GitHub,
SO – Descrição do sistema operacional no qual o PowerShell está sendo executado.
Plataforma - Plataforma na qual o sistema operacional está sendo executado. O valor no Linux e no macOS é Unix. Confira $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 pilha WS-Management

`$PWD`

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

Observação

O PowerShell dá suporte a vários runspaces por processo. Cada runspace tem seu próprio diretório atual. Isso não é o mesmo que o diretório do processo atual: [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 PSEventArgs objeto 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, não os valores resultantes de uma switch instrução. A $switch variável existe apenas enquanto a switch instrução está em execução; ela é excluída quando a instrução conclui a switch 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 $this variável 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 que origina o evento, conhecido como remetente do evento.

`$true`

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

Usando enumeradores

As $inputvariáveis , $foreach, e $switch são todos enumeradores usados para iterar por meio dos valores processados pelo bloco de código que o 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. Manipular diretamente enumeradores não é considerado uma prática recomendada.

Dentro dos loops, as palavras-chave de controle de fluxo break e continue devem ser preferidas.
Nas 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.

MoveNext

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

Observação

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

$input.MoveNext() | Out-Null

[void]$input.MoveNext()

Reset

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

Current

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

A Current propriedade 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 $input variável 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 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 $input variável representa todos os valores canalizados para a função.

Acessar a $input variável limpa todos os valores.
O Reset método redefine toda a coleção.
A Current propriedade nunca é preenchida.
O método MoveNext retorna false porque a coleção não pode ser avançada.
- Chamar MoveNext limpa a $input variável.

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 o $input.Current propriedade

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 Current propriedade nunca é preenchida, a menos que você chame explicitamente MoveNext. A Current propriedade 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 $input variável, a $foreach variável 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 foreach loop chama automaticamente o método MoveNext .

O loop a seguir é executado apenas 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 é encerrado.

A propriedade MoveNext não afeta a variável escolhida para iterar por meio 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 Reset método é chamado. Após os dois primeiros loops, a if instrução falha e o loop itera por todos os três elementos normalmente.

Importante

Isso pode 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 $switch variável tem exatamente as mesmas regras que a $foreach variável. 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 break instrução 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-01-18

Compartilhar via

about_Automatic_Variables

Descrição curta

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

MoveNext

Reset

Current

Exemplos

Exemplo 1: Usando a variável $input

Exemplo 2: Usando $input fora do bloco de processo

Exemplo 3: Usando o $input.Current propriedade

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`