Receive-Job

Módulo:

Microsoft.PowerShell.Core Module

Obtém os resultados dos trabalhos em segundo plano do PowerShell na sessão atual.

Sintaxe

Location (Padrão)

Receive-Job
    [-Job] <Job[]>
    [[-Location] <string[]>]
    [-Keep]
    [-NoRecurse]
    [-Force]
    [-Wait]
    [-AutoRemoveJob]
    [-WriteEvents]
    [-WriteJobInResults]
    [<CommonParameters>]

ComputerName

Receive-Job
    [-Job] <Job[]>
    [[-ComputerName] <string[]>]
    [-Keep]
    [-NoRecurse]
    [-Force]
    [-Wait]
    [-AutoRemoveJob]
    [-WriteEvents]
    [-WriteJobInResults]
    [<CommonParameters>]

Session

Receive-Job
    [-Job] <Job[]>
    [[-Session] <PSSession[]>]
    [-Keep]
    [-NoRecurse]
    [-Force]
    [-Wait]
    [-AutoRemoveJob]
    [-WriteEvents]
    [-WriteJobInResults]
    [<CommonParameters>]

NameParameterSet

Receive-Job
    [-Name] <string[]>
    [-Keep]
    [-NoRecurse]
    [-Force]
    [-Wait]
    [-AutoRemoveJob]
    [-WriteEvents]
    [-WriteJobInResults]
    [<CommonParameters>]

InstanceIdParameterSet

Receive-Job
    [-InstanceId] <guid[]>
    [-Keep]
    [-NoRecurse]
    [-Force]
    [-Wait]
    [-AutoRemoveJob]
    [-WriteEvents]
    [-WriteJobInResults]
    [<CommonParameters>]

SessionIdParameterSet

Receive-Job
    [-Id] <int[]>
    [-Keep]
    [-NoRecurse]
    [-Force]
    [-Wait]
    [-AutoRemoveJob]
    [-WriteEvents]
    [-WriteJobInResults]
    [<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 trabalhos por seu 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 concluídos, 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 para que você possa recebê-los novamente. Para excluir os resultados do trabalho, execute o comando Receive-Job novamente sem o parâmetro Manter, 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 habilitar Receive-Job obter os resultados de um tipo de trabalho personalizado, importe o módulo que dá suporte ao tipo de trabalho personalizado para a sessão antes de executar um comando Receive-Job, usando o cmdlet Import-Module 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 $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}
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 Client

Este exemplo armazena um trabalho na variável $job e redireciona 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 exibiçã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 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 PM

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 que representam três trabalhos executados localmente em três computadores diferentes.

Exemplo 5: Acessar trabalhos filho

O parâmetro -Keep 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

Observação

Os fluxos agregados incluem os fluxos de todos os trabalhos filho. 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, o trabalho ainda será excluído, mas Receive-Job exibirá uma mensagem.

Esse 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.

Esse parâmetro não pode ser usado sem o parâmetro Wait.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

(All)

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

-ComputerName

Especifica uma matriz de nomes de computadores.

Esse 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.

Propriedades do parâmetro

Tipo:	String[]
Valor padrão:	All computers available
Dá suporte a curingas:	True
DontShow:	False
Aliases:	Cn

Conjuntos de parâmetros

ComputerName

Cargo:	1
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	True
Valor dos argumentos restantes:	False

-Force

Indica que esse cmdlet continua aguardando se os trabalhos estão no estado de 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
• Falha
• 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.

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

(All)

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

-Id

Especifica uma matriz de IDs. Esse cmdlet obtém os resultados de trabalhos com as IDs especificadas.

A ID é um número inteiro que identifica exclusivamente o trabalho na sessão atual. é mais fácil de lembrar e digitar do que a ID da instância, mas ela é exclusiva apenas na sessão atual. Você pode digitar uma ou mais IDs separadas por vírgulas. Para localizar a ID de um trabalho, use Get-Job.

Propriedades do parâmetro

