Compartilhar via

New-ScheduledJobOption

  • Referência
Módulo:
PSScheduledJob

Cria um objeto que contém as opções avançadas para um trabalho agendado.

Sintaxe

New-ScheduledJobOption
   [-RunElevated]
   [-HideInTaskScheduler]
   [-RestartOnIdleResume]
   [-MultipleInstancePolicy <TaskMultipleInstancePolicy>]
   [-DoNotAllowDemandStart]
   [-RequireNetwork]
   [-StopIfGoingOffIdle]
   [-WakeToRun]
   [-ContinueIfGoingOnBattery]
   [-StartIfOnBattery]
   [-IdleTimeout <TimeSpan>]
   [-IdleDuration <TimeSpan>]
   [-StartIfIdle]
   [<CommonParameters>]

Description

O New-ScheduledJobOption cmdlet cria um objeto que contém opções avançadas para um trabalho agendado.

Você pode usar o objeto ScheduledJobOptions que New-ScheduledJobOption retorna para definir opções de trabalho para um trabalho agendado novo ou existente. Como alternativa, você pode definir opções de trabalho usando o Get-ScheduledJobOption cmdlet para obter as opções de trabalho de um trabalho agendado existente ou usando um valor de tabela de hash para representar as opções de trabalho.

Sem parâmetros, New-ScheduledJobOption gera um objeto que contém os valores padrão para todas as opções. Como todas as propriedades, exceto a propriedade JobDefinition, podem ser editadas, você pode usar o objeto resultante como um modelo e criar objetos de opção padrão para sua empresa.

Ao criar trabalhos agendados e definir opções de trabalho agendado, examine os valores padrões de todas as opções de trabalho agendado. Executar somente quando todas as condições definidas para a execução de trabalhos agendados forem atendidas.

New-ScheduledJobOption é um de uma coleção de cmdlets de agendamento de trabalho no módulo PSScheduledJob incluído no Windows PowerShell.

Para obter mais informações sobre trabalhos agendados, consulte os tópicos sobre o módulo PSScheduledJob. Importe o módulo PSScheduledJob e digite: Get-Help about_Scheduled* ou consulte about_Scheduled_Jobs.

Este cmdlet foi introduzido no Windows PowerShell 3.0.

Exemplos

Exemplo 1: Criar um objeto de opção de trabalho agendado com valores padrão

Este exemplo cria um objeto de opção de trabalho agendado com os valores padrão.

New-ScheduledJobOption

Exemplo 2: Criar um objeto de opção de trabalho agendado com valores personalizados

Este exemplo cria um objeto de opção de trabalho agendado com valores personalizados

New-ScheduledJobOption -RequireNetwork -StartIfOnBattery

StartIfOnBatteries     : True
StopIfGoingOnBatteries : True
WakeToRun              : False
StartIfNotIdle         : True
StopIfGoingOffIdle     : False
RestartOnIdleResume    : False
IdleDuration           : 00:10:00
IdleTimeout            : 01:00:00
ShowInTaskScheduler    : True
RunElevated            : False
RunWithoutNetwork      : False
DoNotAllowDemandStart  : False
MultipleInstancePolicy : Ignore
NewJobDefinition       :

O comando a seguir cria um objeto de trabalho agendado que requer a rede e executa o trabalho agendado, mesmo que o computador não esteja conectado à corrente alternada.

A saída mostra que o parâmetro RequireNetwork alterou o valor da propriedade RunWithoutNetwork para $false e o parâmetro StartIfOnBattery alterou o valor da propriedade StartIfOnBatteries para $true.

Exemplo 3: Definir opções para um novo trabalho agendado

Este exemplo mostra como usar o objeto ScheduledJobOptions que New-ScheduledJobOption retorna para definir as opções para um novo trabalho agendado.

$runAsAdmin = New-ScheduledJobOption -RunElevated
Register-ScheduledJob -Name Backup -FilePath D:\Scripts\Backup.ps1 -Trigger $Mondays -ScheduledJobOption $RunAsAdmin
Get-ScheduledJobOption -Name Backup

StartIfOnBatteries     : False
StopIfGoingOnBatteries : True
WakeToRun              : False
StartIfNotIdle         : True
StopIfGoingOffIdle     : False
RestartOnIdleResume    : False
IdleDuration           : 00:10:00
IdleTimeout            : 01:00:00
ShowInTaskScheduler    : True
RunElevated            : True
RunWithoutNetwork      : True
DoNotAllowDemandStart  : False
MultipleInstancePolicy : IgnoreNew
JobDefinition          : Microsoft.PowerShell.ScheduledJob.ScheduledJobDefinition

O primeiro comando cria um objeto ScheduledJobOptions com o parâmetro RunLebred . Ele salva o $runAsAdmin objeto na variável.

