共用方式為

Register-ScheduledJob

  • 參考
模組:
PSScheduledJob

建立排程的工作。

Syntax

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

Description

Register-ScheduledJob Cmdlet 會在本機電腦上建立排程工作。

排程工作是一種 Windows PowerShell 背景工作，可在一次性或週期性排程上自動啟動。 排程工作是儲存在磁碟上並在 [工作排程器] 中登錄，因此您可以在 [工作排程器] 中管理它們，或使用 Windows PowerShell 中的排程工作 Cmdlet 來管理它們。

當排程工作啟動時，它會建立排程工作的實例。 排程工作執行個體類似 Windows PowerShell 背景工作，但排程工作的結果會儲存在磁碟上。 使用 Job Cmdlet，例如 Start-Job、Get-Job 和 Receive-Job 來啟動、檢視和取得作業實例的結果。

使用 Register-ScheduledJob 來建立新的排程工作。 若要指定排程工作執行的命令，請使用 ScriptBlock 參數；若要指定工作執行的指令碼，請使用 FilePath 參數。

Windows PowerShell 排程工作使用相同的工作觸發程式和工作選項，工作排程器用於排程工作。

Register-ScheduledJob 的 Trigger 參數會新增一或多個可啟動工作的工作觸發程序。 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：Create 排程工作

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：Create 具有觸發程式和自定義選項的排程工作

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：Create 遠端電腦上的排程工作

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：Create 在遠端電腦上執行腳本的排程工作

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

指定用來驗證使用者認證的機制。 此參數可接受的值為：

  • Default
  • 基本資訊
  • Credssp
  • Digest
  • Kerberos
  • 交涉
  • 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" (或 Daily、Weekly、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。

輸出

ScheduledJobDefinition

備註

  • 每個排程工作都是儲存在本機電腦之 $home\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs 目錄的子目錄中。 子目錄會針對排程工作命名，並包含排程作業的 XML 檔案，以及其執行歷程記錄的記錄。 如需有關磁碟上之排程工作的詳細資訊，請參閱 about_Scheduled_Jobs_Advanced。

  • 您在 Windows PowerShell 中建立的排程工作會出現在 [工作排程器] 的 [工作排程器程式庫\Microsoft\Windows\PowerShell\ScheduledJobs] 資料夾。 您可以使用 [工作排程器] 來檢視及編輯排程工作。

  • 您可以使用 [工作排程器]、SchTasks.exe 命令列工具或「工作排程器」Cmdlet 來管理使用「排程工作」Cmdlet 建立的排程工作。 不過，您無法使用「排程工作」Cmdlet 來管理您在 [工作排程器] 中建立的工作。

  • 若排程工作命令失敗，Windows PowerShell 會傳回錯誤訊息。 不過，若當 [工作排程器] 嘗試執行工作時失敗，該錯誤不會顯示在 Windows PowerShell 中。

    如果排程的作業未執行，請使用下列方法來尋找原因。

  • 確認已正確設定作業觸發程式。 -- 確認作業選項中設定的條件已滿足。
  • 確認作業執行所在的用戶帳戶具有在作業中執行命令或腳本的許可權。
  • 檢查工作排程器歷程記錄中是否有錯誤
  • 檢查工作排程器事件記錄檔中是否有錯誤。

如需詳細資訊，請參閱 about_Scheduled_Jobs_Troubleshooting。