Suspend-Job

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

Interrompe temporariamente tarefas de fluxo de trabalho.

Sintaxe

Suspend-Job
       [-Force]
       [-Wait]
       [-Id] <Int32[]>
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Suspend-Job
       [-Job] <Job[]>
       [-Force]
       [-Wait]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Suspend-Job
       [-Force]
       [-Wait]
       [-Name] <String[]>
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Suspend-Job
       [-Force]
       [-Wait]
       [-InstanceId] <Guid[]>
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Suspend-Job
       [-Force]
       [-Wait]
       [-Filter] <Hashtable>
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Suspend-Job
       [-Force]
       [-Wait]
       [-State] <JobState>
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]

Description

O Suspend-Job cmdlet suspende trabalhos de fluxo de trabalho. Suspender significa interromper ou pausar temporariamente um trabalho de fluxo de trabalho. Este cmdlet permite que os usuários que estão executando fluxos de trabalho suspendam o fluxo de trabalho. Ele complementa a atividade Suspend-Workflowhttps://go.microsoft.com/fwlink/?LinkId=267141 , que é um comando no fluxo de trabalho que suspende o fluxo de trabalho.

O Suspend-Job cmdlet funciona apenas em trabalhos de fluxo de trabalho. Ele não funciona em trabalhos em segundo plano padrão, como aqueles que são iniciados usando o Start-Job cmdlet.

Para identificar um trabalho de fluxo de trabalho, procure um valor de PSWorkflowJob na propriedade PSJobTypeName do trabalho. Para determinar se um determinado tipo de trabalho personalizado dá suporte ao Suspend-Job cmdlet, consulte os tópicos de ajuda para o tipo de trabalho personalizado.

Quando você suspende uma tarefa de fluxo de trabalho, essa tarefa é executada até o próximo ponto de verificação, suspendida e então retorna imediatamente como resultado um objeto de tarefa de fluxo de trabalho. Para aguardar a conclusão da suspensão antes de obter o trabalho, use o parâmetro Wait de Suspend-Job ou o Wait-Job cmdlet. Quando o trabalho de fluxo de trabalho é suspenso, o valor da propriedade State do trabalho é Suspenso.

Suspender corretamente o trabalho depende dos pontos de verificação. O estado atual do trabalho, os metadados e a saída são salvos no ponto de verificação para que o trabalho de fluxo de trabalho possa ser retomado sem perda de estado ou dados. Se o trabalho de fluxo de trabalho não tiver pontos de verificação, ele não poderá ser suspenso corretamente. Para adicionar pontos de verificação a um fluxo de trabalho que você está executando, use o parâmetro comum de fluxo de trabalho PSPersist. Você pode usar o parâmetro Force para suspender qualquer trabalho de fluxo de trabalho imediatamente e suspender um trabalho de fluxo de trabalho que não tenha pontos de verificação, mas a ação pode causar perda de estado e dados.

Antes de usar um cmdlet Job em um tipo de trabalho personalizado, como um trabalho de fluxo de trabalho (PSWorkflowJob), importe o módulo que dá suporte ao tipo de trabalho personalizado, usando o Import-Module cmdlet ou usando ou usando um cmdlet no módulo.

Este cmdlet foi introduzido no Windows PowerShell 3.0.

Exemplos

Exemplo 1: Suspender um trabalho de fluxo de trabalho por nome

Este exemplo mostra como suspender uma tarefa de fluxo de trabalho.

O primeiro comando cria o Get-SystemLog fluxo de trabalho. O fluxo de trabalho usa a CheckPoint-Workflow atividade para definir um ponto de verificação no fluxo de trabalho.

O segundo comando usa o parâmetro AsJob, que é comum a todos os fluxos de trabalho, para executar o Get-SystemLog fluxo de trabalho como um trabalho em segundo plano. O comando usa o parâmetro comum do fluxo de trabalho JobName para especificar um nome amigável para o trabalho de fluxo de trabalho.

O terceiro comando usa o Get-Job cmdlet para obter o trabalho de LogflowJob fluxo de trabalho. A saída mostra que o valor da propriedade PSJobTypeName é PSWorkflowJob.

O quarto comando usa o Suspend-Job cmdlet para suspender o LogflowJob trabalho. O trabalho é executado até o ponto de verificação e, em seguida, é suspenso.