O segundo comando usa o cmdlet para criar um novo trabalho agendado Register-ScheduledJob . O valor do parâmetro ScheduledJobOption é o objeto de opção no valor da $runAsAdmin variável.

O terceiro comando usa o Get-ScheduledJobOption cmdlet para obter as opções de trabalho do trabalho agendado de backup. A saída do cmdlet mostra que a propriedade RunElevated está definida como $true e a propriedade JobDefinition do objeto de opção de trabalho agora está preenchida com o objeto de trabalho agendado para o trabalho agendado de backup.

Exemplo 4: Classificar as propriedades de um objeto de opção de trabalho agendado

Este exemplo mostra como classificar as propriedades de um objeto ScheduledJobOptions em ordem alfabética para facilitar a leitura.

$options = New-ScheduledJobOption -WakeToRun
$options.PSObject.Properties | Sort-Object -Property Name | Format-Table -Property Name, Value -Autosize

Name                       Value
----                       -----
DoNotAllowDemandStart      False
IdleDuration            00:10:00
IdleTimeout             01:00:00
JobDefinition
MultipleInstancePolicy IgnoreNew
RestartOnIdleResume        False
RunElevated                False
RunWithoutNetwork           True
ShowInTaskScheduler         True
StartIfNotIdle              True
StartIfOnBatteries         False
StopIfGoingOffIdle         False
StopIfGoingOnBatteries      True
WakeToRun                   True

O primeiro comando usa o New-ScheduledJobOption cmdlet para criar um objeto ScheduledJobOptions . O comando usa o parâmetro WakeToRun e salva o objeto resultante na $options variável.

Para obter as propriedades de $Options como objetos, o segundo comando usa a propriedade PSObject de todos os objetos do Windows PowerShell e sua propriedade Properties. Em seguida, o comando canaliza os objetos de propriedade para o Sort-Object cmdlet, que classifica as propriedades em ordem alfabética por nome, e depois para o Format-Table cmdlet, que exibe os nomes e valores das propriedades em uma tabela.

Esse formato torna muito mais fácil localizar a propriedade WakeToRun do objeto ScheduledJobOptions e $options verificar se seu valor foi alterado de $false para $true.

Parâmetros

-ContinueIfGoingOnBattery

Não interrompa a tarefa se o computador alternar para a energia da bateria (desconectado da corrente alternada) enquanto o trabalho estiver em execução. Por padrão, os trabalhos agendados param quando o computador é desconectado da corrente alternada.

O parâmetro ContinueIfGoingOnBattery define o valor da propriedade StopIfGoingOnBatteries de trabalhos agendados como $true.

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

-DoNotAllowDemandStart

Inicie o trabalho somente quando ele é acionado. Os usuários não podem iniciar o trabalho manualmente, como usando a execução de recursos no Agendador de tarefas.

Este parâmetro afeta somente o Agendador de tarefas. Isso não impede que os usuários usem o Start-Job cmdlet para iniciar o trabalho.

O parâmetro DoNotAllowDemandStart define o valor da propriedade DoNotAllowDemandStart de trabalhos agendados como $true.

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

-HideInTaskScheduler

Não exiba o trabalho no Agendador de tarefas. Esse valor afeta somente o computador no qual o trabalho é executado. Por padrão, as tarefas agendadas são exibidas no Agendador de tarefas.

Mesmo que uma tarefa esteja oculta, os usuários podem exibi-la selecionando a opção de exibição Mostrar tarefas ocultas no Agendador de Tarefas.

O parâmetro HideInTaskScheduler define o valor da propriedade ShowInTaskScheduler de trabalhos agendados como $false.

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

-IdleDuration

Especifica quanto tempo o computador deve permanecer ocioso antes de iniciar o trabalho. O valor padrão é 10 minutos. Se o computador não estiver ocioso pela duração especificada antes que o valor de IdleTimeout expire, o trabalho agendado não será executado até o próximo horário agendado, se houver.

Insira um objeto TimeSpan , como um gerado pelo New-TimeSpan cmdlet, ou insira um valor no <formato hours>:<minutes>:<seconds> que é convertido automaticamente em um objeto TimeSpan .

Para habilitar esse valor, use o parâmetro StartIfIdle . Por padrão, a propriedade StartIfNotIdle de trabalhos agendados é definida como $true e o Windows PowerShell ignora os valores IdleDuration e IdleTimeout .

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

-IdleTimeout

Especifica quanto tempo a tarefa aguarda o computador ficar ocioso. Se esse tempo limite expirar antes que o computador permaneça ocioso pelo período especificado pelo parâmetro IdleDuration , o trabalho não será executado até o próximo horário agendado, se houver. O valor padrão é uma hora.

Insira um objeto TimeSpan , como um gerado pelo New-TimeSpan cmdlet, ou insira um valor no <formato hours>:<minutes>:<seconds> que é convertido automaticamente em um objeto TimeSpan .

