New-JobTrigger

参考

模块:: PSScheduledJob

为计划作业创建作业触发器。

语法

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>]

说明

New-JobTrigger cmdlet 会创建作业触发器，该触发器可以根据一次性计划或重复计划启动计划作业，或者在事件发生时这样做。

你可以使用 New-JobTrigger 返回的 ScheduledJobTrigger 对象，为新的或现有的计划作业设置作业触发器。还可以使用 Get-JobTrigger cmdlet（用于获取现有计划作业的作业触发器）来创建作业触发器，或者使用一个表示作业触发器的哈希表值来创建作业触发器。

创建作业触发器时，请查看 New-ScheduledJobOption cmdlet 所指定的选项的默认值。这些选项具有与任务计划程序中相应选项相同的有效值和默认值，会影响计划作业的计划和时间安排。

New-JobTrigger 是 PSScheduledJob 模块（包含在 Windows PowerShell 中）中的一系列作业计划 cmdlet 之一。

有关计划作业的详细信息，请参阅 PSScheduledJob 模块中的“关于”主题。导入 PSScheduledJob 模块，然后键入 Get-Help about_Scheduled*，或参阅 about_Scheduled_Jobs。

此 cmdlet 是在 Windows PowerShell 3.0 中引入的。

示例

示例 1：一次性计划

此示例创建一个作业触发器来仅启动计划作业一次。

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

New-JobTrigger cmdlet 用于创建只能启动计划作业一次的作业触发器。 At 参数的值是一个可借助 Windows PowerShell 转换为 DateTime 对象的字符串。

At 参数的值包含一个显式日期，而不是仅仅包含某个时间。如果省略了日期，将使用当前日期和上午 3:00（这可能表示过去的某个时间）来创建该触发器。

示例 2：每日计划

此示例创建一个新的作业触发器，每三天启动一次计划作业。

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

此命令创建可在每隔 3 天的上午 4:15 启动计划作业的作业触发器。

由于 At 参数的值不包含日期，因此当前日期将用作 DateTime 对象中的日期值。如果该日期和时间是过去的日期和时间，则计划作业将在下次开始时间之前启动，开始时间为从 At 参数值起第 3 天。

示例 3：每周计划

此示例创建一个作业触发器，该触发器每隔四周在指定日期启动计划作业。

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

此命令创建一个作业触发器，该触发器将每隔 4 个星期在星期一、星期三和星期五的 23:00（晚上 11:00）启动计划作业。

你还可以以整数形式输入 DaysOfWeek 参数值，例如 -DaysOfWeek 1, 5。

示例 4：登录计划

此示例创建一个作业触发器，以在特定用户登录时启动计划作业。

New-JobTrigger -AtLogOn -User Domain01\Admin01

此命令创建一个作业触发器，该触发器将在每次域管理员登录到计算机时启动计划作业。

示例 5：使用随机延迟

此示例创建一个具有随机时间跨度延迟的新作业触发器。

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

此命令创建一个作业触发器，在每天凌晨 1:00 启动计划作业。此命令使用 RandomDelay 参数将最大延迟设置为 20 分钟。因此，该作业将以伪随机地方式在每天凌晨 1:00 至凌晨 1:20（随间隔值变化而变化）之间运行。

你可以将随机延迟用于采样、负载平衡以及其他管理任务。设置延迟值时，请检查 New-ScheduledJobOption cmdlet 的有效值和默认值，并使用选项设置来协调延迟。

示例 6：为新的计划作业创建作业触发器

以下示例使用作业触发器来创建新的计划作业。

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

第一个命令使用 New-JobTrigger cmdlet 创建在每周一、周三和周五的凌晨 0:01 启动作业的作业触发器。此命令将作业触发器保存在 $t 变量中。

第二个命令使用 Register-ScheduledJob cmdlet 创建在每周一、周三和周五的凌晨 0:01 启动作业的计划作业。 Trigger 参数的值是存储在 $t 变量中的触发器。

示例 7：将作业触发器添加到计划作业

此示例显示了如何将作业触发器添加到现有的计划作业。

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

你可以将多个作业触发器添加到任何计划作业。

此命令使用 Add-JobTrigger cmdlet 将作业触发器添加到 SynchronizeApps 计划作业。 Trigger 参数的值是在每天凌晨 3:10 运行该作业的 New-JobTrigger 命令。

完成此命令后，SynchronizeApps 将是一个在该作业触发器指定的时间运行的计划作业。

示例 8：创建重复作业触发器

此示例创建一个重复作业触发器，仅运行特定的时间。

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

此命令创建一个作业触发器，该触发器从 2013 年 9 月 12 日凌晨 1:00 开始，在 48 小时内每 60 分钟运行一次作业。

示例 9：停止重复作业触发器

此示例停止重复作业触发器。

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

此命令强制停止 SecurityCheck 作业，该作业触发后将在其作业触发器到期之前每 60 分钟运行一次。

为了防止作业重复，该命令使用 Get-JobTrigger 获取 SecurityCheck 作业的作业触发器，并使用 Set-JobTrigger cmdlet 将作业触发器的重复间隔和重复持续时间更改为零 (0)。

示例 10：创建每小时作业触发器

此示例创建一个无限期运行的重复作业触发器。

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

以下命令创建一个作业触发器，该触发器将无限期地每 12 个小时运行计划作业一次。该计划从明日 (9/21/2012) 午夜（凌晨 0:00）开始运行。

参数

-At

