TÓPICO

about_Jobs

DESCRIÇÃO RESUMIDA
Fornece informações sobre como os trabalhos de segundo plano do
Windows PowerShell executam um comando ou expressão em segundo
plano sem interação com a sessão atual.

DESCRIÇÃO LONGA
Este tópico explica como executar trabalhos de segundo plano no
Windows PowerShell em um computador local. Para obter informações
sobre a execução de trabalhos de segundo plano em computadores
remotos, consulte about_Remote_Jobs.

Quando você inicia um trabalho de segundo plano, o prompt de

comando é retornado imediatamente, mesmo se o trabalho ainda
demorar um longo tempo para ser concluído. Você pode continuar a
trabalhar na sessão sem interrupções enquanto o trabalho é executado.

Importante: os trabalhos de segundo plano iniciados utilizando o

parâmetro Start-Job ou AsJob de Invoke-Command contam com a
infraestrutura remota do Windows PowerShell. Para usar esses
recursos, o Windows PowerShell deve ser configurado para execução
remota, mesmo se o trabalho de segundo plano for executado
somente no computador local. Para obter mais informações,
consulte about_Remote_Requirements.

COMO INICIAR UM TRABALHO EM UM COMPUTADOR LOCAL

Para iniciar um trabalho de segundo plano em um computador local,
use o cmdlet Start-Job.

Para gravar um comando Start-Job, coloque o comando que o

trabalho executa entre chaves ( { } ). Use o parâmetro
ScriptBlock para especificar o comando.

O comando a seguir inicia um trabalho de segundo plano que

executa um comando Get-Process no computador local.

start-job -scriptblock {get-process}

O comando Start-Job retorna um objeto que representa o trabalho.

O objeto de trabalho contém informações úteis sobre o trabalho,
mas não contém os resultados do trabalho.

Salve o objeto de trabalho em uma variável e, em seguida, use-o

com outros cmdlets para gerenciar o trabalho de segundo plano. O
comando a seguir inicia um objeto de trabalho e salva o objeto de
trabalho resultante na variável $job.

$job = start-job -scriptblock {get-process}

Você também pode usar o cmdlet Get-Job para obter objetos que
representam os trabalhos iniciados na sessão atual. O Get-Job
retorna o mesmo objeto de trabalho que Start-Job.

OBTENDO OBJETOS DE TRABALHO

 Para obter objetos que representam os trabalhos de segundo plano
que foram iniciados na sessão atual, use o cmdlet Get-Job. Sem
parâmetros, Get-Job retorna todos os trabalhos iniciados na
sessão atual.

Por exemplo, o comando a seguir obtém os trabalhos na sessão atual.

get-job

Id Name State HasMoreData Location Command

-- ---- ----- ----------- -------- -------
1 Job1 Running True localhost get-process

Você também pode salvar o objeto de trabalho em uma variável e

usá-lo para representar o trabalho em um comando posterior. O
comando a seguir obtém o trabalho com ID 1 e o salva na variável $job.

$job = get-job -id 1

O objeto de trabalho contém o estado do trabalho que indica se o

trabalho foi concluído. Um trabalho concluído tem um estado
"Complete" ou "Failed". Um trabalho também pode ser bloqueado ou
executado.

get-job

Id Name State HasMoreData Location Command

-- ---- ----- ----------- -------- -------
1 Job1 Complete True localhost get-process

OBTENDO OS RESULTADOS DE UM TRABALHO

Quando você executa um trabalho de segundo plano, os resultados

não aparecem imediatamente. Em vez disso, o cmdlet Start-Job
retorna um objeto de trabalho que representa o trabalho, mas ele
não contém os resultados. Para obter os resultados de um trabalho
de segundo plano, use o cmdlet Receive-Job.

O comando a seguir usa o cmdlet Receive-Job para obter os

resultados do trabalho. Ele usa um objeto de trabalho salvo na
variável $job para identificar o trabalho.

receive-job -job $job

