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