Para habilitar esse valor, use o parâmetro StartIfIdle . Por padrão, a propriedade StartIfNotIdle de trabalhos agendados é definida como $true e o Windows PowerShell ignora os valores IdleDuration e IdleTimeout .

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

-MultipleInstancePolicy

Determina como o sistema responde a uma solicitação para iniciar uma instância de um trabalho agendado, enquanto outra instância de trabalho está em execução. O valor padrão é IgnoreNew. Os valores aceitáveis para esse parâmetro são:

  • IgnoreNew - A nova instância de trabalho é ignorada.
  • Parallel - A nova instância de trabalho é iniciada imediatamente.
  • Queue - A nova instância de trabalho é iniciada assim que a instância atual é concluída.
  • StopExisting - A instância atual do trabalho é interrompida e a nova instância é iniciada.

Para executar o trabalho, todas as condições da agenda de trabalho devem ser atendidas. Por exemplo, se as condições definidas pelos parâmetros RequireNetwork, IdleDuration e IdleTimeout não forem atendidas, a instância do trabalho não será iniciada, independentemente do valor desse parâmetro.

Tipo:TaskMultipleInstancePolicy
Valores aceitos:None, IgnoreNew, Parallel, Queue, StopExisting
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-RequireNetwork

Executa a tarefa agendada somente quando conexões de rede estão disponíveis.

Se você especificar esse parâmetro e a rede não estiver disponível na hora de início agendada, o trabalho não será executado até a próxima hora de início agendada, se houver alguma.

O parâmetro RequireNetwork define o valor da propriedade RunWithoutNetwork de trabalhos agendados como $false.

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

-RestartOnIdleResume

Reinicia um trabalho agendado quando o computador ficar ocioso. Esse parâmetro funciona com o parâmetro StopIfGoingOffIdle, que suspende um trabalho agendado em execução se o computador se tornar ativo (deixar o estado ocioso).

O parâmetro RestartOnIdleResume define o valor da propriedade RestartOnIdleResume de trabalhos agendados como $true.

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

-RunElevated

Executa o trabalho agendado com as permissões de um membro do grupo Administradores no computador no qual o trabalho é executado.

Para permitir que um trabalho agendado seja executado com permissões de administrador, use o parâmetro Credential de Register-ScheduledJob para fornecer uma credencial explícita para o trabalho.

O parâmetro RunElevated define o valor da propriedade RunElevated de trabalhos agendados como $true.

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

-StartIfIdle

Inicia o trabalho agendado se o computador tiver ficado ocioso pelo tempo especificado pelo parâmetro IdleDuration antes que o tempo especificado pelo parâmetro IdleTimeout expire.

Por padrão, os parâmetros IdleDuration e IdleTimeout são ignorados e o trabalho é iniciado na hora de início agendada, mesmo que o computador esteja ocupado.

Se você especificar esse parâmetro e o computador estiver ocupado (não ocioso) na hora de início agendada, o trabalho não será executado até a próxima hora de início agendada se houver.

O parâmetro StartIfIdle define o valor da propriedade StartIfNotIdle de trabalhos agendados como $false.

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

-StartIfOnBattery

Inicia o trabalho agendado, mesmo se o computador estiver usando baterias na hora de início agendada. O valor padrão é $false.

O parâmetro StartIfOnBattery define o valor da propriedade StartIfOnBatteries de trabalhos agendados como $true.

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

-StopIfGoingOffIdle

Suspende um trabalho agendado em execução se o computador se torna ativo (não ocioso) enquanto o trabalho está em execução.

Por padrão, um trabalho agendado é suspenso quando o computador se torna ativo e retomado quando o computador tornar-se ocioso novamente. Para alterar esse comportamento padrão, use o parâmetro RestartOnIdleResume .

O parâmetro StopIfGoingOffIdle define o valor da propriedade StopIfGoingOffIdle de trabalhos agendados como $true.

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

-WakeToRun

Desperta o computador de um estado de suspensão ou de hibernação na hora de início agendada para que possa executar o trabalho. Por padrão, se o computador está em um estado de suspensão ou de hibernação na hora de início agendada, o trabalho não será executado.

O parâmetro WakeToRun define o valor da propriedade WakeToRun de trabalhos agendados como $true.

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

Entradas

None

Você não pode canalizar objetos para esse cmdlet.

Saídas

ScheduledJobOptions

Esse cmdlet retorna um objeto ScheduledJobOptions que representa as opções criadas.

Observações

  • Você pode usar o objeto ScheduledJobOptions que New-ScheduledJobOption é criado como o valor do parâmetro ScheduledJobOption do Register-ScheduledJob cmdlet. No entanto, o parâmetro ScheduledJobOption também pode usar um valor de tabela de hash que especifica as propriedades do objeto ScheduledJobOptions e seus valores, como:

    @{ShowInTaskScheduler=$False; RunElevated=$True; IdleDuration="00:05"}