O cmdlet Receive-Job retorna os resultados do trabalho.

Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName

------- ------ ----- ----- ----- ------ ----------------
103 4 11328 9692 56 1176 audiodg
804 14 12228 14108 100 101.74 1740 CcmExec
 668 7 2672 6168 104 32.26 488 csrss
...

Você também pode salvar os resultados de um trabalho em uma

variável. O comando a seguir salva os resultados do trabalho na
variável $job para a variável $results.

$results = receive-job -job $job

E você pode salvar os resultados do trabalho em um arquivo

utilizando o operador de redirecionamento (>) ou o cmdlet
Out-File. O comando a seguir usa o
operador de redirecionamento para salvar os resultados do
trabalho na variável $job no arquivo Results.txt.

receive-job -job $job > results.txt

OBTENDO E MANTENDO RESULTADOS DE TRABALHO PARCIAIS

O cmdlet Receive-Job retorna os resultados de um trabalho de

segundo plano. Se o trabalho estiver concluído, Receive-Job
retornará os resultados completos do trabalho. Se o trabalho
ainda estiver em execução, Receive-Job obtém os resultados que
foram gerados posteriormente. Você pode executar os comandos
Receive-Job novamente para obter os resultados restantes.

Quando o Receive-Job retorna os resultados, por padrão, ele

exclui os resultados do cache em que os trabalhos estão
armazenados. Se você executar outro comando Receive-Job, obterá
somente os resultados que ainda não foram recebidos.

Os comandos a seguir mostram os resultados dos comandos

Receive-Job executados antes da conclusão do trabalho.

C:\PS> receive-job -job $job

Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName

------- ------ ----- ----- ----- ------ --------------
103 4 11328 9692 56 1176 audiodg
804 14 12228 14108 100 101.74 1740 CcmExec

C:\PS> receive-job -job $job

Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName

------- ------ ----- ----- ----- ------ --------------
68 3 2632 664 29 0.36 1388 ccmsetup
749 22 21468 19940 203 122.13 3644 communicator
905 7 2980 2628 34 197.97 424 csrss
1121 25 28408 32940 174 430.14 3048 explorer

Para impedir que o Receive-Job exclua os resultados do trabalho

que ele retornou, use o parâmetro Keep. Consequentemente, o
 Receive-Job retorna todos os resultados que foram gerados até
aquele momento.

Os comandos a seguir mostram o efeito do uso do parâmetro Keep em

um trabalho que ainda não está concluído.

C:\PS> receive-job -job $job -keep

Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName

------- ------ ----- ----- ----- ------ --------------
103 4 11328 9692 56 1176 audiodg
804 14 12228 14108 100 101.74 1740 CcmExec

C:\PS> receive-job -job $job -keep

Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName

------- ------ ----- ----- ----- ------ --------------
103 4 11328 9692 56 1176 audiodg
804 14 12228 14108 100 101.74 1740 CcmExec
68 3 2632 664 29 0.36 1388 ccmsetup
749 22 21468 19940 203 122.13 3644 communicator
905 7 2980 2628 34 197.97 424 csrss
1121 25 28408 32940 174 430.14 3048 explorer

AGUARDANDO RESULTADOS

Se você executar um comando que demora um longo período para ser

concluído, poderá usar as propriedades do objeto de trabalho para
determinar quando o trabalho é concluído. O comando a seguir usa
o objeto Get-Job para obter todos os trabalhos de segundo plano
na sessão atual.

get-job

O resultado aparece na tabela. O status do trabalho é exibido na

coluna State.

Id Name State HasMoreData Location Command

-- ---- ----- ----------- -------- -------
1 Job1 Complete True localhost get-process
2 Job2 Running True localhost get-eventlog -log syst...
3 Job3 Complete True localhost dir -path c:\* -recurse

Nesse caso, a propriedade State revela que o Job2 ainda está em