#Sample Workflow
Workflow Get-SystemLog
{
    $Events = Get-WinEvent -LogName System
    CheckPoint-Workflow
    InlineScript {\\Server01\Scripts\Analyze-SystemEvents.ps1 -Events $Events}
}
Get-SystemLog -AsJob -JobName "LogflowJob"
Get-Job -Name LogflowJob

Id   Name          PSJobTypeName   State       HasMoreData     Location   Command
--   ----          -------------   -----       -----------     --------   -------
4    LogflowJob    PSWorkflowJob   Running     True            localhost   Get-SystemLog

Suspend-Job -Name LogflowJob

Id   Name          PSJobTypeName   State       HasMoreData     Location   Command
--   ----          -------------   -----       -----------     --------   -------
4    LogflowJob    PSWorkflowJob   Suspended   True            localhost   Get-SystemLog

Exemplo 2: Suspender e retomar um trabalho de fluxo de trabalho

Este exemplo mostra como suspender e retomar uma tarefa de fluxo de trabalho.

O primeiro comando suspende o trabalho LogWorkflowJob. O comando retorna imediatamente. A saída mostra que o trabalho de fluxo de trabalho ainda está em execução, mesmo que esteja sendo suspenso.

O segundo comando usa o Get-Job cmdlet para obter o trabalho LogWorkflowJob. A saída mostra que o trabalho de fluxo de trabalho foi suspenso com êxito.

O terceiro comando usa o Get-Job cmdlet para obter o trabalho LogWorkflowJob e o Resume-Job cmdlet para retomá-lo. A saída mostra que o trabalho de fluxo de trabalho foi retomado com êxito e agora está em execução.

Suspend-Job -Name LogWorkflowJob

Id   Name          PSJobTypeName      State         HasMoreData     Location      Command
--   ----          -------------      -----         -----------     --------      -------
67   LogflowJob    PSWorkflowJob      Running       True            localhost     LogWorkflow

Get-Job -Name LogWorkflowJob

Id   Name          PSJobTypeName      State         HasMoreData     Location      Command
--   ----          -------------      -----         -----------     --------      -------
67   LogflowJob    PSWorkflowJob      Suspended     True            localhost     LogWorkflow

Get-Job -Name LogWorkflowJob | Resume-Job

Id     Name          PSJobTypeName      State       HasMoreData     Location      Command
--     ----          -------------      -----       -----------     --------      -------
67     LogflowJob    PSWorkflowJob      Running     True            localhost     LogWorkflow

Exemplo 3: Suspender um trabalho de fluxo de trabalho em um computador remoto

