Register-ScheduledJob

模块:

PSScheduledJob

创建计划作业。

语法

Register-ScheduledJob
        [-ScriptBlock] <ScriptBlock>
        [-Name] <String>
        [-Trigger <ScheduledJobTrigger[]>]
        [-InitializationScript <ScriptBlock>]
        [-RunAs32]
        [-Credential <PSCredential>]
        [-Authentication <AuthenticationMechanism>]
        [-ScheduledJobOption <ScheduledJobOptions>]
        [-ArgumentList <Object[]>]
        [-MaxResultCount <Int32>]
        [-RunNow]
        [-RunEvery <TimeSpan>]
        [-WhatIf]
        [-Confirm]
        [<CommonParameters>]

Register-ScheduledJob
        [-FilePath] <String>
        [-Name] <String>
        [-Trigger <ScheduledJobTrigger[]>]
        [-InitializationScript <ScriptBlock>]
        [-RunAs32]
        [-Credential <PSCredential>]
        [-Authentication <AuthenticationMechanism>]
        [-ScheduledJobOption <ScheduledJobOptions>]
        [-ArgumentList <Object[]>]
        [-MaxResultCount <Int32>]
        [-RunNow]
        [-RunEvery <TimeSpan>]
        [-WhatIf]
        [-Confirm]
        [<CommonParameters>]

说明

Register-ScheduledJob cmdlet 可在本地计算机上创建计划作业。

计划作业是一个Windows PowerShell后台作业，可按一次性或定期计划自动启动。 计划作业存储在磁盘上并且已在任务计划程序中注册，因此可在任务计划程序中或者通过在 Windows PowerShell 中使用 Scheduled Job cmdlet 来对其进行管理。

计划作业启动时，它会创建计划的作业的实例。 除了结果保存在磁盘上以外，计划作业实例与 Windows PowerShell 后台作业相同。 使用作业 cmdlet（例如 Start-Job、Get-Job 和 Receive-Job）启动、查看和获取作业实例的结果。

使用 Register-ScheduledJob 来创建新的计划作业。 若要指定计划作业运行的命令，请使用 ScriptBlock 参数；若要指定作业运行的脚本，请使用 FilePath 参数。

Windows PowerShell计划作业使用相同的作业触发器和任务计划程序用于计划任务的作业选项。

Register-ScheduledJob 的 Trigger 参数添加用于启动作业的一个或多个作业触发器。 触发器参数是可选的，因此可以在创建计划作业时添加触发器，稍后添加作业触发器，添加 RunNow 参数以立即启动作业，使用 Start-Job cmdlet 随时启动作业，或将未尝试的计划作业另存为其他作业的模板。

使用 Options 参数可自定义计划作业的选项设置。 Options 参数也是可选项，因此你可以在创建计划作业时设置作业选项，或随时更改这些选项。 由于作业选项设置可能会阻止计划作业运行，因此需检查作业选项并小心设置它们。

Register-ScheduledJob 是 PSScheduledJob 模块中包含在 Windows PowerShell 中的作业计划 cmdlet 集合之一。

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

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

示例

示例 1：创建计划作业

PS C:\> Register-ScheduledJob -Name "Archive-Scripts" -ScriptBlock { dir $home\*.ps1 -Recurse | Copy-Item -Destination "\\Server\Share\PSScriptArchive" }

此命令创建 Archive-Scripts 计划作业。 ScriptBlock 参数值包含一个命令，用于采用递归方式在 $home 目录下搜索 .ps1 文件，并将这些文件复制到文件共享中的目录。

因为计划作业不包含触发器，因此它无法自动启动。 以后可以使用添加作业触发器，使用 Start-Job cmdlet 按需启动作业，或使用计划作业作为其他计划作业的模板。

示例 2：使用触发器和自定义选项创建计划作业

The first command uses the New-ScheduledJobOption cmdlet to create a job option object, which it saves in the $O parameter. The options start the scheduled job even if the computer is not idle, wake the computer to run the job, if necessary, and allows multiple instances of the job to run in a series.
PS C:\> $O = New-ScheduledJobOption -WakeToRun -StartIfNotIdle -MultipleInstancesPolicy Queue


