Partilhar via

Receive-Job

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

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
       [-Keep]
       [-NoRecurse]
       [-Force]
       [-Wait]
       [-AutoRemoveJob]
       [-WriteEvents]
       [-WriteJobInResults]
       [-Name] <String[]>
       [<CommonParameters>]
Receive-Job
       [-Keep]
       [-NoRecurse]
       [-Force]
       [-Wait]
       [-AutoRemoveJob]
       [-WriteEvents]
       [-WriteJobInResults]
       [-InstanceId] <Guid[]>
       [<CommonParameters>]
Receive-Job
       [-Keep]
       [-NoRecurse]
       [-Force]
       [-Wait]
       [-AutoRemoveJob]
       [-WriteEvents]
       [-WriteJobInResults]
       [-Id] <Int32[]>
       [<CommonParameters>]

Description

O cmdlet Receive-Job obtém os resultados de trabalhos em segundo plano do PowerShell, como aqueles iniciados usando o cmdlet Start-Job 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 cmdlet Receive-Job obtém os resultados que foram gerados no momento em que o comando Receive-Job é enviado. Se os resultados ainda não estiverem completos, você poderá executar comandos Receive-Job adicionais 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 e recebê-los novamente. Para excluir os resultados do trabalho, execute o comando Receive-Job novamente sem o parâmetro Keep, feche a sessão ou use o cmdlet Remove-Job 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 permitir que Receive-Job obtenha os resultados de um tipo de trabalho personalizado, importe o módulo que suporta o tipo de trabalho personalizado para a sessão antes de executar um comando Receive-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: Obter resultados para um trabalho específico

$job = Start-Job -ScriptBlock {Get-Process}
Receive-Job -Job $job

Esses 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 variável $job.

O segundo comando usa o cmdlet Receive-Job 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}
$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 Client

Este exemplo armazena um trabalho na variável $job e canaliza o trabalho para o cmdlet Receive-Job. O parâmetro -Keep 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 Invoke-Command para iniciar um trabalho, o objeto de 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             Server02

Exemplo 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 job outputs the ComputerName of each server.
# Save the job objects in the $j variable.
$j = Invoke-Command -Session $s -ScriptBlock {Start-Job -ScriptBlock {$env:COMPUTERNAME}}
# 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    Job1     Completed  True          Localhost  $env:COMPUTERNAME
2    Job2     Completed  True          Localhost  $env:COMPUTERNAME
3    Job3     Completed  True          Localhost  $env:COMPUTERNAME

# 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 -Job $Using:j}

Server01
Server02
Server03

Este 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 comando Start-Job 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.

Observação

No último comando, como $j é uma variável local, o bloco de script usa o modificador de escopo Usando para identificar a variável $j. Para obter mais informações sobre o Usando modificador de escopo, consulte about_Remote_Variables.

Exemplo 5: Aceder a empregos subordinados

O parâmetro -Keep preserva o estado dos fluxos agregados de um trabalho para que ele possa ser visualizado 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

Observação

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        : localhost

Parâ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 cmdlet Invoke-Command para executar um comando Receive-Job 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ída |
  • Falhou
  • Parou
  • 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 cmdlet Get-Job.

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 cmdlet Remove-Job 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 do PowerShell especificada (PSSession). Insira uma variável que contenha o PSSession ou um comando que obtenha o PSSession, como um comando Get-PSSession.

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ída |
  • Falhou
  • Parou
  • Suspenso
  • Desconectado.

Para direcionar o parâmetro Wait para continuar aguardando se o estado do trabalho for Suspended ou Disconnected, use o parâmetro Force juntamente 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

Job

Você pode canalizar objetos de trabalho para este cmdlet.

Saídas

PSObject

Este cmdlet retorna os resultados dos comandos no trabalho.