Invoke-Command -ComputerName Srv01 -Scriptblock {Suspend-Job -Filter @{CustomID="031589"}

Esse comando usa o Invoke-Command cmdlet para suspender um trabalho de fluxo de trabalho no computador remoto Srv01. O valor do parâmetro Filter é uma tabela de hash que especifica um valor CustomID. Esse CustomID é um metadado de trabalho (PSPrivateMetadata).

Exemplo 4: Aguarde a suspensão do trabalho de fluxo de trabalho

Suspend-Job VersionCheck -Wait

Id     Name          PSJobTypeName      State         HasMoreData     Location      Command
--     ----          -------------      -----         -----------     --------      -------
 5     VersionCheck  PSWorkflowJob      Suspended     True            localhost     LogWorkflow

Este comando suspende a tarefa de fluxo de trabalho VersionCheck. O comando usa o parâmetro Wait para aguardar até que o trabalho de fluxo de trabalho seja suspenso. Quando o trabalho de fluxo de trabalho é executado para o próximo ponto de verificação e é suspenso, o comando é concluído e retorna o objeto de trabalho.

Exemplo 5: Forçar a suspensão de um trabalho de fluxo de trabalho

Suspend-Job Maintenance -Force

Este comando suspende à força a tarefa de fluxo de trabalho Maintenance. O trabalho de manutenção não tem pontos de verificação. Ele não pode ser suspenso corretamente e pode não ser retomado corretamente.

Parâmetros

-Confirm

Solicita sua confirmação antes de executar o cmdlet.

Tipo:SwitchParameter
Aliases:cf
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Filter

Especifica uma tabela de hash de condições. Esse cmdlet suspende trabalhos que atendem a todas as condições. Insira uma tabela de hash na qual as chaves são propriedades do trabalho e os valores são valores de propriedade do trabalho.

Tipo:Hashtable
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-Force

Suspende a tarefa de fluxo de trabalho imediatamente. Essa ação pode causar uma perda de estado e dados.

Por padrão, permite que o trabalho de fluxo de trabalho seja executado até o próximo ponto de verificação e, em seguida, Suspend-Job o suspende. Você também pode usar esse parâmetro para suspender tarefas de fluxo de trabalho que não têm pontos de verificação.

Tipo:SwitchParameter
Aliases:F
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Id

Especifica as IDs de trabalhos que esse cmdlet suspende.

O ID é um 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 localizar a ID de um trabalho, use o Get-Job cmdlet.

Tipo:Int32[]
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-InstanceId

Especifica as IDs de instância de trabalhos que esse cmdlet suspende. O padrão é obter todos os trabalhos.

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 Get-Job.

Tipo:Guid[]
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-Job

Especifica os trabalhos de fluxo de trabalho que esse cmdlet interrompe. Insira uma variável que contenha as tarefas de fluxo de trabalho ou um comando que as obtenha. Você também pode canalizar trabalhos de fluxo de trabalho para o Suspend-Job cmdlet.

Tipo:Job[]
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-Name

Especifica nomes amigáveis de trabalhos que esse cmdlet suspende. Insira um ou mais nomes de tarefas de fluxo de trabalho. Há suporte para caracteres curinga.

Tipo:String[]
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-State

Especifica um estado de trabalho. Esse cmdlet interrompe apenas os trabalhos no estado especificado. Os valores aceitáveis para esse parâmetro são:

  • NotStarted
  • Executando
  • Concluído(a)
  • Com falha
  • Parado
  • Bloqueado
  • Suspenso
  • Desconectado
  • Suspensão
  • Parando

Suspend-Job suspende apenas trabalhos de fluxo de trabalho no estado Em execução .

Para obter mais informações sobre estados de trabalho, consulte Enumeração JobState.

Tipo:JobState
Valores aceitos:NotStarted, Running, Completed, Failed, Stopped, Blocked, Suspended, Disconnected, Suspending, Stopping, AtBreakpoint
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-Wait

Indica que esse cmdlet suprime o prompt de comando até que o trabalho de fluxo de trabalho esteja no estado suspenso. Por padrão, Suspend-Job retorna imediatamente, mesmo que o trabalho de fluxo de trabalho ainda não esteja no estado suspenso.

O parâmetro Wait é equivalente a canalizar um Suspend-Job comando para o Wait-Job cmdlet.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-WhatIf

Mostra o que aconteceria se o cmdlet fosse executado. O cmdlet não é executado.

Tipo:SwitchParameter
Aliases:wi
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

Entradas

Job

Você pode canalizar todos os tipos de trabalhos para esse cmdlet. No entanto, se Suspend-Job obtiver um trabalho de um tipo sem suporte, ele retornará um erro de encerramento.

Saídas

Job

Esse cmdlet retorna os trabalhos que ele suspendeu.

Observações

O Windows PowerShell inclui os seguintes aliases para Suspend-Job:

  • sujb

O mecanismo e o local para salvar um trabalho suspenso podem variar, dependendo do tipo do trabalho. Por exemplo, tarefas de fluxo de trabalho suspensas são salvas em um repositório de arquivo simples por padrão, mas também podem ser salvas em um banco de dados.

Se você enviar um trabalho de fluxo de trabalho que não esteja no estado Em execução, Suspend-Job exibirá uma mensagem de aviso. Para suprimir o aviso, use o parâmetro comum WarningAction com um valor de SilentlyContinue.

Se um trabalho não for de um tipo que suporte a suspensão, Suspend-Job retornará um erro de encerramento.

Para localizar os trabalhos de fluxo de trabalho suspensos, incluindo aqueles que foram suspensos por esse cmdlet, use o parâmetro State do cmdlet para obter trabalhos de fluxo de Get-Job trabalho no estado Suspenso.

Alguns tipos de trabalho têm opções ou propriedades que impedem que o Windows PowerShell suspenda o trabalho em questão. Se as tentativas de suspender o trabalho falharem, verifique se as opções e propriedades do trabalho permitem a suspensão.