The second command uses the New-JobTrigger cmdlet to create job trigger that starts a job every other Monday at 9:00 PM.
PS C:\> $T = New-JobTrigger -Weekly -At "9:00 PM" -DaysOfWeek Monday -WeeksInterval 2

This command creates the UpdateVersion scheduled job, which runs the UpdateVersion.ps1 script every Monday at 9:00 p.m. The command uses the *FilePath* parameter to specify the script that the job runs. It uses the *Trigger* parameter to specify the job triggers in the $T variable and the *ScheduledJobOption* parameter to specify the option object in the $O variable.
PS C:\> Register-ScheduledJob -Name "UpdateVersion" -FilePath "\\Srv01\Scripts\UpdateVersion.ps1" -Trigger $T -ScheduledJobOption $O

此示例显示了如何创建具有作业触发器和自定义作业选项的计划作业。

示例 3：使用哈希表指定触发器和作业选项

PS C:\> Register-ScheduledJob -FilePath "\\Srv01\Scripts\Update-Version.ps1" -Trigger @{Frequency=Weekly; At="9:00PM"; DaysOfWeek="Monday"; Interval=2} -ScheduledJobOption @{WakeToRun; StartIfNotIdle; MultipleInstancesPolicy="Queue"}

此命令具有与示例 2 中的命令相同的作用。 它创建计划作业，但使用哈希表来指定 Trigger 和 ScheduledJobOption 参数的值。

示例 4：在远程计算机上创建计划作业

PS C:\> Invoke-Command -ComputerName (Get-Content Servers.txt) -ScriptBlock {Register-ScheduledJob -Name "Get-EnergyData" -FilePath "\\Srv01\Scripts\Get-EnergyData.ps1" -ScheduledJobOption $O -Trigger $T } -Credential $Cred

此命令在多台远程计算机上创建 EnergyData 计划作业。 此计划作业运行可用于收集原始数据的脚本，并将该脚本保存在正在运行的日志中。 在远程计算机上，创建、运行这些计划作业并存储其结果。

该命令使用 Invoke-Command cmdlet 在 Servers.txt 文件中的计算机上运行 Register-ScheduledJob 命令。 Invoke-Command 命令使用 Credential 参数提供有权在 Servers.txt 文件中的计算机上创建计划的作业的用户的凭据。

Register-ScheduledJob 命令在远程计算机上创建计划作业，该作业在$T变量中由作业触发器指定的计划上运行EnergyData.ps1脚本。 该脚本位于文件服务器上且可用于所有参与的计算机。

示例 5：创建在远程计算机上运行脚本的计划作业

PS C:\> Register-ScheduledJob -Name "CollectEnergyData" -Trigger $T -MaxResultCount 99 -ScriptBlock { Invoke-Command -AsJob -ComputerName (Servers.txt) -FilePath "\\Srv01\Scripts\Get-EnergyData.ps1" -Credential $Admin -Authentication CredSSP }

此命令使用 Register-ScheduledJob cmdlet 在本地计算机上创建 CollectEnergyData 计划作业。 此命令使用 Trigger 参数指定作业计划，并使用 MaxResultCount 参数将保存的结果数增加至 99。

CollectEnergyData 作业使用 Invoke-Command cmdlet 在Servers.txt文件中列出的计算机上以后台形式运行EnergyData.ps1脚本。 Invoke-Command 命令使用 AsJob 参数在本地计算机上创建后台作业对象，即使Energydata.ps1脚本在远程计算机上运行也是如此。 此命令使用 Credential 参数来指定有权在远程计算机上运行脚本的用户帐户，并使用值为 CredSSP 的 Authentication 参数以允许使用委派的凭据。

参数

-ArgumentList

指定由 FilePath 参数指定的脚本的参数值，或者指定由 ScriptBlock 参数指定的命令的值。

Type:	Object[]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Authentication

指定用于对用户的凭据进行身份验证的机制。 此参数的可接受值为：

• 默认
• 基本
• Credssp
• 摘要
• Kerberos
• Negotiate
• NegotiateWithImplicitCredential

