Freigeben über

New-ScheduledJobOption

  • Referenz
Modul:
PSScheduledJob

Erstellt ein Objekt, das erweiterte Optionen für einen geplanten Auftrag enthält.

Syntax

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

Beschreibung

Das New-ScheduledJobOption-Cmdlet erstellt ein Objekt, das erweiterte Optionen für einen geplanten Auftrag enthält.

Sie können das ScheduledJobOptions-Objekt, das New-ScheduledJobOption zurückgibt, verwenden, um Auftragsoptionen für einen neuen oder vorhandenen geplanten Auftrag festzulegen. Alternativ können Sie Auftragsoptionen festlegen, indem Sie das Cmdlet Get-ScheduledJobOption verwenden, um die Auftragsoptionen eines vorhandenen geplanten Auftrags abzurufen, oder indem Sie einen Hashtabellenwert zur Darstellung der Auftragsoptionen verwenden.

Ohne Parameter generiert New-ScheduledJobOption ein Objekt, das die Standardwerte für alle Optionen enthält. Da alle Eigenschaften mit Ausnahme der JobDefinition-Eigenschaft bearbeitet werden können, können Sie das resultierende Objekt als Vorlage verwenden und standardmäßige Optionsobjekte für Ihr Unternehmen erstellen.

Beim Erstellen geplanter Aufträge und Festlegen von Optionen für geplante Aufträge überprüfen Sie die Standardwerte aller Optionen für geplante Aufträge. Geplante Aufträge werden nur ausgeführt, wenn alle für deren Ausführung festgelegten Bedingungen erfüllt sind.

New-ScheduledJobOption ist eine Sammlung von Cmdlets zur Auftragsplanung im PSScheduledJob-Modul, das in Windows PowerShell enthalten ist.

Weitere Informationen zu geplanten Aufträgen finden Sie unter den Info-Themen im PSScheduledJob-Modul. Importieren Sie das PSScheduledJob-Modul, und geben Sie dann Folgendes ein, Get-Help about_Scheduled* oder lesen Sie about_Scheduled_Jobs.

Dieses Cmdlet wurde in Windows PowerShell 3.0 eingeführt.

Beispiele

Beispiel 1: Create eines Optionsobjekts für einen geplanten Auftrag mit Standardwerten

PS C:\> New-ScheduledJobOption
StartIfOnBatteries     : False
StopIfGoingOnBatteries : True
WakeToRun              : False
StartIfNotIdle         : True
StopIfGoingOffIdle     : False
RestartOnIdleResume    : False
IdleDuration           : 00:10:00
IdleTimeout            : 01:00:00
ShowInTaskScheduler    : True
RunElevated            : False
RunWithoutNetwork      : True
DoNotAllowDemandStart  : False
MultipleInstancePolicy : Ignore
NewJobDefinition       :

Dieser Befehl erstellt ein Optionsobjekt für einen geplanten Auftrag, das alle Standardwerte aufweist.

Beispiel 2: Create eines Optionsobjekts für einen geplanten Auftrag mit benutzerdefinierten Werten

PS C:\> 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       :

Der folgende Befehl erstellt ein Objekt für einen geplanten Auftrag, das das Netzwerk erfordert und den geplanten Auftrag selbst dann ausführt, wenn der Computer nicht an das Stromnetz angeschlossen ist.

Die Ausgabe zeigt, dass der RequireNetwork-Parameter den Wert der RunWithoutNetwork-Eigenschaft in $False und der Parameter StartIfOnBattery den Wert der StartIfOnBatteries-Eigenschaft in $True geändert hat.

Beispiel 3: Festlegen von Optionen für einen neuen geplanten Auftrag

The first command creates a **ScheduledJobOptions** object with the *RunElevated* parameter. It saves the object in the $RunAsAdmin variable.
PS C:\> $RunAsAdmin = New-ScheduledJobOption -RunElevated

