Compartilhar via

New-JobTrigger

  • Referência
Módulo:
PSScheduledJob

Cria um disparador de trabalho para um trabalho agendado.

Syntax

New-JobTrigger
   [-RandomDelay <TimeSpan>]
   -At <DateTime>
   [-Once]
   [-RepetitionInterval <TimeSpan>]
   [-RepetitionDuration <TimeSpan>]
   [-RepeatIndefinitely]
   [<CommonParameters>]
New-JobTrigger
   [-DaysInterval <Int32>]
   [-RandomDelay <TimeSpan>]
   -At <DateTime>
   [-Daily]
   [<CommonParameters>]
New-JobTrigger
   [-WeeksInterval <Int32>]
   [-RandomDelay <TimeSpan>]
   -At <DateTime>
   -DaysOfWeek<DayOfWeek[]>
   [-Weekly]
   [<CommonParameters>]
New-JobTrigger
   [-RandomDelay <TimeSpan>]
   [-AtStartup]
   [<CommonParameters>]
New-JobTrigger
   [-RandomDelay <TimeSpan>]
   [-User <String>]
   [-AtLogOn]
   [<CommonParameters>]

Description

O New-JobTrigger cmdlet cria um gatilho de trabalho que inicia um trabalho agendado em uma agenda única ou recorrente ou quando ocorre um evento.

Você pode usar o objeto ScheduledJobTrigger que New-JobTrigger retorna para definir um gatilho de trabalho para um trabalho agendado novo ou existente. Você também pode criar um gatilho de trabalho com o cmdlet para obter o gatilho de trabalho de um trabalho agendado existente ou com um valor de tabela de hash para representar um gatilho Get-JobTrigger de trabalho.

Ao criar um gatilho New-ScheduledJobOption de trabalho, revise os valores padrão das opções especificadas pelo cmdlet. Essas opções, que têm os mesmos valores válidos e padrão que as opções correspondentes no Agendador de Tarefas, afetam o agendamento e o tempo dos trabalhos agendados.

New-JobTrigger é 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: Agendamento Único

Este exemplo cria um gatilho de trabalho para iniciar um trabalho agendado apenas uma vez.

New-JobTrigger -Once -At "1/20/2012 3:00 AM"

O New-JobTrigger cmdlet para criar um gatilho de trabalho que inicia um trabalho agendado apenas uma vez. O valor do parâmetro At é uma cadeia de caracteres que o Windows PowerShell converte em um objeto DateTime.

O valor do parâmetro At inclui uma data explícita, não apenas uma hora. Se a data foi omitida, o gatilho seria criado com a data atual e hora de 3h, que é provável que represente uma hora no passado.

Exemplo 2: Programação diária

Este exemplo cria um novo gatilho de trabalho para iniciar um trabalho agendado a cada três dias.

New-JobTrigger -Daily -At "4:15 AM" -DaysInterval 3

Este comando cria um gatilho de trabalho que inicia um trabalho agendado a cada três dias às 4h15.

Como o valor do parâmetro At não inclui uma data, a data atual é usada como o valor de data no objeto DateTime . Se a data e a hora estiverem no passado, o trabalho agendado será iniciado na próxima ocorrência, que é 3 dias depois do valor do parâmetro At .

Exemplo 3: Agenda semanal

Este exemplo cria um gatilho de trabalho que inicia um trabalho agendado a cada quatro semanas em dias especificados dessa semana.

New-JobTrigger -Weekly -DaysOfWeek Monday, Wednesday, Friday -At "23:00" -WeeksInterval 4

Id Frequency Time                  DaysOfWeek                  Enabled
-- --------- ----                  ----------                  -------
0  Weekly    9/21/2012 11:00:00 PM {Monday, Wednesday, Friday} True

Este comando cria um gatilho de trabalho para iniciar um trabalho agendado às segundas, quartas e sextas-feiras às 2300 horas (23:00) a cada 4 semanas.

Você também pode inserir o valor do parâmetro DaysOfWeek em inteiros, como -DaysOfWeek 1, 5.

Exemplo 4: Agendamento de logon

Este exemplo cria um gatilho de trabalho para iniciar um trabalho agendado no logon de um usuário específico.

New-JobTrigger -AtLogOn -User Domain01\Admin01

Esse comando cria um gatilho de trabalho para iniciar um trabalho agendado sempre que o administrador de domínio fizer logon no computador.

Exemplo 5: Usando um atraso aleatório

Este exemplo cria um novo gatilho de trabalho com um atraso aleatório de período de tempo.

New-JobTrigger -Daily -At 1:00 -RandomDelay 00:20:00

Esse comando cria um gatilho de trabalho para iniciar um trabalho agendado todos os dias à 1:00 da manhã. O comando usa o parâmetro RandomDelay para definir o atraso máximo para 20 minutos. Como resultado, o trabalho é executado diariamente entre 1h e 1h20, com o intervalo variando pseudo aleatoriamente.