默认值为 Default。 有关此参数的值的详细信息，请参阅 MSDN 库中的 AuthenticationMechanism 枚举 。

注意：在凭据安全服务提供程序 (CredSSP) 身份验证中，用户凭据传递到远程计算机中以进行验证，这种验证用于要求对多个资源（例如访问远程网络共享）进行验证的命令。 此机制增加了远程操作的安全风险。 如果远程计算机的安全受到威胁，则传递给该计算机的凭据可用于控制网络会话。

Type:	AuthenticationMechanism
Accepted values:	Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Position:	Named
Default value:	Default
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Confirm

提示你在运行 cmdlet 之前进行确认。

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

-Credential

指定有权运行计划作业的用户帐户。 默认为当前用户。

键入用户名（如 User01 或 Domain01\User01），或输入 PSCredential 对象，例如Get-Credential cmdlet 中的一个。 如果只输入用户名，系统会提示输入密码。

Type:	PSCredential
Position:	Named
Default value:	Current user
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-FilePath

指定计划作业运行的脚本。 在本地计算机上输入指向 .ps1 文件的路径。 若要指定脚本参数的默认值，请使用 ArgumentList 参数。 每个 Register-ScheduledJob 命令都必须使用 ScriptBlock 或 FilePath 参数。

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

-InitializationScript

指定指向 Windows PowerShell 脚本 (.ps1) 的完全限定路径。 在会话中运行针对后台作业而创建的初始化脚本，然后再运行由 ScriptBlock 参数指定的命令或由 FilePath 参数指定的脚本。 可使用初始化脚本配置会话，例如添加文件、函数或别名、创建目录或者检查必备项。

若要指定用于运行主作业命令的脚本，请使用 FilePath 参数。

如果初始化脚本 (甚至) 出现非终止错误，则计划的作业的当前实例不会运行并且其状态为“失败”。

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

-MaxResultCount

指定为计划作业保留的作业结果项数。 默认值为 32。

Windows PowerShell 将计划作业的每个触发实例的执行历史记录和结果都保存在磁盘上。 此参数的值可确定为此计划作业保存的作业实例结果数。 当作业实例结果数超过此值时，Windows PowerShell 将删除最旧的作业实例结果，以便为最新的作业实例结果腾出空间。

作业执行历史记录和作业结果保存在创建作业的计算机上$home\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs\<JobName>\Output\<Timestamp> 目录。 若要查看执行历史记录，请使用 Get-Job cmdlet。 若要获取作业结果，请使用 Receive-Job cmdlet。

MaxResultCount 参数设置计划作业的 ExecutionHistoryLength 属性值。

若要删除当前执行历史记录和作业结果，请使用 Set-ScheduledJob cmdlet 的 ClearExecutionHistory 参数。

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

-Name

指定计划作业的名称。 该名称也用于计划作业的所有启动实例。 该名称在计算机上必须唯一。 此参数是必需的。

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

-RunAs32

在 32 位进程中运行计划作业。

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

-RunEvery

用于指定运行作业的频率。 例如，使用此选项每 15 分钟运行一次作业。

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

-RunNow

运行 Register-ScheduledJob cmdlet 后，立即启动作业。 通过使用此参数，使得触发器任务计划程序无需在注册后立即运行 Windows PowerShell 脚本，而且用户无需创建可指定启动日期和时间的触发器。

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

-ScheduledJobOption

设置计划作业的选项。 输入 ScheduledJobOptions 对象，例如使用 New-ScheduledJobOption cmdlet 或哈希表值创建的对象。

注册计划作业或使用Set-ScheduledJobOption或Set-ScheduledJob cmdlet 更改选项时，可以为计划作业设置选项。

许多选项及其默认值都可确定是否运行计划作业以及运行时间。 在计划某个作业之前，务必检查这些选项。 有关计划作业选项的说明，包括默认值，请参阅 New-ScheduledJobOption。

若要提交哈希表，请使用以下键。 在下列哈希表中，这些键与其默认值一起显示。