execução. Se você usou o cmdlet Receive-Job para obter os
resultados de trabalho agora, os resultados ficariam incompletos.
Você pode usar o cmdlet Receive-Job várias vezes para obter todos
os resultados. Por padrão, sempre que usá-lo, você obtém somente
os resultados que ainda não foram recebidos, mas você pode usar o
parâmetro Keep do cmdlet Receive-Job para manter os resultados,
embora já tenham sido recebidos.

Neste momento, você pode gravar os resultados em um arquivo e, em

seguida, anexá-lo aos resultados recebidos recentemente, conforme
 eles chegam. Ou você pode aguardar e verificar o estado desse
trabalho posteriormente.

Também é possível usar o cmdlet Wait-Job para aguardar qualquer

um ou todos os resultados de trabalho. O Wait-Job permite
aguardar um trabalho específico, todos os trabalhos ou qualquer
um dos trabalhos a serem concluídos.

O comando a seguir usa o cmdlet Wait-Job para aguardar um

trabalho com ID 10.

wait-job -ID 10

Consequentemente, o prompt do Windows PowerShell é suprimido até

que o trabalho esteja concluído.

Você também pode aguardar por um período predeterminado. Esse

comando usar o parâmetro Timeout para limitar a espera em 120
segundos. Quando o tempo expira, o prompt de comando é retornado,
mas o trabalho continua a ser executado no segundo plano.

wait-job -ID 10 -timeout 120

PARANDO UM TRABALHO

Para parar um trabalho de segundo plano, use o cmdlet Stop-Job. O

comando a seguir inicia um trabalho para obter cada entrada no
log de eventos do sistema. Ele salva o objeto de trabalho na
variável $job.

$job = start-job -scriptblock {get-eventlog -log system}

O comando a seguir para o trabalho. Ele usa um operador de

pipeline (|) para enviar o trabalho na variável $job para Stop-Job.

$job | stop-job

EXCLUINDO UM TRABALHO

Para excluir um trabalho de segundo plano, use o cmdlet Remove-Job.

O comando a seguir exclui o trabalho da variável $job.

remove-job -job $job

INVESTIGANDO UM TRABALHO COM FALHA

Para descobrir porque um trabalho falhou, use a subpropriedade

Reason do objeto de trabalho.

O comando a seguir inicia um trabalho sem as credenciais

exigidas. Ele salva o objeto de trabalho na variável $job.

$job = start-job -scriptblock {new-item -path HKLM:\Software\MyCompany}

Id Name State HasMoreData Location Command

 -- ---- ----- ----------- -------- -------
1 Job1 Failed False localhost new-item -path HKLM:\S...

O comando a seguir usa a propriedade Reason para localizar o erro

que causou a falha no trabalho.

$job.ChildJobs[0].JobStateInfo.Reason

Nesse caso, o trabalho falhou porque o computador remoto exigiu

credenciais explícitas para executar o comando. O valor da
propriedade Reason é:

Falha ao conectar ao servidor remoto com a seguinte mensagem

de erro: Acesso negado.

OS CMDLETS DE TRABALHO

Start-Job Inicia um trabalho de segundo plano em um

computador local.

Get-Job Obtém os trabalhos de segundo plano iniciados

na sessão atual.

Receive-Job Obtém os resultados dos trabalhos de segundo plano.

Stop-Job Para um trabalho de segundo plano.

Wait-Job Suprime o prompt de comando até a conclusão de um

ou todos os trabalhos.

Remove-Job Exclui um trabalho de segundo plano.

Invoke-Command O parâmetro AsJob executa qualquer comando como

um trabalho de segundo plano em um computador remoto.
Você também pode usar o Invoke-Command para executar
qualquer comando de trabalho remotamente, incluindo um
comando Start-Job.

CONSULTE TAMBÉM
about_Remote_Jobs
about_Job_Details
about_Remote
about_PSSessions
Start-Job
Get-Job
Receive-Job
Stop-Job
Wait-Job
Remove-Job
Invoke-Command