New-ScheduledJobOption

参考

模块:: PSScheduledJob

为计划作业创建包含高级选项的对象。

语法

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

说明

New-ScheduledJobOption cmdlet 为计划作业创建包含高级选项的对象。

你可以使用 New-ScheduledJobOption 返回的 ScheduledJobOptions 对象，为新的或现有的计划作业设置作业选项。也可设置作业选项，方法是使用 Get-ScheduledJobOption cmdlet 获取现有计划作业的作业选项，或者使用哈希表值来表示作业选项。

如果没有参数，New-ScheduledJobOption 将生成一个对象，该对象包含所有选项的默认值。由于所有属性都是可编辑的（JobDefinition 属性除外），因此你可以将生成的对象用作模板，并为你的企业创建标准选项对象。

当创建计划作业并设置计划作业选项时，应检查所有计划作业选项的默认值。仅在满足为其执行所设置的所有条件时才运行计划作业。

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

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

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

示例

示例 1：创建具有默认值的计划作业选项对象

此示例创建一个具有默认值的计划作业选项对象。

New-ScheduledJobOption

示例 2：创建一个具有自定义值的计划作业选项对象

此示例创建一个具有自定义值的计划作业选项对象

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       :

以下命令将创建一个计划作业对象，该对象需要网络并运行该计划作业，即使计算机未连接到交流电源也是如此。

输出显示，RequireNetwork 参数将 RunWithoutNetwork 属性的值更改为 $false，而 StartIfOnBattery 参数将 StartIfOnBatteries 属性的值更改为 $true。

示例 3：为新的计划作业设置选项

此示例显示如何使用 New-ScheduledJobOption 返回的 ScheduledJobOptions 对象为新的计划作业设置选项。

$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

第一个命令使用 RunElevated 参数创建 ScheduledJobOptions 对象。它将对象保存在 $runAsAdmin 变量中。

第二个命令使用 Register-ScheduledJob cmdlet 创建新的计划作业。 ScheduledJobOption 参数的值是 $runAsAdmin 变量的值中的选项对象。

第三个命令使用 Get-ScheduledJobOption cmdlet 获取 Backup 计划作业的作业选项。此 cmdlet 输出显示 RunElevated 属性将设置为 $true，并且现在使用 Backup 计划作业的计划作业对象填充作业选项对象的 JobDefinition 属性。

示例 4：对计划作业选项对象的属性排序

此示例显示如何按字母顺序对 ScheduledJobOptions 对象的属性排序以方便阅读。

$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

第一个命令使用 New-ScheduledJobOption cmdlet 创建 ScheduledJobOptions 对象。此命令使用 WakeToRun 参数并将生成的对象保存在 $options 变量中。

为了将 $Options 的属性作为对象获取，第二个命令将使用所有 Windows PowerShell 对象的 PSObject 属性及其 Properties 属性。然后，该命令将属性对象通过管道传送到 Sort-Object cmdlet，该 cmdlet 按名称的字母顺序对属性进行排序，然后将其传送到 Format-Table cmdlet，后者在表中显示属性的名称和值。

借助此格式，可以轻松得多地在 $options 中找到 ScheduledJobOptions 对象的 WakeToRun 属性，并验证其值是否已从 $false 更改为 $true。

参数

-ContinueIfGoingOnBattery

如果计算机在正在运行计划作业时切换到电池电源（断开交流电源），请不要停止运行该作业。默认情况下，计划作业在计算机断开交流电源时将停止运行。

ContinueIfGoingOnBattery 参数将计划作业的 StopIfGoingOnBatteries 属性的值设置为 $true。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-DoNotAllowDemandStart

仅在触发作业时它才启动。用户无法手动启动作业，例如通过使用任务计划程序中的 Run 功能。

此参数仅影响任务计划程序。它不会阻止用户使用 Start-Job cmdlet 来启动作业。

DoNotAllowDemandStart 参数将计划作业的 DoNotAllowDemandStart 属性的值设置为 $true。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-HideInTaskScheduler

不会在任务计划程序中显示作业。此值仅影响运行该作业的计算机。默认情况下，计划任务将显示在任务计划程序中。

即使任务处于隐藏状态，用户也可通过选择任务计划程序中的“显示隐藏任务”视图选项来显示该任务。

HideInTaskScheduler 参数将计划作业的 ShowInTaskScheduler 属性的值设置为 $false。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-IdleDuration

指定在启动作业之前计算机必须处于空闲状态的时长。默认值为 10 分钟。如果在 IdleTimeout 的值过期前，计算机在指定的持续时间内不处于空闲状态，则在下一个计划时间（如果有）之前计划作业不会启动。

输入一个 TimeSpan 对象（例如由 New-TimeSpan cmdlet 生成的对象），或输入一个采用 <小时>:<分钟>:<秒> 格式（会自动转换为 TimeSpan 对象）的值。

