Partilhar via

Wait-Job

  • Referência
Módulo:
Microsoft.PowerShell.Core

Suprime o prompt de comando até que um ou todos os trabalhos em segundo plano do Windows PowerShell em execução na sessão sejam concluídos.

Sintaxe

Wait-Job
    [-Any]
    [-Timeout <Int32>]
    [-Force]
    [-Id] <Int32[]>
    [<CommonParameters>]
Wait-Job
    [-Job] <Job[]>
    [-Any]
    [-Timeout <Int32>]
    [-Force]
    [<CommonParameters>]
Wait-Job
    [-Any]
    [-Timeout <Int32>]
    [-Force]
    [-Name] <String[]>
    [<CommonParameters>]
Wait-Job
    [-Any]
    [-Timeout <Int32>]
    [-Force]
    [-InstanceId] <Guid[]>
    [<CommonParameters>]
Wait-Job
    [-Any]
    [-Timeout <Int32>]
    [-Force]
    [-State] <JobState>
    [<CommonParameters>]
Wait-Job
    [-Any]
    [-Timeout <Int32>]
    [-Force]
    [-Filter] <Hashtable>
    [<CommonParameters>]

Description

O cmdlet Wait-Job aguarda a conclusão dos trabalhos em segundo plano do Windows PowerShell antes de exibir o prompt de comando. Você pode esperar até que qualquer trabalho em segundo plano seja concluído ou até que todos os trabalhos em segundo plano sejam concluídos, e você pode definir um tempo máximo de espera para o trabalho.

Quando os comandos no trabalho estiverem concluídos, Wait-Job exibirá o prompt de comando e retornará um objeto de trabalho para que você possa canalizá-lo para outro comando.

Você pode usar cmdlet Wait-Job para aguardar trabalhos em segundo plano, como aqueles que foram iniciados usando o cmdlet Start-Job ou o parâmetro AsJob do cmdlet Invoke-Command. Para obter mais informações sobre trabalhos em segundo plano do Windows PowerShell, consulte about_Jobs.

A partir do Windows PowerShell 3.0, o cmdlet Wait-Job também aguarda tipos de trabalho personalizados, como trabalhos de fluxo de trabalho e instâncias de trabalhos agendados. Para permitir que Wait-Job aguarde trabalhos de um tipo específico, importe o módulo que dá suporte ao tipo de trabalho personalizado para a sessão antes de executar o cmdlet Get-Job, usando o cmdlet Import-Module ou usando ou obtendo um cmdlet no módulo. Para obter informações sobre um tipo de trabalho personalizado específico, consulte a documentação do recurso de tipo de trabalho personalizado.

Exemplos

Exemplo 1: Aguarde todos os trabalhos

PS C:\> Get-Job | Wait-Job

Este comando aguarda a conclusão de todos os trabalhos em segundo plano em execução na sessão.

Exemplo 2: Aguarde trabalhos iniciados em computadores remotos usando Start-Job

PS C:\> $s = New-PSSession Server01, Server02, Server03
PS C:\> Invoke-Command -Session $s -ScriptBlock {Start-Job -Name Date1 -ScriptBlock {Get-Date}}
PS C:\> $done = Invoke-Command -Session $s -Command {Wait-Job -Name Date1}
PS C:\> $done.Count
3

Este exemplo mostra como usar o cmdlet Wait-Job com trabalhos iniciados em computadores remotos usando o cmdlet Start-Job. Os comandos Start-Job e Wait-Job são enviados ao computador remoto usando o cmdlet Invoke-Command.

Este exemplo usa Wait-Job para determinar se um comando Get-Date executado como um trabalho em segundo plano em três computadores diferentes foi concluído.

O primeiro comando cria uma sessão do Windows PowerShell (PSSession) em cada um dos três computadores remotos e os armazena na variável $s.

O segundo comando usa Invoke-Command para executar Start-Job em cada uma das três sessões em $s. Todos os trabalhos são nomeados Date1.

