Receive-Job
Obtém os resultados dos trabalhos em segundo plano do PowerShell na sessão atual.
Sintaxe
Receive-Job
[-Job] <Job[]>
[[-Location] <string[]>]
[-Keep]
[-NoRecurse]
[-Force]
[-Wait]
[-AutoRemoveJob]
[-WriteEvents]
[-WriteJobInResults]
[<CommonParameters>]Receive-Job
[-Job] <Job[]>
[[-ComputerName] <string[]>]
[-Keep]
[-NoRecurse]
[-Force]
[-Wait]
[-AutoRemoveJob]
[-WriteEvents]
[-WriteJobInResults]
[<CommonParameters>]Receive-Job
[-Job] <Job[]>
[[-Session] <PSSession[]>]
[-Keep]
[-NoRecurse]
[-Force]
[-Wait]
[-AutoRemoveJob]
[-WriteEvents]
[-WriteJobInResults]
[<CommonParameters>]Receive-Job
[-Name] <string[]>
[-Keep]
[-NoRecurse]
[-Force]
[-Wait]
[-AutoRemoveJob]
[-WriteEvents]
[-WriteJobInResults]
[<CommonParameters>]Receive-Job
[-InstanceId] <guid[]>
[-Keep]
[-NoRecurse]
[-Force]
[-Wait]
[-AutoRemoveJob]
[-WriteEvents]
[-WriteJobInResults]
[<CommonParameters>]Receive-Job
[-Id] <int[]>
[-Keep]
[-NoRecurse]
[-Force]
[-Wait]
[-AutoRemoveJob]
[-WriteEvents]
[-WriteJobInResults]
[<CommonParameters>]Description
O Receive-Job cmdlet obtém os resultados de trabalhos em segundo plano do PowerShell, como aqueles iniciados usando o Start-Job cmdlet ou o parâmetro AsJob de qualquer cmdlet. Você pode obter os resultados de todos os trabalhos ou identificar os trabalhos pelo nome, ID, ID da instância, nome do computador, local ou sessão, ou enviando um objeto de trabalho.
Quando você inicia um trabalho em segundo plano do PowerShell, o trabalho é iniciado, mas os resultados não aparecem imediatamente. Em vez disso, o comando retorna um objeto que representa o trabalho em segundo plano. O objeto de trabalho contém informações úteis sobre o trabalho, mas não contém os resultados. Esse método permite que você continue a trabalhar na sessão enquanto o trabalho é executado. Para obter mais informações sobre trabalhos em segundo plano no PowerShell, consulte about_Jobs.
O Receive-Job cmdlet obtém os resultados que foram gerados no momento em que o Receive-Job comando é enviado. Se os resultados ainda não estiverem completos, você poderá executar comandos adicionais Receive-Job para obter os resultados restantes.
Por padrão, os resultados do trabalho são excluídos do sistema quando você os recebe, mas você pode usar o parâmetro Keep para salvar os resultados para que possa recebê-los novamente. Para excluir os resultados do trabalho, execute o Receive-Job comando novamente sem o parâmetro Keep , feche a sessão ou use o Remove-Job cmdlet para excluir o trabalho da sessão.
A partir do Windows PowerShell 3.0, Receive-Job também obtém os resultados de tipos de trabalho personalizados, como trabalhos de fluxo de trabalho e instâncias de trabalhos agendados. Para habilitar Receive-Job para obter os resultados um tipo de trabalho personalizado, importe o módulo que suporta o tipo de trabalho personalizado para a sessão antes de executar um Receive-Job comando, usando o Import-Module cmdlet 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: Obter resultados para um trabalho específico
$job = Start-Job -ScriptBlock {Get-Process}
Start-Sleep -Seconds 1
Receive-Job -Job $jobEsses comandos usam o parâmetro Job de Receive-Job para obter os resultados de um trabalho específico.
O primeiro comando inicia um trabalho com Start-Job e armazena o objeto de trabalho na $job variável.
O segundo comando usa o Receive-Job cmdlet para obter os resultados do trabalho.
Ele usa o parâmetro Job para especificar o trabalho.
Exemplo 2: Usar o parâmetro Keep
$job = Start-Job -ScriptBlock {Get-Service dhcp, fakeservice}
Start-Sleep -Seconds 1
$job | Receive-Job -Keep
Cannot find any service with service name 'fakeservice'.
+ CategoryInfo : ObjectNotFound: (fakeservice:String) [Get-Service], ServiceCommandException
+ FullyQualifiedErrorId : NoServiceFoundForGivenName,Microsoft.PowerShell.Commands.GetServiceCommand
+ PSComputerName : localhost
Status Name DisplayName
------ ---- -----------
Running dhcp DHCP Client
$job | Receive-Job -Keep
Cannot find any service with service name 'fakeservice'.
+ CategoryInfo : ObjectNotFound: (fakeservice:String) [Get-Service], ServiceCommandException
+ FullyQualifiedErrorId : NoServiceFoundForGivenName,Microsoft.PowerShell.Commands.GetServiceCommand
+ PSComputerName : localhost
Status Name DisplayName
------ ---- -----------
Running dhcp DHCP ClientEste exemplo armazena $job um trabalho na variável e canaliza o trabalho para o Receive-Job cmdlet. O -Keep parâmetro também é usado para permitir que todos os dados de fluxo agregados sejam recuperados novamente após a primeira visualização.
Exemplo 3: Obter resultados de vários trabalhos em segundo plano
Quando você usa o parâmetro AsJob de para iniciar um trabalho, o objeto de Invoke-Command trabalho é criado no computador local, mesmo que o trabalho seja executado nos computadores remotos. Como resultado, você usa comandos locais para gerenciar o trabalho.
Além disso, quando você usa AsJob, o PowerShell retorna um objeto de trabalho que contém um trabalho filho para cada trabalho iniciado. Nesse caso, o objeto de trabalho contém três trabalhos filho, um para cada trabalho em cada computador remoto.
# Use the Invoke-Command cmdlet with the -AsJob parameter to start a background job that
# runs a Get-Service command on three remote computers. Store the resulting job object in
# the $j variable
$j = Invoke-Command -ComputerName Server01, Server02, Server03 -ScriptBlock {Get-Service} -AsJob
# Display the value of the **ChildJobs** property of the job object in $j. The display
# shows that the command created three child jobs, one for the job on each remote
# computer. You could also use the -IncludeChildJobs parameter of the Get-Job cmdlet.
$j.ChildJobs
Id Name State HasMoreData Location Command
-- ---- ----- ----------- -------- -------
2 Job2 Completed True Server01 Get-Service
3 Job3 Completed True Server02 Get-Service
4 Job4 Completed True Server03 Get-Service
# Use the Receive-Job cmdlet to get the results of just the Job3 child job that ran on the
# Server02 computer. Use the *Keep* parameter to allow you to view the aggregated stream
# data more than once.
Receive-Job -Name Job3 -Keep
Status Name DisplayName PSComputerName
------ ----------- ----------- --------------
Running AeLookupSvc Application Experience Server02
Stopped ALG Application Layer Gateway Service Server02
Running Appinfo Application Information Server02
Running AppMgmt Application Management Server02Exemplo 4: Obter resultados de trabalhos em segundo plano em vários computadores remotos
# Use the New-PSSession cmdlet to create three user-managed PSSessions on three servers,
# and save the sessions in the $s variable.
$s = New-PSSession -ComputerName Server01, Server02, Server03
# Use Invoke-Command run a Start-Job command in each of the PSSessions in the $s variable.
# The code creates a new job with a custom name to each server. The job outputs the
# datetime from each server. Save the job objects in the $j variable.
$invokeCommandSplat = @{
Session = $s
ScriptBlock = {
Start-Job -Name $('MyJob-' +$env:COMPUTERNAME) -ScriptBlock {
(Get-Date).ToString()
}
}
}
$j = Invoke-Command @invokeCommandSplat
# To confirm that these job objects are from the remote machines, run Get-Job to show no
# local jobs running.
Get-Job`
# Display the three job objects in $j. Note that the Localhost location is not the local
# computer, but instead localhost as it relates to the job on each Server.
$j
Id Name State HasMoreData Location Command
-- ---- ----- ----------- -------- -------
1 MyJob-Server01 Completed True Localhost (Get-Date).ToString()
2 MyJob-Server02 Completed True Localhost (Get-Date).ToString()
3 MyJob-Server03 Completed True Localhost (Get-Date).ToString()
# Use Invoke-Command to run a Receive-Job command in each of the sessions in the $s
# variable and save the results in the $results variable. The Receive-Job command must be
# run in each session because the jobs were run locally on each server.
$results = Invoke-Command -Session $s -ScriptBlock {
Receive-Job -Name $('MyJob-' +$env:COMPUTERNAME)
}
3/22/2021 7:41:47 PM
3/22/2021 7:41:47 PM
3/22/2021 9:41:47 PMEste exemplo mostra como obter os resultados de trabalhos em segundo plano executados em três computadores remotos. Ao contrário do exemplo anterior, usar Invoke-Command para executar o Start-Job comando realmente iniciou três trabalhos independentes em cada um dos três computadores. Como resultado, o comando retornou três objetos de trabalho representando três trabalhos executados localmente em três computadores diferentes.
Exemplo 5: Aceder a empregos subordinados
O -Keep parâmetro preserva o estado dos fluxos agregados de um trabalho para que ele possa ser exibido novamente. Sem esse parâmetro, todos os dados de fluxo agregados são apagados quando o trabalho é recebido.
Para obter mais informações, consulte about_Job_Details
Nota
Os fluxos agregados incluem os fluxos de todos os empregos infantis. Você ainda pode acessar os fluxos individuais de dados por meio do objeto de trabalho e dos objetos de trabalho filho.
Start-Job -Name TestJob -ScriptBlock {dir C:\, Z:\}
# Without the Keep parameter, aggregated child job data is displayed once.
# Then destroyed.
Receive-Job -Name TestJob
Directory: C:\
Mode LastWriteTime Length Name
---- ------------- ------ ----
d-r--- 1/24/2019 7:11 AM Program Files
d-r--- 2/13/2019 8:32 AM Program Files (x86)
d-r--- 10/3/2018 11:47 AM Users
d----- 2/7/2019 1:52 AM Windows
Cannot find drive. A drive with the name 'Z' does not exist.
+ CategoryInfo : ObjectNotFound: (Z:String) [Get-ChildItem], DriveNotFoundException
+ FullyQualifiedErrorId : DriveNotFound,Microsoft.PowerShell.Commands.GetChildItemCommand
+ PSComputerName : localhost
# It would seem that the child job data is gone.
Receive-Job -Name TestJob
# Using the object model, you can still retrieve child job data and streams.
$job = Get-Job -Name TestJob
$job.ChildJobs[0].Error
Cannot find drive. A drive with the name 'Z' does not exist.
+ CategoryInfo : ObjectNotFound: (Z:String) [Get-ChildItem], DriveNotFoundException
+ FullyQualifiedErrorId : DriveNotFound,Microsoft.PowerShell.Commands.GetChildItemCommand
+ PSComputerName : localhostParâmetros
-AutoRemoveJob
Indica que esse cmdlet exclui o trabalho depois que ele retorna os resultados do trabalho. Se o trabalho tiver mais resultados, ele ainda será excluído, mas Receive-Job exibirá uma mensagem.
Este parâmetro funciona apenas em tipos de trabalho personalizados. Ele foi projetado para instâncias de tipos de trabalho que salvam o trabalho ou o tipo fora da sessão, como instâncias de trabalhos agendados.
Este parâmetro não pode ser usado sem o parâmetro Wait .
Esse parâmetro foi introduzido no Windows PowerShell 3.0.
| Tipo: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | False |
-ComputerName
Especifica uma matriz de nomes de computadores.
Este parâmetro seleciona entre os resultados do trabalho armazenados no computador local. Ele não obtém dados para trabalhos executados em computadores remotos. Para obter resultados de trabalho armazenados em computadores remotos, use o Invoke-Command cmdlet para executar um Receive-Job comando remotamente.
| Tipo: | String[] |
| Aliases: | Cn |
| Position: | 1 |
| Default value: | All computers available |
| Necessário: | False |
| Aceitar entrada de pipeline: | True |
| Aceitar carateres universais: | True |
-Force
Indica que esse cmdlet continuará aguardando se os trabalhos estiverem no estado Suspenso ou Desconectado . Por padrão, o parâmetro Wait de Receive-Job retorna ou encerra a espera quando os trabalhos estão em um dos seguintes estados:
- Concluído
- Com falhas
- Parado
- Suspenso
- Desconectado.
O parâmetro Force é válido somente quando o parâmetro Wait também é usado no comando.
Esse parâmetro foi introduzido no Windows PowerShell 3.0.
| Tipo: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | False |
-Id
Especifica uma matriz de IDs. Este cmdlet obtém os resultados de trabalhos com as IDs especificadas.
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 uma ou mais IDs separadas por vírgulas. Para encontrar a ID de um trabalho, use 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. Este cmdlet obtém os resultados de trabalhos com as IDs de instância especificadas.
Um ID de instância é um GUID que identifica exclusivamente o trabalho no computador. Para localizar a ID da instância de um trabalho, use o Get-Job cmdlet.
| Tipo: | Guid[] |
| Position: | 0 |
| Default value: | All instances |
| Necessário: | True |
| Aceitar entrada de pipeline: | True |
| Aceitar carateres universais: | False |
-Job
Especifica o trabalho para o qual os resultados estão sendo recuperados.
Insira uma variável que contenha o trabalho ou um comando que obtenha o trabalho. Você também pode canalizar um objeto de trabalho para Receive-Job.
| Tipo: | Job[] |
| Position: | 0 |
| Default value: | None |
| Necessário: | True |
| Aceitar entrada de pipeline: | True |
| Aceitar carateres universais: | False |
-Keep
Indica que esse cmdlet salva os dados de fluxo agregados no sistema, mesmo depois de recebê-los. Por padrão, os dados de fluxo agregados são apagados depois de visualizados com Receive-Job.
Fechar a sessão ou remover o trabalho com o Remove-Job cmdlet também exclui dados de fluxo agregados.
| Tipo: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | False |
-Location
Especifica uma matriz de locais. Este cmdlet obtém apenas os resultados de trabalhos nos locais especificados.
| Tipo: | String[] |
| Position: | 1 |
| Default value: | All locations |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | False |
-Name
Especifica uma matriz de nomes amigáveis. Este cmdlet obtém os resultados de trabalhos que têm os nomes especificados. Caracteres curinga são suportados.
| Tipo: | String[] |
| Position: | 0 |
| Default value: | None |
| Necessário: | True |
| Aceitar entrada de pipeline: | True |
| Aceitar carateres universais: | True |
-NoRecurse
Indica que esse cmdlet obtém resultados somente do trabalho especificado. Por padrão, Receive-Job também obtém os resultados de todos os trabalhos filhos do trabalho especificado.
| Tipo: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | False |
-Session
Especifica uma matriz de sessões. Este cmdlet obtém os resultados de trabalhos que foram executados na sessão especificada do PowerShell (PSSession). Insira uma variável que contenha o PSSession ou um comando que obtenha o PSSession, como um Get-PSSession comando.
| Tipo: | PSSession[] |
| Position: | 1 |
| Default value: | All sessions |
| Necessário: | False |
| Aceitar entrada de pipeline: | True |
| Aceitar carateres universais: | False |
-Wait
Indica que esse cmdlet suprime o prompt de comando até que todos os resultados do trabalho sejam recebidos. Por padrão, Receive-Job retorna imediatamente os resultados disponíveis.
Por padrão, o parâmetro Wait aguarda até que o trabalho esteja em um dos seguintes estados:
- Concluído
- Com falhas
- Parado
- Suspenso
- Desligado
Para direcionar o parâmetro Wait para continuar aguardando se o estado do trabalho for Suspended ou Disconnected, use o parâmetro Force junto com o parâmetro Wait.
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 |
-WriteEvents
Indica que esse cmdlet relata alterações no estado do trabalho enquanto aguarda a conclusão do trabalho.
Esse parâmetro é válido somente quando o parâmetro Wait é usado no comando e o parâmetro Keep é omitido.
Esse parâmetro foi introduzido no Windows PowerShell 3.0.
| Tipo: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | False |
-WriteJobInResults
Indica que esse cmdlet retorna o objeto de trabalho seguido pelos resultados.
Esse parâmetro é válido somente quando o parâmetro Wait é usado no comando e o parâmetro Keep é omitido.
Esse parâmetro foi introduzido no Windows PowerShell 3.0.
| Tipo: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Necessário: | False |
| Aceitar entrada de pipeline: | False |
| Aceitar carateres universais: | False |
Entradas
Você pode canalizar objetos de trabalho para este cmdlet.
Saídas
Este cmdlet retorna os resultados dos comandos no trabalho.
Notas
O PowerShell inclui os seguintes aliases para Receive-Job:
- Todas as plataformas:
rcjb