The second command uses the Register-ScheduledJob cmdlet to create a new scheduled job. The value of the *ScheduledJobOption* parameter is the option object in the value of the $RunAsAdmin variable.
PS C:\> Register-ScheduledJob -Name Backup -FilePath D:\Scripts\Backup.ps1 -Trigger $Mondays -ScheduledJobOption $RunAsAdmin

The third command uses the Get-ScheduledJobOption cmdlet to get the job options of the Backup scheduled job.The cmdlet output shows that the RunElevated property is set to $True and the JobDefinition property of the job option object is now populated with the scheduled job object for the Backup scheduled job.
PS C:\> 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

Dieses Beispiel zeigt, wie Sie das ScheduledJobOptions-Objekt, das von New-ScheduledJobOption zurückgegeben wird, zum Festlegen der Optionen für einen neuen geplanten Auftrag verwenden.

Beispiel 4: Sortieren der Eigenschaften eines Optionsobjekts für einen geplanten Auftrag

PS C:\> $Options = New-ScheduledJobOption -WakeToRun
PS C:\> $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

In diesem Beispiel wird veranschaulicht, wie die Eigenschaften eines ScheduledJobOptions-Objekts in alphabetischer Reihenfolge sortiert werden, um die Lesbarkeit zu verbessern.

Der erste Befehl verwendet das New-ScheduledJobOption-Cmdlet, um ein ScheduledJobOptions-Objekt zu erstellen. Der Befehl verwendet den WakeToRun-Parameter und speichert das resultierende Objekt in der $Options-Variablen.

Um die Eigenschaften von $Options als Objekte abzurufen, verwendet der zweite Befehl die PSObject-Eigenschaft aller Windows PowerShell-Objekte und die zugehörige Properties-Eigenschaft. Der Befehl leitet dann die Eigenschaftsobjekte an das Cmdlet Sort-Object weiter, das die Eigenschaften alphabetisch nach Name sortiert, und dann an das Cmdlet Format-Table, das die Namen und Werte der Eigenschaften in einer Tabelle anzeigt.

Dieses Format erleichtert es, die WakeToRun-Eigenschaft des ScheduledJobOptions-Objekts in $Options zu finden und zu überprüfen, ob der Wert von $False in $True geändert wurde.

Parameter

-ContinueIfGoingOnBattery

Beenden Sie den geplanten Auftrag nicht, wenn der Computer (vom Netzbetrieb) in den Akkubetrieb umschaltet, während der Auftrag ausgeführt wird. Geplante Aufträge werden standardmäßig beendet, wenn der Computer vom Netzbetrieb getrennt wird.

Der ContinueIfGoingOnBattery-Parameter legt den Wert der StopIfGoingOnBatteries-Eigenschaft von geplanten Aufträgen auf $True fest.

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

-DoNotAllowDemandStart

Startet den Auftrag nur, wenn er ausgelöst wird. Benutzer können den Auftrag nicht manuell starten, beispielsweise durch die Funktion „Ausführen“ im Taskplaner.

Dieser Parameter wirkt sich nur auf den Taskplaner aus. Es verhindert nicht, dass Benutzer das Cmdlet Start-Job verwenden, um den Auftrag zu starten.

Der Parameter DoNotAllowDemandStart legt den Wert der DoNotAllowDemandStart-Eigenschaft von geplanten Aufträgen auf $True fest.

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

-HideInTaskScheduler

Zeigt den Auftrag nicht im Taskplaner an. Dieser Wert wirkt sich nur auf den Computer aus, auf dem der Auftrag ausgeführt wird. Standardmäßig werden geplante Tasks im Taskplaner angezeigt.

Auch wenn eine Aufgabe ausgeblendet ist, können Benutzer die Aufgabe anzeigen, indem sie in der Aufgabenplanung die Option Ausgeblendete Aufgaben anzeigen auswählen.

Der HideInTaskScheduler-Parameter legt den Wert der ShowInTaskScheduler-Eigenschaft geplanter Aufträge auf $False fest.

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

-IdleDuration

