about_Automatic_Variables
Breve descrição
Descreve variáveis que armazenam informações de estado para e são criadas e mantidas pelo PowerShell.
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 para.
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
Descrição longa
$$
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 for bem-sucedido e False se falhar. 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 executados em vários estágios em um pipeline, por exemplo, em ambos e process
end
blocos, chamando this.WriteError()
ou $PSCmdlet.WriteError()
respectivamente em qualquer ponto define $?
como False, como faz this.ThrowTerminatingError()
e $PSCmdlet.ThrowTerminatingError()
.
O Write-Error
cmdlet sempre define $?
como False imediatamente após ser executado, mas não será definido $?
como 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 fim, $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.
Nota
Até o PowerShell 7, encapsulando uma instrução entre parênteses (...)
, sintaxe $(...)
de subexpressão ou uma expressão @(...)
de matriz sempre reset$?
como True. Por exemplo, (Write-Error)
mostra $?
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.
$_
O mesmo que $PSItem
. Contém o current objeto 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 bloco de script. Ao criar uma função, você pode declarar os parâmetros com a param
palavra-chave 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 $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 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 à $Error
matriz, use o parâmetro comum ErrorAction com um valor Ignore. Para obter mais informações, consulte 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 variável, como $Event.TimeGenerated
, em um Action
bloco de Event
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 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 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 ForEach . A $ForEach
variável existe apenas enquanto o ForEach
loop está em execução, ela é excluída 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 current loop. 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 "$env:USERPROFILE"
ambiente Windows, normalmente C:\Users\<UserName>
. No Unix, esta 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 "$env:HOMEDRIVE$env:HOMEPATH"
que $HOME
.
$Host
Contém um objeto que representa o current aplicativo host para PowerShell.
Você pode usar essa variável para representar o current host em comandos ou para exibir ou alterar as propriedades do host, como $Host.version
ou $Host.CurrentCulture
, ou $Host.UI.RawUI.BackGroundColor = "Red"
.
Nota
As configurações de cor em $Host.PrivateData
foram substituídas pela variável de $PSStyle
preferência. 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 arquivos de script (que são blocos de script salvos).
Em uma função sem um
begin
,process
, ouend
bloco, 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.process
No bloco , a$input
variável contém o current objeto no pipeline.end
No bloco , a$input
variável enumera a coleção de todas as entradas para a função.Nota
Não é possível usar a
$input
variável dentro doprocess
bloco e doend
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 current loop. Para obter mais informações, consulte Usando enumeradores.
A $input
variável também está disponível para o -Command
comando especificado pelo parâmetro de quando invocado a partir da linha de pwsh
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 current sessão está sendo executada no .NET Core Runtime (CoreCLR). Caso contrário, contém $false
.
$IsLinux
Contém $true
se a sessão está sendo executada current em um sistema operacional Linux.
Caso contrário, contém $false
.
$IsMacOS
Contém $true
se a sessão está sendo executada current em um sistema operacional MacOS.
Caso contrário, contém $false
.
$IsWindows
Contém $true
se a sessão está sendo executada current 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 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 para valorizar o especificado pela palavra-chaveexit
. 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 do
$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
- O script chama outro script que usa a
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 palavra-chave
exit
, se usado no script 0
se o script foi concluído com êxito
Quando um script é chamado usando o parâmetro Command,
$LASTEXITCODE
é definido comopwsh
: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 foi concluído com êxito e o resultado do último comando definido$?
como$true
Para obter mais informações sobre os parâmetros File e Command , consulte about_Pwsh.
$Matches
A $Matches
variável trabalha com os -match
e -notmatch
operadores. Quando você envia a entrada escalar para o -match
operador ou -notmatch
e qualquer um deles deteta uma correspondência, eles retornam um valor booleano e preenchem a $Matches
variável automática com uma tabela de hash de quaisquer valores de cadeia de caracteres que foram correspondidos. A tabela hash $Matches
também pode ser preenchida com capturas quando utiliza expressões regulares com o operador -match
.
Para obter mais informações sobre o -match
operador, consulte about_Comparison_Operators. 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. É povoado da mesma forma que os e -notmatch
operadores-match
. Para obter mais informações sobre a instrução, consulte about_Switchswitch
.
Nota
Quando $Matches
é preenchido em uma sessão, ele retém o valor correspondente até ser substituído por outra correspondência. Se -match
for usado novamente e nenhuma correspondência for encontrada, não reset$Matches
será $null
. O valor correspondido anteriormente é mantido até $Matches
que outra correspondência seja encontrada.
$MyInvocation
Contém informações sobre o current comando, 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 current comando.
$MyInvocation
é preenchido apenas para scripts, função e blocos de script. Você pode usar as informações no objeto System.Management.Automation.InvocationInfo que $MyInvocation
retorna no current script, como o nome de uma função ($MyInvocation.MyCommand.Name
) para identificar o current comando.
Isso é útil para encontrar o current nome do script.
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 current comando. 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 current comando. O valor dessa propriedade é preenchido somente quando o chamador é um script.
Ao contrário das $PSScriptRoot
variáveis e $PSCommandPath
automáticas, as propriedades PSScriptRoot e PSCommandPath da variável automática contêm informações sobre o $MyInvocation
invocador ou script de chamada, não o current script.
$NestedPromptLevel
Contém o nível de current prompt. Um valor 0 indica o nível de prompt original. O valor é incrementado quando você entra em um nível aninhado e diminuído 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 current comando, salva o contexto de execução e incrementa o $NestedPromptLevel
valor da variável. 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 $NestedPromptLevel
variável ajuda você 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 é $null
tratado 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ê canalizar a $null
variável para o ForEach-Object
cmdlet, 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 substitui o valor de $null
parâmetro padrão.
No entanto, como o PowerShell trata a $null
variável como um espaço reservado, 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 identificador de processo (PID) do processo que está hospedando a sessão do current PowerShell.
$PROFILE
Contém o caminho completo do perfil do PowerShell para o current usuário e o current aplicativo host. 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 current valores. 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 current valores de parâmetros ou para passar valores de parâmetro para outro script ou função.
Neste exemplo, a função Test2 passa para $PSBoundParameters
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 $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. 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) do current PowerShell. Se a cultura for alterada em um espaço de execução do PowerShell, o $PSCulture
valor desse 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 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 Breakpoints e propriedades 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, mas $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 current objeto 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 $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 (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 Get-UICulture
cmdlet.
$PSVersionTable
Contém uma tabela de hash somente leitura que exibe detalhes sobre a versão do PowerShell que está sendo executada current na sessão. A tabela inclui os seguintes itens:
- PSVersion - O número da versão do PowerShell
- PSEdition Esta 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. Esta propriedade tem o valor de
Core
para o PowerShell 6 e superior, bem como para o Windows PowerShell 5.1 em edições de pegada reduzida, como o Windows Nano Server ou o Windows IoT. - GitCommitId - O ID de confirmação dos arquivos de origem, no GitHub,
- OS - 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 macOS é Unix. Veja
$IsMacOs
e$IsLinux
. - PSCompatibleVersions - Versões do PowerShell compatíveis com a current versão
- 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 path que representa o caminho completo do current local do diretório para o espaço de execução do current PowerShell.
Nota
O PowerShell oferece suporte a vários espaços de execução por processo. Cada espaço de execução tem seu próprio current diretório. Isso não é o mesmo que o current diretório 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 PSEventArgs objeto que Get-Event
retorna.
$ShellId
Contém o identificador do current shell.
$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 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 current loop. 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 ETS (Extensible Type System) do PowerShell permite adicionar propriedades a classes usando blocos de script. Em um bloco de script 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á 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 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 evento .NET que usam blocos de script como delegados para o manipulador de eventos. Nesse cenário, $this
representa o objeto que originou 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 $input
variáveis , $foreach
, e são $switch
todos enumeradores usados para iterar através dos valores processados por seu bloco de código que contém.
Um enumerador contém propriedades e métodos que você pode usar para avançar ou reset iterar, 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 quebram e continuam devem ser preferidas.
Dentro de 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 foi avançado com êxito, False
se o enumerador passou o final da coleção.
Nota
O valor booleano retornado por MoveNext é enviado para o fluxo de saída.
Você pode suprimir a saída digitando-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 Current propriedade obtém o elemento na coleção, ou pipeline, na current posição 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 Reset método redefine a $input
variável para o valor do current 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.
- O acesso à
$input
variável limpa todos os valores. - O Reset método redefine toda a coleção.
- A Current propriedade nunca é povoada.
- O método MoveNext retorna false porque a coleção não pode ser avançada.
- Chamar MoveNext limpa a
$input
variável.
- Chamar MoveNext limpa a
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 Current propriedade, o valor do pipeline pode ser acessado current várias vezes sem usar o Reset método. O bloco de processo não chama automaticamente o método MoveNext .
A propriedade nunca é preenchida, Current 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 Current propriedade para acessar o current elemento collection e os Reset métodos e MoveNext para alterar seu valor.
Nota
Cada iteração do foreach
loop 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 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
O uso do Reset método redefine o current elemento 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 através de todos os 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 $switch
variável tem exatamente as mesmas regras que a $foreach
variável. O exemplo a seguir demonstra todos os conceitos do enumerador.
Nota
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