O terceiro comando usa Invoke-Command para executar Wait-Job . Este comando aguarda a conclusão dos trabalhos Date1 em cada computador. Ele armazena a coleção resultante (matriz) de objetos de trabalho na variável $done.

O quarto comando usa a propriedade Count da matriz de objetos de trabalho na variável $done para determinar quantos trabalhos foram concluídos.

Exemplo 3: Determinar quando o primeiro trabalho em segundo plano termina

PS C:\> $s = New-PSSession (Get-Content Machines.txt)
PS C:\> $c = 'Get-EventLog -LogName System | where {$_.EntryType -eq "error" --and $_.Source -eq "LSASRV"} | Out-File Errors.txt'
PS C:\> Invoke-Command -Session $s -ScriptBlock {Start-Job -ScriptBlock {$Using:c}
PS C:\> Invoke-Command -Session $s -ScriptBlock {Wait-Job -Any}

Este exemplo usa o parâmetro Any de Wait-Job para determinar quando o primeiro de muitos trabalhos em segundo plano em execução na sessão atual é concluído. Ele também mostra como usar o cmdlet Wait-Job para aguardar a conclusão dos trabalhos remotos.

O primeiro comando cria um PSSession em cada um dos computadores listados no arquivo Machines.txt e armazena os objetos PSSession na variável $s. O comando usa o cmdlet Get-Content para obter o conteúdo do arquivo. O comando Get-Content é colocado entre parênteses para garantir que seja executado antes do comando New-PSSession.

O segundo comando armazena uma cadeia de caracteres de comando Get-EventLog, entre aspas, na variável $c.

O terceiro comando usa Invoke-Command cmdlet para executar Start-Job em cada uma das sessões do $s. O comando Start-Job inicia um trabalho em segundo plano que executa o comando Get-EventLog na variável $c.

O comando usa o modificador de escopo Usando para indicar que a variável $c foi definida no computador local. O modificador de escopo Usando é introduzido no Windows PowerShell 3.0. Para obter mais informações sobre o Usando modificador de escopo, consulte about_Remote_Variables (https://go.microsoft.com/fwlink/?LinkID=252653).

O quarto comando usa Invoke-Command para executar um comando Wait-Job nas sessões. Ele usa o parâmetro Any para aguardar até que o primeiro trabalho nos computadores remotos seja concluído.

Exemplo 4: Definir um tempo de espera para trabalhos em computadores remotos

PS C:\> $s = New-PSSession Server01, Server02, Server03
PS C:\> $jobs = Invoke-Command -Session $s -ScriptBlock {Start-Job -ScriptBlock {Get-Date}}
PS C:\> $done = Invoke-Command -Session $s -ScriptBlock {Wait-Job -Timeout 30}

Este exemplo mostra como usar o parâmetro Timeout de Wait-Job para definir um tempo máximo de espera para os trabalhos em execução em computadores remotos.

O primeiro comando cria um PSSession em cada um dos três computadores remotos (Server01, Server02 e Server03) e, em seguida, armazena os objetos PSSession na variável $s.

O segundo comando usa Invoke-Command para executar Start-Job em cada um dos objetos PSSession no $s. Ele armazena os objetos de trabalho resultantes na variável $jobs.

O terceiro comando usa Invoke-Command para executar Wait-Job em cada uma das sessões em $s. O comando Wait-Job determina se todos os comandos foram concluídos em 30 segundos. Ele usa o parâmetro Timeout com um valor de 30 para estabelecer o tempo máximo de espera e, em seguida, armazena os resultados do comando na variável $done.

Neste caso, após 30 segundos, apenas o comando no computador Server02 foi concluído. Wait-Job encerra a espera, exibe o prompt de comando e retorna o objeto que representa o trabalho que foi concluído.

A variável $done contém um objeto de trabalho que representa o trabalho executado no Server02.

Exemplo 5: Aguarde até que um dos vários trabalhos termine

PS C:\> Wait-Job -id 1,2,5 -Any

Este comando identifica três trabalhos por seus IDs e aguarda até que qualquer um deles seja concluído. O prompt de comando retorna quando o primeiro trabalho é concluído.

Exemplo 6: Aguarde um período e, em seguida, permita que o trabalho continue em segundo plano

PS C:\> Wait-Job -Name "DailyLog" -Timeout 120

Este comando aguarda 120 segundos (dois minutos) para que o trabalho do DailyLog seja concluído. Se o trabalho não terminar nos próximos dois minutos, o prompt de comando retornará de qualquer maneira e o trabalho continuará a ser executado em segundo plano.

Exemplo 7: Aguarde um trabalho pelo nome

PS C:\> Wait-Job -Name "Job3"

Este comando usa o nome do trabalho para identificar o trabalho pelo qual aguardar.

Exemplo 8: Aguarde trabalhos no computador local iniciados com Start-Job

PS C:\> $j = Start-Job -ScriptBlock {Get-ChildItem *.ps1| where {$_lastwritetime -gt ((Get-Date) - (New-TimeSpan -Days 7))}}
PS C:\> $j | Wait-Job

Este exemplo mostra como usar o cmdlet Wait-Job com trabalhos iniciados no computador local usando Start-Job.

Esses comandos iniciam um trabalho que obtém os arquivos de script do Windows PowerShell que foram adicionados ou atualizados na última semana.

O primeiro comando usa Start-Job para iniciar um trabalho em segundo plano no computador local. O trabalho executa um comando Get-ChildItem que obtém todos os arquivos que têm uma extensão de nome de arquivo .ps1 que foram adicionados ou atualizados na última semana.

O terceiro comando usa Wait-Job para aguardar até que o trabalho seja concluído. Quando o trabalho é concluído, o comando exibe o objeto de trabalho, que contém informações sobre o trabalho.

Exemplo 9: Aguarde trabalhos iniciados em computadores remotos usando Invoke-Command

PS C:\> $s = New-PSSession Server01, Server02, Server03
PS C:\> $j = Invoke-Command -Session $s -ScriptBlock {Get-Process} -AsJob
PS C:\> $j | Wait-Job

Este exemplo mostra como usar Wait-Job com trabalhos iniciados em computadores remotos usando o parâmetro AsJob de Invoke-Command. Ao usar AsJob, o trabalho é criado no computador local e os resultados são retornados automaticamente para o computador local, mesmo que o trabalho seja executado nos computadores remotos.

Este exemplo usa Wait-Job para determinar se um comando Get-Process em execução nas sessões em três computadores remotos foi concluído.

O primeiro comando cria objetos PSSession em três computadores e os armazena na variável $s.

O segundo comando usa Invoke-Command para executar Get-Process em cada uma das três sessões em $s. O comando usa o parâmetro AsJob para executar o comando de forma assíncrona como um trabalho em segundo plano. O comando retorna um objeto de trabalho, assim como os trabalhos iniciados usando Start-Job , e o objeto de trabalho é armazenado na variável $j.

O terceiro comando usa um operador de pipeline (|) para enviar o objeto de trabalho em $j para o cmdlet Wait-Job. Neste caso, não é necessário um comando Invoke-Command , porque o trabalho reside no computador local.

Exemplo 10: Aguarde um trabalho que tenha um ID

PS C:\> Get-Job

Id   Name     State      HasMoreData     Location             Command
--   ----     -----      -----------     --------             -------
1    Job1     Completed  True            localhost,Server01.. get-service
4    Job4     Completed  True            localhost            dir | where

PS C:\> Wait-Job -Id 1

Este comando aguarda o trabalho com um valor de ID de 1.

Parâmetros

-Any

Indica que esse cmdlet exibe o prompt de comando e retorna o objeto de trabalho quando qualquer trabalho é concluído. Por padrão, Wait-Job aguarda até que todos os trabalhos especificados sejam concluídos antes de exibir o prompt.

Tipo:SwitchParameter
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Filter

Especifica uma tabela de condições de hash. Este cmdlet aguarda trabalhos que satisfaçam todas as condições na tabela de hash. Insira uma tabela de hash onde as chaves são propriedades de trabalho e os valores são valores de propriedade de trabalho.

Esse parâmetro funciona apenas em tipos de trabalho personalizados, como trabalhos de fluxo de trabalho e trabalhos agendados. Ele não funciona em trabalhos em segundo plano padrão, como aqueles criados usando o cmdlet Start-Job. Para obter informações sobre o suporte para esse parâmetro, consulte o tópico de ajuda para o tipo de trabalho.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:Hashtable
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Force

Indica que esse cmdlet continua aguardando trabalhos no estado Suspenso ou Desconectado. Por padrão, Wait-Job retorna ou encerra a espera quando os trabalhos estão em um dos seguintes estados:

  • Concluída |
  • Falhou
  • Parou
  • Suspenso
  • Desconectado

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:SwitchParameter
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Id

Especifica uma matriz de IDs de trabalhos pelos quais esse cmdlet aguarda.

O ID é um número inteiro que identifica exclusivamente o trabalho na sessão atual. É mais fácil de lembrar e digitar do que o ID da instância, mas é exclusivo apenas na sessão atual. Você pode digitar um ou mais IDs, separados por vírgulas. Para encontrar a ID de um trabalho, digite Get-Job.

Tipo:Int32[]
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-InstanceId

Especifica uma matriz de IDs de instância de trabalhos pelos quais esse cmdlet aguarda. O padrão é todos os trabalhos.

Um ID de instância é um GUID que identifica exclusivamente o trabalho no computador. Para localizar a ID de instância de um trabalho, use Get-Job.

Tipo:Guid[]
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Job

Especifica os trabalhos pelos quais esse cmdlet aguarda. Insira uma variável que contenha os objetos de trabalho ou um comando que obtenha os objetos de trabalho. Você também pode usar um operador de pipeline para enviar objetos de trabalho para o cmdlet Wait-Job. Por padrão, Trabalho de Espera aguarda todos os trabalhos criados na sessão atual.

Tipo:Job[]
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Name

Especifica nomes amigáveis de trabalhos pelos quais esse cmdlet aguarda.

Tipo:String[]
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-State

Especifica um estado de trabalho. Este cmdlet aguarda apenas trabalhos no estado especificado. Os valores aceitáveis para este parâmetro são:

  • NotStarted
  • Em execução
  • Concluída |
  • Falhou
  • Parou
  • Bloqueado
  • Suspenso
  • Desconectado
  • Suspensão
  • Parar

Para obter mais informações sobre estados de trabalho, consulte de enumeração JobState na biblioteca MSDN.

Tipo:JobState
Valores aceites:NotStarted, Running, Completed, Failed, Stopped, Blocked, Suspended, Disconnected, Suspending, Stopping, AtBreakpoint
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Timeout

Especifica o tempo máximo de espera para cada trabalho em segundo plano, em segundos. O valor padrão, -1, indica que o cmdlet aguarda até que o trabalho seja concluído. O tempo começa quando você envia o comando Wait-Job, não o comando Start-Job.

Se esse tempo for excedido, a espera termina e o prompt de comando retorna, mesmo que o trabalho ainda esteja em execução. O comando não exibe nenhuma mensagem de erro.

Tipo:Int32
Aliases:TimeoutSec
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

Entradas

System.Management.Automation.RemotingJob

Você pode canalizar um objeto de trabalho para este cmdlet.

Saídas

System.Management.Automation.PSRemotingJob

Este cmdlet retorna objetos de trabalho que representam os trabalhos concluídos. Se a espera terminar porque o valor do parâmetro Timeout for excedido, Wait-Job não retornará nenhum objeto.

Notas

  • Por padrão, Wait-Job retorna ou encerra a espera quando os trabalhos estão em um dos seguintes estados:
  • Concluída |
  • Falhou
  • Parou
  • Suspenso
  • Desconectado Para direcionar de trabalho em espera para continuar a aguardar trabalhos suspensos e desconectados, use o parâmetro Force.