New-ScheduledJobOption

  • Referência
Módulo:
PSScheduledJob

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

Syntax

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, revise os valores padrão de todas as opções de trabalho agendado. Os trabalhos agendados são executados somente quando todas as condições definidas para sua execução são satisfeitas.

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 no 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 se o computador não estiver conectado à alimentação CA.

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 RunElevated . Ele salva o objeto na $runAsAdmin variável.

O segundo comando usa o Register-ScheduledJob cmdlet para criar um novo trabalho agendado. O valor do parâmetro ScheduledJobOption é o objeto option 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, em seguida, 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 pare o trabalho agendado se o computador mudar para a alimentação da bateria (desconecta-se da alimentação CA) enquanto o trabalho está em execução. Por padrão, os trabalhos agendados param quando o computador se desconecta da alimentação CA.

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

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-DoNotAllowDemandStart

Inicie o trabalho somente quando ele for acionado. Os usuários não podem iniciar o trabalho manualmente, como usando o recurso Executar no Agendador de Tarefas.

Este parâmetro afeta apenas o Agendador de Tarefas. Ele 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.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-HideInTaskScheduler

Não exiba o trabalho no Agendador de Tarefas. Esse valor afeta apenas o computador no qual o trabalho é executado. Por padrão, as tarefas agendadas aparecem no Agendador de Tarefas.

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

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

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IdleDuration

Especifica por quanto tempo o computador deve ficar ocioso antes que o trabalho seja iniciado. O valor predefinido é 10 minutos. Se o computador não estiver ocioso durante a duração especificada antes que o valor de IdleTimeout expire, o trabalho agendado não será executado até a próxima hora agendada, 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 .

Type:TimeSpan
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IdleTimeout

Especifica quanto tempo o trabalho agendado aguarda para que o computador fique ocioso. Se esse tempo limite expirar antes que o computador permaneça ocioso durante o período especificado pelo parâmetro IdleDuration , o trabalho não será executado até a próxima hora agendada, 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 .

Type:TimeSpan
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MultipleInstancePolicy

Determina como o sistema responde a uma solicitação para iniciar uma instância de um trabalho agendado enquanto outra instância do trabalho está em execução. O valor predefinido é IgnoreNew. Os valores aceitáveis para este 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 para e a nova instância é iniciada.

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

Type:Microsoft.PowerShell.ScheduledJob.TaskMultipleInstancePolicy
Accepted values:None, IgnoreNew, Parallel, Queue, StopExisting
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RequireNetwork

Executa o trabalho agendado somente quando as 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.

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

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RestartOnIdleResume

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

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

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RunElevated

Executa o trabalho agendado com as permissões de um membro do grupo Administradores no computador em que 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 credenciais explícitas para o trabalho.

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

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-StartIfIdle

Inicia o trabalho agendado se o computador tiver estado inativo durante o tempo especificado pelo parâmetro IdleDuration antes do tempo especificado pelo parâmetro IdleTimeout expirar.

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.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-StartIfOnBattery

Inicia o trabalho agendado mesmo que o computador esteja funcionando com baterias na hora de início agendada. O valor predefinido é $false.

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

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-StopIfGoingOffIdle

Suspende um trabalho agendado em execução se o computador ficar ativo (não ocioso) enquanto o trabalho estiver em execução.

Por padrão, um trabalho agendado que é suspenso quando o computador fica ativo é retomado quando o computador fica 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.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WakeToRun

Desperta o computador de um estado de Hibernação ou Suspensão na hora de início agendada para que possa executar o trabalho. Por padrão, se o computador estiver em um estado de Hibernação ou Suspensão no horário de início agendado, o trabalho não será executado.

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

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Entradas

None

Não é possível canalizar objetos para este cmdlet.

Saídas

Microsoft.PowerShell.ScheduledJob.ScheduledJobOptions

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

Notas

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

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