Você pode usar um atraso aleatório para amostragem, balanceamento de carga e outras tarefas administrativas. Ao definir o valor de atraso, revise os valores efetivos e padrão do cmdlet e coordene o atraso com as configurações de New-ScheduledJobOption opção.

Exemplo 6: Criar um gatilho de trabalho para um novo trabalho agendado

Este exemplo usa um gatilho de trabalho para criar um novo trabalho agendado.

$t = New-JobTrigger -Weekly -DaysOfWeek 1,3,5 -At 12:01AM
Register-ScheduledJob -Name Test-HelpFiles -FilePath C:\Scripts\Test-HelpFiles.ps1 -Trigger $t

O primeiro comando usa o cmdlet para criar um gatilho New-JobTrigger de trabalho que inicia um trabalho todas as segundas, quartas e sextas-feiras às 12h01. O comando salva o gatilho $t de trabalho na variável.

O segundo comando usa o cmdlet para criar um trabalho agendado Register-ScheduledJob que inicia um trabalho todas as segundas, quartas e sextas-feiras às 12h01. O valor do parâmetro Trigger é o gatilho $t armazenado na variável.

Exemplo 7: Adicionar um gatilho de trabalho a um trabalho agendado

Este exemplo mostra como adicionar um gatilho de trabalho a um trabalho agendado existente.

Add-JobTrigger -Name SynchronizeApps -Trigger (New-JobTrigger -Daily -At 3:10AM)

Você pode adicionar vários gatilhos de trabalho a qualquer trabalho agendado.

O comando usa o Add-JobTrigger cmdlet para adicionar o gatilho de trabalho ao trabalho agendado SynchronizeApps . O valor do parâmetro Trigger é um New-JobTrigger comando que executa o trabalho todos os dias às 3:10 AM.

Quando o comando é concluído, SynchronizeApps é um trabalho agendado que é executado nos horários especificados pelo gatilho do trabalho.

Exemplo 8: Criar um gatilho de trabalho repetitivo

Este exemplo cria um gatilho de trabalho de repetição para ser executado apenas por um período de tempo específico.

New-JobTrigger -Once -At "09/12/2013 1:00:00" -RepetitionInterval (New-TimeSpan -Hours 1) -RepetitionDuration (New-Timespan -Hours 48)

Esse comando cria um gatilho de trabalho que executa um trabalho a cada 60 minutos por 48 horas a partir de 12 de setembro de 2013 às 01:00.

Exemplo 9: Parar um gatilho de trabalho repetitivo

Este exemplo interrompe um disparador de trabalho repetitivo.

Get-JobTrigger -Name SecurityCheck | Set-JobTrigger -RepetitionInterval 0:00 -RepetitionDuration 0:00

Esse comando interrompe à força o trabalho SecurityCheck, que é acionado para ser executado a cada 60 minutos até que seu gatilho de trabalho expire.

Para impedir que o trabalho se repita, o comando usa o Get-JobTrigger para obter o gatilho de trabalho do trabalho SecurityCheck e o Set-JobTrigger cmdlet para alterar o intervalo de repetição e a duração de repetição do gatilho de trabalho para zero (0).

Exemplo 10: Criar um gatilho de trabalho por hora

Este exemplo cria um gatilho de trabalho repetitivo que é executado indefinidamente.

New-JobTrigger -Once -At "9/21/2012 0am" -RepetitionInterval (New-TimeSpan -Hour 12) -RepetitionDuration ([TimeSpan]::MaxValue)

O comando a seguir cria um gatilho de trabalho que executa um trabalho agendado a cada 12 horas, por um período indefinido de tempo. A agenda começa amanhã (21/9/2012) à meia-noite (0:00 AM).

Parâmetros

-At

Inicia o trabalho em determinada data e hora. Insira um objeto DateTime , como um que o Get-Date cmdlet retorna, ou uma cadeia de caracteres que possa ser convertida em uma data e hora, como April 19, 2012 15:00, 12/31ou 3am. Se você não especificar um elemento de data, como o ano, a data no gatilho tem o elemento correspondente a partir da data atual.

Ao usar o parâmetro Once , defina o valor do parâmetro At para uma data e hora futuras. Como a data padrão em um objeto DateTime é a data atual, se você especificar uma hora antes da hora atual sem uma data explícita, o gatilho de trabalho será criado para um tempo no passado.

Os objetos DateTime e as cadeias de caracteres convertidas em objetos DateTime são ajustados automaticamente para serem compatíveis com os formatos de data e hora selecionados para o computador local em Região e Idioma no Painel de Controle.

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

-AtLogOn

Inicia o trabalho agendado quando os usuários especificados fazem logon no computador. Para especificar um usuário, use o parâmetro User .

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

-AtStartup

Inicia o trabalho agendado quando o Windows inicia.

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

-Daily

Especifica uma agenda recorrente de trabalho diário. Use os outros parâmetros no conjunto de parâmetros Daily para especificar os detalhes da agenda.

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

-DaysInterval

Especifica o número de dias entre ocorrências em uma agenda diária. Por exemplo, um valor de 3 inicia o trabalho agendado em dias 1, 74e assim por diante. O valor padrão é 1.

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