Gibt an, wie lange der Computer im Leerlauf sein muss, bevor der Auftrag gestartet wird. Der Standardwert beträgt 10 Minuten. Wenn der Computer nicht für die angegebene Dauer im Leerlauf ist, bevor der Wert von IdleTimeout abläuft, wird der geplante Auftrag erst zum nächsten geplanten Zeitpunkt ausgeführt, sofern vorhanden.

Geben Sie ein TimeSpan-Objekt ein, z. B. ein vom cmdlet New-TimeSpan generiertes Objekt, oder geben Sie einen Wert im <Format hours>:<minutes>:<seconds> ein, der automatisch in ein TimeSpan-Objekt konvertiert wird.

Um diesen Wert zu aktivieren, verwenden Sie den StartIfIdle-Parameter. Standardmäßig ist die StartIfNotIdle-Eigenschaft von geplanten Aufträgen auf $True festgelegt, und Windows PowerShell ignoriert die Werte IdleDuration und IdleTimeout.

Type:TimeSpan
Position:Named
Default value:10 minutes (00:10:00)
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IdleTimeout

Gibt an, wie lange der geplante Auftrag während der Leerlaufzeit des Computers wartet. Wenn dieses Timeout abläuft, bevor der Computer für den durch den IdleDuration-Parameter angegebenen Zeitraum im Leerlauf war, wird der Auftrag erst zum nächsten geplanten Zeitpunkt ausgeführt, sofern vorhanden. Der Standardwert beträgt eine Stunde.

Geben Sie ein TimeSpan-Objekt ein, z. B. ein vom cmdlet New-TimeSpan generiertes Objekt, oder geben Sie einen Wert im <Format hours>:<minutes>:<seconds> ein, der automatisch in ein TimeSpan-Objekt konvertiert wird.

Um diesen Wert zu aktivieren, verwenden Sie den StartIfIdle-Parameter. Standardmäßig ist die StartIfNotIdle-Eigenschaft von geplanten Aufträgen auf $True festgelegt, und Windows PowerShell ignoriert die Werte IdleDuration und IdleTimeout.

Type:TimeSpan
Position:Named
Default value:1 hour (1:00:00)
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MultipleInstancePolicy

Bestimmt, wie das System auf eine Anforderung reagiert, eine Instanz eines geplanten Auftrags zu starten, während eine andere Instanz des Auftrags ausgeführt wird. Der Standardwert ist IgnoreNew. Zulässige Werte für diesen Parameter:

  • IgnoreNew. Die neue Auftragsinstanz wird ignoriert.
  • Parallel Die neue Auftragsinstanz wird sofort gestartet.
  • Warteschlange. Die neue Auftragsinstanz wird gestartet, sobald die aktuelle Instanz abgeschlossen ist.
  • StopExisting. Die aktuelle instance des Auftrags wird beendet, und die neue instance wird gestartet.

Um den Auftrag auszuführen, müssen alle Bedingungen für den Auftragszeitplan erfüllt sein. Wenn beispielsweise die Bedingungen, die von den Parametern RequireNetwork, IdleDuration und IdleTimeout festgelegt werden, nicht erfüllt sind, wird der Auftrag instance nicht gestartet, unabhängig vom Wert dieses Parameters.

Type:TaskMultipleInstancePolicy
Accepted values:None, IgnoreNew, Parallel, Queue, StopExisting
Position:Named
Default value:IgnoreNew
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RequireNetwork

Führt den geplanten Auftrag nur aus, wenn Netzwerkverbindungen verfügbar sind.

Wenn Sie diesen Parameter angeben und das Netzwerk zur geplanten Startzeit nicht verfügbar ist, wird der Auftrag erst zur nächsten geplanten Startzeit ausgeführt, falls vorhanden.

Der RequireNetwork-Parameter legt den Wert der RunWithoutNetwork-Eigenschaft von geplanten Aufträgen auf $False fest.

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

-RestartOnIdleResume