若要启用此值，请使用 StartIfIdle 参数。默认情况下，计划作业的 StartIfNotIdle 属性设置为 $true，并且 Windows PowerShell 会忽略 IdleDuration 和 IdleTimeout 值。

类型:	TimeSpan
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-IdleTimeout

指定计划作业等待计算机进入空闲状态的时长。如果超过此超时而计算机仍未在 IdleDuration 参数指定的时间段保持空闲状态，则在下一个计划时间（如果有）之前该作业不会运行。默认值为 1 小时。

输入一个 TimeSpan 对象（例如由 New-TimeSpan cmdlet 生成的对象），或输入一个采用 <小时>:<分钟>:<秒> 格式（会自动转换为 TimeSpan 对象）的值。

若要启用此值，请使用 StartIfIdle 参数。默认情况下，计划作业的 StartIfNotIdle 属性设置为 $true，并且 Windows PowerShell 会忽略 IdleDuration 和 IdleTimeout 值。

类型:	TimeSpan
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-MultipleInstancePolicy

确定系统如何在计划作业的某个实例正在运行时响应启动该作业的其他实例。默认值为 IgnoreNew。此参数的可接受值为：

IgnoreNew - 忽略新的作业实例。
Parallel - 立即启动新的作业实例。
Queue - 在当前实例完成后立即启动新的作业实例。
StopExisting - 停止当前的作业实例，并启动新的实例。

若要运行该作业，必须满足作业计划的所有条件。例如，如果不满足由 RequireNetwork、IdleDuration 和 IdleTimeout 参数设置的条件，则无论此参数的值如何，都不会启动作业实例。

类型:	TaskMultipleInstancePolicy
接受的值:	None, IgnoreNew, Parallel, Queue, StopExisting
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-RequireNetwork

仅在网络连接可用时才运行计划作业。

如果指定了此参数，但网络在计划开始时间不可用，则在下一个计划开始时间（如果有）之前该作业不会运行。

RequireNetwork 参数将计划作业的 RunWithoutNetwork 属性的值设置为 $false。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-RestartOnIdleResume

在计算机处于空闲状态后重新启动计划作业。此参数可与 StopIfGoingOffIdle 参数配合使用，后者会在计算机变为活动状态（退出空闲状态）时暂停正在运行的计划作业。

RestartOnIdleResume 参数将计划作业的 RestartOnIdleResume 属性的值设置为 $true。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-RunElevated

使用运行计划作业的计算机上 Administrators 组成员权限来运行该作业。

若要使计划作业能够使用管理员权限运行，请使用 Register-ScheduledJob 的 Credential 参数为作业提供显式凭据。

RunElevated 参数将计划作业的 RunElevated 属性的值设置为 $true。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-StartIfIdle

如果在 IdleDuration 参数指定的时间到期之前，计算机在 IdleTimeout 参数指定的时间内已处于空闲状态，则启动计划作业。

默认情况下，系统会忽略 IdleDuration 和 IdleTimeout 参数，作业会在计划的开始时间启动，即使计算机处于繁忙状态。

如果指定了此参数，但计算机在计划开始时间处于繁忙状态（不空闲），则在下一个计划开始时间（如果有）之前该作业不会运行。

StartIfIdle 参数将计划作业的 StartIfNotIdle 属性的值设置为 $false。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-StartIfOnBattery

在计划开始时间启动计划作业，即使计算机使用电池电源运行也是如此。默认值为 $false。

StartIfOnBattery 参数将计划作业的 StartIfOnBatteries 属性的值设置为 $true。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-StopIfGoingOffIdle

如果计算机在计划作业正在运行时处于活动状态（不空闲），则挂起运行的作业。

默认情况下，计划作业将在计算机处于活动状态时挂起，而在计算机再次处于空闲状态时恢复运行。若要更改此默认行为，请使用 RestartOnIdleResume 参数。

StopIfGoingOffIdle 参数将计划作业的 StopIfGoingOffIdle 属性的值设置为 $true。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-WakeToRun

在计划开始时间，将计算机从休眠或睡眠状态唤醒，以便它可以运行该作业。默认情况下，如果计算机在计划开始时间处于休眠或睡眠状态，则不会运行该作业。

WakeToRun 参数将计划作业的 WakeToRun 属性的值设置为 $true。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

输入

None

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

输出

ScheduledJobOptions

此 cmdlet 返回表示创建的选项的 ScheduledJobOptions 对象。

备注

可以使用 New-ScheduledJobOption 创建的 ScheduledJobOptions 对象作为 Register-ScheduledJob cmdlet 的 ScheduledJobOption 参数的值。但是，ScheduledJobOption 参数也可以采用一个哈希表值，该值可指定 ScheduledJobOptions 对象的属性及其值，例如：

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

通过