-DaysOfWeek

Especifica os dias da semana em que um trabalho agendado semanalmente é executado. Insira nomes de dia, como Monday ou inteiros , onde 0 representa o 0-6domingo. Esse parâmetro é necessário no conjunto de parâmetros Semanal .

Nomes de dias são convertidos em seus valores inteiros no gatilho de trabalho. Quando você coloca nomes de dia entre aspas em um comando, coloque o nome de cada dia entre aspas separadas, como "Monday", "Tuesday". Se você colocar vários nomes de dias em um par de aspas simples, os valores inteiros correspondentes são somados. Por exemplo, "Monday, Tuesday" (1 + 2) resulta em um valor de Wednesday (3).

Type:DayOfWeek[]
Accepted values:Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Once

Especifica uma agenda personalizada de repetição ou não recorrente (única). Para criar uma agenda de repetição, use o parâmetro Once com os parâmetros RerepeatDuration e RerepeatInterval .

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

-RandomDelay

Permite um atraso aleatório que começa na hora de início agendada e define o valor de tempo de espera máximo. O tempo de atraso é definido pseudoaleatoriamente para cada início e varia de nenhum atraso até a hora especificada pelo valor desse parâmetro. O valor padrão, zero (00:00:00), desabilita o atraso aleatório.

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

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

-RepeatIndefinitely

Esse parâmetro, disponível a partir do Windows PowerShell 4.0, elimina a necessidade de especificar um valor TimeSpan.MaxValue para o parâmetro RepetitionDuration para executar um trabalho agendado repetidamente, por um período indefinido.

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

-RepetitionDuration

Repete o trabalho até o tempo especificado expirar. A frequência de repetição é determinada pelo valor do parâmetro RerepeatInterval . Por exemplo, se o valor de RerepeatInterval for 5 minutos e o valor de RerepeatDuration for 2 horas, o trabalho será acionado a cada cinco minutos por duas horas.

Insira um objeto timespan, como um que o New-TimeSpan cmdlet retorna ou uma cadeia de caracteres que pode ser convertida em um objeto timespan, como 1:05:30.

Para executar um trabalho indefinidamente, adicione o parâmetro RepeatIndefinitely em vez disso.

Para interromper um trabalho antes que a duração da repetição do gatilho de trabalho expire, use o Set-JobTrigger cmdlet para definir o valor RerepeatDuration como zero (0).

Esse parâmetro é válido somente quando os parâmetros Once, At e RerepeatInterval são usados no comando.

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

-RepetitionInterval

Repete o trabalho no tempo especificado. Por exemplo, se o valor desse parâmetro é de 2 horas, o trabalho será acionado a cada duas horas. O valor padrão, 0, não repete o trabalho.

Insira um objeto timespan, como um que o New-TimeSpan cmdlet retorna ou uma cadeia de caracteres que pode ser convertida em um objeto timespan, como 1:05:30.

Esse parâmetro é válido somente quando os parâmetros Once, At e RerepeatDuration são usados no comando.

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

-User

Especifica os usuários que disparam um início AtLogon de um trabalho agendado. Digite o nome de um usuário em <UserName> ou <Domain\Username> formate ou insira um asterisco (*) para representar todos os usuários. O valor padrão é todos os usuários.

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

-Weekly

Especifica uma agenda recorrente de trabalho semanal. Use os outros parâmetros no conjunto de parâmetros Weekly para especificar os detalhes da agenda.

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

-WeeksInterval

Especifica o número de semanas entre ocorrências em uma agenda semanal. Por exemplo, um valor de 3 inicia o trabalho agendado em semanas 1, 74e assim por diante. O valor padrão é 1.

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

Entradas

None

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

Saídas

ScheduledJobTrigger

Esse cmdlet retorna um objeto ScheduledJobTrigger que representa o gatilho criado.

Observações

  • Gatilhos de trabalho não são salvos em disco. No entanto, os trabalhos agendados são salvos no disco e você pode usar o para obter o gatilho Get-JobTrigger de trabalho de qualquer trabalho agendado.

  • New-JobTrigger não impede que você crie um gatilho de trabalho que não executará um trabalho agendado, como gatilho único para uma data no passado.

  • O Register-ScheduledJob cmdlet aceita um objeto ScheduledJobTrigger , como um retornado pelos New-JobTrigger cmdlets ou Get-JobTrigger ou uma tabela de hash com valores de disparo.

    Para enviar uma tabela de hash, use as seguintes chaves.

    • Frequência: Once, Daily, Weekly, AtStartup, ou AtLogon
    • Em: qualquer sequência de tempo válida, como 3am
    • DaysOfWeek: qualquer combinação de nomes de dia como cadeias de caracteres, como "Monday", "Wednesday"
    • Intervalo: qualquer intervalo de frequência válido como um inteiro
    • RandomDelay: qualquer cadeia de caracteres de intervalo de tempo válida, como 30minutes
    • Usuário: qualquer usuário válido, como Domain1\User01; usado somente com o valor de frequência AtLogon