Tipo:	Int32[]
Valor padrão:	None
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

SessionIdParameterSet

Cargo:	0
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	True
Valor dos argumentos restantes:	False

-InstanceId

Especifica uma matriz de IDs de instância. Esse cmdlet obtém os resultados de trabalhos com as IDs de instância especificadas.

Uma 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.

Propriedades do parâmetro

Tipo:	Guid[]
Valor padrão:	All instances
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

InstanceIdParameterSet

Cargo:	0
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	True
Valor dos argumentos restantes:	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 obtém o trabalho. Você também pode canalizar um objeto de trabalho para Receive-Job.

Propriedades do parâmetro

Tipo:	Job[]
Valor padrão:	None
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

Location

Cargo:	0
Obrigatório:	True
Valor do pipeline:	True
Valor do pipeline pelo nome da propriedade:	True
Valor dos argumentos restantes:	False

Session

Cargo:	0
Obrigatório:	True
Valor do pipeline:	True
Valor do pipeline pelo nome da propriedade:	True
Valor dos argumentos restantes:	False

ComputerName

Cargo:	0
Obrigatório:	True
Valor do pipeline:	True
Valor do pipeline pelo nome da propriedade:	True
Valor dos argumentos restantes:	False

-Keep

Indica que esse cmdlet salva os dados de fluxo agregados no sistema, mesmo depois de você tê-los recebido. Por padrão, os dados de fluxo agregados são apagados após exibidos com Receive-Job.

Fechar a sessão ou remover o trabalho com o cmdlet Remove-Job também exclui dados de fluxo agregados.

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

(All)

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

-Location

Especifica uma matriz de locais. Esse cmdlet obtém apenas os resultados de trabalhos nos locais especificados.

Propriedades do parâmetro

Tipo:	String[]
Valor padrão:	All locations
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

Location

Cargo:	1
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

-Name

Especifica uma matriz de nomes amigáveis. Esse cmdlet obtém os resultados de trabalhos que têm os nomes especificados. Há suporte para caracteres curinga.

Propriedades do parâmetro

Tipo:	String[]
Valor padrão:	None
Dá suporte a curingas:	True
DontShow:	False

Conjuntos de parâmetros

NameParameterSet

Cargo:	0
Obrigatório:	True
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	True
Valor dos argumentos restantes:	False

-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 filho do trabalho especificado.

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

(All)

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

-Session

Especifica uma matriz de sessões. Esse cmdlet obtém os resultados dos trabalhos que foram executados na sessão especificada do PowerShell (PSSession). Insira uma variável que contenha o PSSession ou um comando que obtém oPSSession , como um comando .

Propriedades do parâmetro

Tipo:	PSSession[]
Valor padrão:	All sessions
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

Session

Cargo:	1
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	True
Valor dos argumentos restantes:	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
• Falha
• Parado
• Suspenso
• Desconectado

Para direcionar o parâmetro Wait para continuar aguardando se o estado do trabalho estiver Suspenso ou Desconectado, use o parâmetro Force junto com o parâmetro Wait.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	None
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

(All)

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	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.

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

(All)

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	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.

Propriedades do parâmetro

Tipo:	SwitchParameter
Valor padrão:	False
Dá suporte a curingas:	False
DontShow:	False

Conjuntos de parâmetros

(All)

Cargo:	Named
Obrigatório:	False
Valor do pipeline:	False
Valor do pipeline pelo nome da propriedade:	False
Valor dos argumentos restantes:	False

CommonParameters

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Entradas

Job

Você pode redirecionar objetos de trabalho para este cmdlet.

Saídas

PSObject

Esse cmdlet retorna os resultados dos comandos no trabalho.

Observações

O PowerShell inclui os seguintes aliases para Receive-Job:

• Todas as plataformas:
  • rcjb

Links Relacionados

• Get-Job
• Invoke-Command
• Remove-Job
• Start-Job
• Stop-Job
• Wait-Job