Compartilhar via

New-ScheduledJobOption

  • Referência
Módulo:
PSScheduledJob

Cria um objeto que contém as 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 cmdlet New-ScheduledJobOption cria um objeto que contém as opções avançadas para um trabalho agendado.

Você pode usar o objeto ScheduledJobOptions que retorna New-ScheduledJobOption para definir opções de trabalho para um trabalho agendado novo ou existente. Como alternativa, você pode definir opções de trabalho usando o cmdlet Get-ScheduledJobOption 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, é possível usar o objeto resultante como um modelo e criar objetos de opção padrão para a 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 é uma 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 veja about_Scheduled_Jobs.

Este cmdlet foi introduzido no Windows PowerShell 3.0.

Exemplos

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

PS C:\> New-ScheduledJobOption
StartIfOnBatteries     : False
StopIfGoingOnBatteries : True
WakeToRun              : False
StartIfNotIdle         : True
StopIfGoingOffIdle     : False
RestartOnIdleResume    : False
IdleDuration           : 00:10:00
IdleTimeout            : 01:00:00
ShowInTaskScheduler    : True
RunElevated            : False
RunWithoutNetwork      : True
DoNotAllowDemandStart  : False
MultipleInstancePolicy : Ignore
NewJobDefinition       :

Este comando cria um objeto de opção de trabalho agendado que tem todos os valores padrões.

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

PS C:\> 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

The first command creates a **ScheduledJobOptions** object with the *RunElevated* parameter. It saves the object in the $RunAsAdmin variable.
PS C:\> $RunAsAdmin = New-ScheduledJobOption -RunElevated

The second command uses the Register-ScheduledJob cmdlet to create a new scheduled job. The value of the *ScheduledJobOption* parameter is the option object in the value of the $RunAsAdmin variable.
PS C:\> Register-ScheduledJob -Name Backup -FilePath D:\Scripts\Backup.ps1 -Trigger $Mondays -ScheduledJobOption $RunAsAdmin

The third command uses the Get-ScheduledJobOption cmdlet to get the job options of the Backup scheduled job.The cmdlet output shows that the RunElevated property is set to $True and the JobDefinition property of the job option object is now populated with the scheduled job object for the Backup scheduled job.
PS C:\> 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

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

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

PS C:\> $Options = New-ScheduledJobOption -WakeToRun
PS C:\> $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

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

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

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

Esse formato facilita muito a localização da propriedade WakeToRun do objeto ScheduledJobOptions em $Options e 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.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters: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. Ele não impede que os usuários usem o cmdlet Start-Job 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:False
Required:False
Accept pipeline input:False
Accept wildcard characters: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 poderão exibir a tarefa 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:False
Required:False
Accept pipeline input:False
Accept wildcard characters: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 durante o tempo especificado antes do valor de IdleTimeout expirar, o trabalho agendado não será executado até que a próxima execução agendada, se houver.

Insira um objeto TimeSpan , como um gerado pelo cmdlet New-TimeSpan 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 Windows PowerShell ignora os valores IdleDuration e IdleTimeout.

Type:TimeSpan
Position:Named
Default value:10 minutes (00:10:00)
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IdleTimeout

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

Insira um objeto TimeSpan , como um gerado pelo cmdlet New-TimeSpan 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 Windows PowerShell ignora os valores IdleDuration e IdleTimeout.

Type:TimeSpan
Position:Named
Default value:1 hour (1:00:00)
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 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 será ignorada.
  • Paralelo. A nova instância de trabalho será iniciada imediatamente.
  • Fila. A nova instância de trabalho começa assim que a instância atual for 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 de trabalho não será iniciada, independentemente do valor desse parâmetro.

Type:TaskMultipleInstancePolicy
Accepted values:None, IgnoreNew, Parallel, Queue, StopExisting
Position:Named
Default value:IgnoreNew
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

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

-RestartOnIdleResume

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

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

Type:SwitchParameter
Position:Named
Default value:False
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 no qual o trabalho é executado.

Para habilitar um trabalho agendado a ser 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:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-StartIfIdle

Inicia o trabalho agendado, se o computador estiver ocioso durante o tempo especificado pelo parâmetro IdleDuration antes da hora especificada pelo parâmetro IdleTimeout expirar.

Por padrão, os parâmetros IdleDuration e IdleTimeout serão ignorados e o trabalho será iniciado na hora de início agendada, mesmo se o computador estiver 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:False
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters: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, utilize 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:False
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

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

Entradas

None

Não é possível redirecionar a entrada para este cmdlet.

Saídas

ScheduledJobOptions

Observações

  • Você pode usar o objeto ScheduledJobOptions que New-ScheduledJobOption cria como o valor do parâmetro ScheduledJobOption do cmdlet Register-ScheduledJob. 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"}