@{StartIfOnBattery=$False; StopIfGoingOnBattery=$True; WakeToRun=$False; StartIfNotIdle=$False; IdleDuration="00:10:00"; IdleTimeout="01:00:00"; StopIfGoingOffIdle=$True; RestartOnIdleResume=$False; ShowInTaskScheduler=$True; RunElevated=$False; RunWithoutNetwork=$False; DoNotAllowDemandStart=$False; MultipleInstancePolicy=IgnoreNew}

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

-ScriptBlock

指定计划作业运行的命令。 用大括号 ({ }) 括起命令以形成脚本块。 若要指定命令参数的默认值，请使用 ArgumentList 参数。

每个 Register-ScheduledJob 命令都必须使用 ScriptBlock 或 FilePath 参数。

Type:	ScriptBlock
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Trigger

指定计划作业的触发器。 输入一个或多个 ScheduledJobTrigger 对象，例如New-JobTrigger cmdlet 返回的对象，或作业触发器键和值的哈希表。

作业触发器启动计划作业。 该触发器可指定一次性或循环计划作业或者事件，例如在用户进行登录或 Windows 启动时。

Trigger 参数为可选参数。 可以在创建计划作业、使用 Add-JobTrigger、Set-JobTrigger 或Set-ScheduledJob cmdlet 在以后添加或更改作业触发器时添加触发器，或使用 Start-Job cmdlet 立即启动计划作业。 你还可以在没有用作模板的触发器的情况下创建和保留计划作业。

若要提交哈希表，请使用以下键：

@{Frequency="Once" (或每日、每周、AtStartup、AtLogon) ; At="3am" (或任何有效的时间字符串) ; DaysOfWeek="Monday", "Wednesday" (或日期名称的任意组合) ; Interval=2 (或任何有效的频率间隔) ; RandomDelay="30minutes" (或任何有效的时间跨度字符串) ; User="Domain1\User01" (或任何有效用户;仅用于 AtLogon 频率值) }

Type:	ScheduledJobTrigger[]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-WhatIf

显示在此 cmdlet 运行的情况下将会发生什么。 此 cmdlet 未运行。

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

输入

None

不能通过管道将输入传递给此 cmdlet。

输出

Microsoft.PowerShell.ScheduledJob.ScheduledJobDefinition

备注

• 每个计划作业都保存在本地计算机上的 $home\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs 目录的子目录中。 子目录为计划作业命名，并包含计划的作业的 XML 文件及其执行历史记录的记录。 有关磁盘上计划作业的详细信息，请参阅 about_Scheduled_Jobs_Advanced。

• 在 Windows PowerShell 中创建的计划作业会显示在 Task Scheduler Library\Microsoft\Windows\PowerShell\ScheduledJobs 文件夹中的任务计划程序中。 你可以使用任务计划程序查看和编辑计划作业。

• 你可以使用任务计划程序、SchTasks.exe 命令行工具和 Task Scheduler cmdlet 来管理使用 Scheduled Job cmdlet 创建的计划作业。 但是，你无法使用 Scheduled Job cmdlet 来管理在任务计划程序中创建的任务。

• 如果计划作业命令失败，则 Windows PowerShell 将返回一条错误消息。 但是，如果作业在任务计划程序尝试运行它时失败，则 Windows PowerShell 将不返回此错误。

  如果计划作业未运行，请使用以下方法查找原因。

• 验证作业触发器是否已正确设置。 -- 验证作业选项中设置的条件是否满足。
• 验证运行作业的用户帐户是否有权在作业中运行命令或脚本。
• 检查任务计划程序历史记录是否存在错误
• 检查任务计划程序事件日志中是否存在错误。

有关详细信息，请参阅 about_Scheduled_Jobs_Troubleshooting。

相关链接

• about_Scheduled_Jobs
• Add-JobTrigger
• Disable-JobTrigger
• Disable-ScheduledJob
• Enable-JobTrigger
• Enable-ScheduledJob
• Get-JobTrigger
• Get-ScheduledJob
• Get-ScheduledJobOption
• New-JobTrigger
• New-ScheduledJobOption
• Register-ScheduledJob
• Remove-JobTrigger
• Set-JobTrigger
• Set-ScheduledJob
• Set-ScheduledJobOption
• Unregister-ScheduledJob