在指定的日期和时间启动作业。输入一个 DateTime 对象，例如 Get-Date cmdlet 返回的对象，或者输入一个可转换为日期和时间的字符串，例如 April 19, 2012 15:00、12/31 或 3am。如果没有指定日期的元素（例如年份），则触发器中的日期将具有当前日期中的相应元素。

使用 Once 参数时，应将 At 参数的值设置为未来的某个日期和时间。由于 DateTime 对象中的默认日期为当前日期，因此在没有显式日期的情况下指定当前时间之前的某个时间时，将针对过去的某个时间创建作业触发器。

DateTime 对象以及转换为 DateTime 对象的字符串将自动调整为与在控制面板的“区域和语言”中为本地计算机选择的日期和时间格式兼容。

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

-AtLogOn

在指定的用户登录到计算机时，启动计划作业。若要指定某个用户，请使用 User 参数。

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

-AtStartup

在 Windows 启动时，启动计划作业。

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

-Daily

指定一个循环的每日作业计划。使用 Daily 参数集中的其他参数来指定计划详细信息。

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

-DaysInterval

指定启动每日计划之间间隔的天数。例如，值为 3 时将在第 1 天、第 4 天、第 7 天（依此类推）启动计划作业。默认值为 1。

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

-DaysOfWeek

指定在星期几运行每周计划作业。输入星期名称，例如 Monday 或整数 0-6，其中 0 表示星期天。 Weekly 参数集中需要此参数。

在作业触发器中，应将星期几名称转换为其对应的整数值。在某个命令中将星期名称引在引号中时，应单独将每个星期名称引在引号中，例如 "Monday", "Tuesday"。如果将多个星期几名称括在一对引号中，则应合计相应的整数值。例如，"Monday, Tuesday" (1 + 2) 会生成值 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

指定非循环（一次性）计划或自定义的重复计划。若要创建重复计划，请将 Once 参数与 RepetitionDuration 参数和 RepetitionInterval 参数结合使用。

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

-RandomDelay

启用从计划开始时间开始的随机延迟，并设置最大延迟值。针对每次启动以伪随机地方式设置延迟的长度，该长度可从无延迟变化到由此参数值指定的时间。默认值为零 (00:00:00)，表示禁用随机延迟。

输入一个时间跨度对象（例如 New-TimeSpan cmdlet 返回的对象），或输入一个采用 <hours>:<minutes>:<seconds> 格式的值（会自动转换为 TimeSpan 对象）。

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

-RepeatIndefinitely

使用此参数（从 Windows PowerShell 4.0 开始提供），无需为 RepetitionDuration 参数指定 TimeSpan.MaxValue 值即可无限期地重复运行计划作业。

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

-RepetitionDuration

重复运行该作业，直到指定时间到期为止。重复频率由 RepetitionInterval 参数值确定。例如，如果 RepetitionInterval 的值为 5 分钟且 RepetitionDuration 的值为 2 小时，将在两小时内每 5 分钟触发一次该作业。

输入一个时间跨度对象（例如 New-TimeSpan cmdlet 返回的一个对象），或者输入一个可转换为时间跨度对象的字符串（例如 1:05:30）。

若要无限期地运行作业，请改为添加 RepeatIndefinitely 参数。

若要在作业触发器重复持续时间到期之前停止作业，请使用 Set-JobTrigger cmdlet 将 RepetitionDuration 值设置为零 (0)。

仅当命令中使用了 Once、At 和 RepetitionInterval 参数时，此参数才有效。

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

-RepetitionInterval

在指定的时间间隔重复运行作业。例如，如果此参数的值是 2 小时，则将每隔两小时触发该作业一次。默认值为 0，表示不重复该作业。

输入一个时间跨度对象（例如 New-TimeSpan cmdlet 返回的一个对象），或者输入一个可转换为时间跨度对象的字符串（例如 1:05:30）。

仅当命令中使用了 Once、At 和 RepetitionDuration 参数时，此参数才有效。

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

-User

指定可触发计划作业启动 AtLogon 的用户。按 <UserName> 或 <Domain\Username> 格式输入用户名，或者输入一个星号 (*) 来表示所有用户。默认值为所有用户。

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

-Weekly

指定一个循环的每周作业计划。使用 Weekly 参数集中的其他参数来指定计划详细信息。

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

-WeeksInterval

指定启动每周作业计划之间间隔的天数。例如，值为 3 时将在第 1 周、第 4 周、第 7 周（依此类推）启动计划作业。默认值为 1。

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

输入

None

不能通过管道将对象传递给此 cmdlet。

输出

ScheduledJobTrigger

此 cmdlet 返回表示创建的触发器的 ScheduledJobTrigger 对象。

备注

作业触发器不会保存到磁盘。但是，计划作业会保存到磁盘，你可以使用 Get-JobTrigger 获取任何计划作业的作业触发器。
New-JobTrigger 不会阻止你创建将不运行计划作业的作业触发器，例如针对过去某个日期的一次性触发器。
Register-ScheduledJob cmdlet 接受 ScheduledJobTrigger 对象（例如 New-JobTrigger 或 Get-JobTrigger cmdlet 返回的对象）或者具有触发器值的哈希表。

若要提交哈希表，请使用以下键。
- Frequency：Once、Daily、Weekly、AtStartup 或 AtLogon
- At：任何有效的时间字符串，例如 3am
- DaysOfWeek：字符串形式的星期名称的任意组合，例如 "Monday", "Wednesday"
- Interval：任何有效的频率间隔，采用整数形式
- RandomDelay：任何有效的时间跨度字符串，例如 30minutes
- User：任何有效用户，例如 Domain1\User01；仅与 AtLogon 频率值一起使用

通过