Startet einen geplanten Auftrag neu, sobald der Computer im Leerlauf ist. Dieser Parameter arbeitet mit dem StopIfGoingOffIdle-Parameter zusammen, durch den ein aktuell ausgeführter geplanter Auftrag angehalten wird, wenn der Computer aktiv wird (den Leerlaufzustand verlässt).

Der Parameter RestartOnIdleResume legt den Wert der RestartOnIdleResume-Eigenschaft von geplanten Aufträgen auf $True fest.

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

-RunElevated

Führt den geplanten Auftrag mit den Berechtigungen eines Mitglieds der Gruppe "Administratoren" auf dem Computer aus, auf dem der Auftrag ausgeführt wird.

Um die Ausführung eines geplanten Auftrags mit Administratorberechtigungen zu aktivieren, verwenden Sie den Credential-Parameter von Register-ScheduledJob, um explizite Anmeldeinformationen für den Auftrag bereitzustellen.

Der Parameter RunElevated legt den Wert der RunElevated-Eigenschaft geplanter Aufträge auf $True fest.

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

-StartIfIdle

Startet den geplanten Auftrag, wenn der Computer für die durch den IdleDuration-Parameter angegebene Zeit im Leerlauf war und bevor die durch den IdleTimeout-Parameter angegebene Zeit abgelaufen ist.

Standardmäßig werden der IdleDuration-Parameter und IdleTimeout-Parameter ignoriert und der Auftrag zur geplanten Startzeit gestartet, selbst wenn der Computer ausgelastet ist.

Wenn Sie diesen Parameter angeben und der Computer zur geplanten Startzeit ausgelastet (nicht im Leerlauf) ist, wird der Auftrag erst zur nächsten geplanten Startzeit ausgeführt, falls vorhanden.

Der Parameter StartIfIdle legt den Wert der StartIfNotIdle-Eigenschaft geplanter Aufträge auf $False fest.

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

-StartIfOnBattery

Startet den geplanten Auftrag, selbst wenn der Computer zur geplanten Startzeit im Akkubetrieb ausgeführt wird. Der Standardwert ist $False.

Der Parameter StartIfOnBattery legt den Wert der StartIfOnBatteries-Eigenschaft von geplanten Aufträgen auf $True fest.

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

-StopIfGoingOffIdle

Hält einen aktuell ausgeführten geplanten Auftrag an, wenn der Computer aktiv wird (aus dem Leerlauf wechselt), während der Auftrag ausgeführt wird.

Ein geplanter Auftrag, der angehalten wird, wenn der Computer aktiv wird, wird standardmäßig fortgesetzt, sobald der Computer wieder im Leerlauf ist. Um dieses Standardverhalten zu ändern, verwenden Sie den RestartOnIdleResume-Parameter.

Der Parameter StopIfGoingOffIdle legt den Wert der StopIfGoingOffIdle-Eigenschaft von geplanten Aufträgen auf $True fest.

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

-WakeToRun

Aktiviert den Computer zur geplanten Startzeit aus dem Ruhezustand oder Standbymodus, damit der Auftrag ausgeführt werden kann. Wenn sich der Computer zur geplanten Startzeit im Ruhezustand oder Standbymodus befindet, wird der Auftrag standardmäßig nicht ausgeführt.

Der WakeToRun-Parameter legt den Wert der WakeToRun-Eigenschaft geplanter Aufträge auf $True fest.

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

Eingaben

None

Eingaben können nicht an dieses Cmdlet weitergereicht werden.

Ausgaben

ScheduledJobOptions

Hinweise

  • Sie können das ScheduledJobOptions-Objekt , das New-ScheduledJobOption erstellt, als Wert des ScheduledJobOption-Parameters des cmdlets Register-ScheduledJob verwenden. Der ScheduledJobOption-Parameter kann jedoch auch einen Hashtabellenwert annehmen, der die Eigenschaften des ScheduledJobOptions-Objekts und deren Werte angibt, z. B.:

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