Register-ScheduledJob

Hiermee maakt u een geplande taak.

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

De Register-ScheduledJob cmdlet maakt geplande taken op de lokale computer.

Een geplande taak is een Windows PowerShell achtergrondtaak die automatisch kan worden gestart volgens een eenmalige of terugkerende planning. Geplande taken worden opgeslagen op schijf en geregistreerd in Task Scheduler. De taken kunnen worden beheerd in Task Scheduler of met behulp van de cmdlets geplande taken in Windows PowerShell.

Wanneer een geplande taak wordt gestart, wordt er een exemplaar van de geplande taak gemaakt. Geplande taakexemplaren zijn identiek aan Windows PowerShell achtergrondtaken, behalve dat de resultaten op schijf worden opgeslagen. Gebruik de taak-cmdlets, zoals Start-Job, Get-Joben Receive-Job om de resultaten van de taakexemplaren te starten, weer te geven en op te halen.

Hiermee Register-ScheduledJob maakt u een nieuwe geplande taak. Gebruik de parameter ScriptBlock om de opdrachten op te geven die door de geplande taak worden uitgevoerd. Als u een script wilt opgeven dat door de taak wordt uitgevoerd, gebruikt u de parameter FilePath .

Windows PowerShell geplande taken gebruiken dezelfde taaktriggers en taakopties die Task Scheduler gebruikt voor geplande taken.

De parameter Trigger van het toevoegen van Register-ScheduledJob een of meer taaktriggers die de taak starten. De parameter Trigger is optioneel, zodat u triggers kunt toevoegen wanneer u de geplande taak maakt, later taaktriggers toevoegt, de parameter RunNow toevoegt om de taak onmiddellijk te starten, de Start-Job cmdlet gebruikt om de taak onmiddellijk te starten of de geplande taak zonder trigger op te slaan als sjabloon voor andere taken.

Met de parameter Opties kunt u de opties voor de geplande taak aanpassen. De parameter Opties is optioneel, zodat u taakopties kunt instellen wanneer u de geplande taak maakt of deze op elk gewenst moment wijzigt. Omdat taakoptie-instellingen kunnen voorkomen dat de geplande taak wordt uitgevoerd, controleert u de taakopties en stelt u deze zorgvuldig in.

Register-ScheduledJobis een van een verzameling cmdlets voor taakplanning in de PSScheduledJob-module die is opgenomen in Windows PowerShell.

Zie de artikelen Over in de PSScheduledJob-module voor meer informatie over geplande taken. Importeer de PSScheduledJob-module en typ vervolgens: Get-Help about_Scheduled* of zie about_Scheduled_Jobs.

Deze cmdlet is geïntroduceerd in Windows PowerShell 3.0.

Voorbeelden

Voorbeeld 1: Een geplande taak maken

In dit voorbeeld wordt een geplande taak gemaakt op de lokale computer.

Register-ScheduledJob -Name "Archive-Scripts" -ScriptBlock {
  Get-ChildItem $home\*.ps1 -Recurse |
    Copy-Item -Destination "\\Server\Share\PSScriptArchive"
}

Register-ScheduledJob gebruikt de parameter Name om de Archive-Scripts geplande taak te maken. De parameter ScriptBlock wordt uitgevoerd Get-ChildItem die recursief in de $home map zoekt naar .ps1 bestanden. De Copy-Item cmdlet kopieert de bestanden naar een map die is opgegeven door de doelparameter.

Omdat de geplande taak geen trigger bevat, wordt deze niet automatisch gestart. U kunt taaktriggers toevoegen met Add-JobTrigger, de Start-Job cmdlet gebruiken om de taak op aanvraag te starten of de geplande taak gebruiken als sjabloon voor andere geplande taken.

Voorbeeld 2: Een geplande taak maken met triggers en aangepaste opties

In dit voorbeeld ziet u hoe u een geplande taak maakt met een taaktrigger en aangepaste taakopties.

$O = New-ScheduledJobOption -WakeToRun -StartIfIdle -MultipleInstancePolicy Queue
$T = New-JobTrigger -Weekly -At "9:00 PM" -DaysOfWeek Monday -WeeksInterval 2
$path = "\\Srv01\Scripts\UpdateVersion.ps1"
Register-ScheduledJob -Name "UpdateVersion" -FilePath $path -ScheduledJobOption $O -Trigger $T

Met $O de variabele wordt het taakoptieobject opgeslagen dat door de New-ScheduledJobOption cmdlet is gemaakt. Met de opties wordt de geplande taak gestart, zelfs als de computer niet inactief is, wordt de computer geactiveerd om de taak uit te voeren, indien nodig en kunnen meerdere exemplaren van de taak in een reeks worden uitgevoerd.

Met $T de variabele wordt het resultaat van de New-JobTrigger cmdlet opgeslagen om een taaktrigger te maken die elke andere maandag om 19:00 uur een taak start.

Met $path de variabele wordt het pad naar het UpdateVersion.ps1 scriptbestand opgeslagen.

Register-ScheduledJob gebruikt de naamparameter om de geplande UpdateVersion-taak te maken. De FilePath-parameter gebruikt $path om het script op te geven dat door de taak wordt uitgevoerd. De parameter ScheduledJobOption maakt gebruik van de taakopties die zijn opgeslagen in $O. De parameter Trigger maakt gebruik van de taaktriggers die zijn opgeslagen in $T.

Voorbeeld 3: Hash-tabellen gebruiken om een trigger en geplande taakopties op te geven

Dit voorbeeld heeft hetzelfde effect als de opdracht in voorbeeld 2. Er wordt een geplande taak gemaakt met behulp van hashtabellen om de waarden van de parameters Trigger en ScheduledJobOption op te geven. De $O variabelen die $Tin voorbeeld 2 zijn gedefinieerd, worden vervangen door hashtabellen.

$T = @{
  Frequency="Weekly"
  At="9:00PM"
  DaysOfWeek="Monday"
  Interval=2
}
$O = @{
  WakeToRun=$true
  StartIfNotIdle=$false
  MultipleInstancePolicy="Queue"
}
Register-ScheduledJob -Trigger $T -ScheduledJobOption $O -Name UpdateVersion -FilePath "\\Srv01\Scripts\Update-Version.ps1"

Voorbeeld 4: Geplande taken maken op externe computers

In dit voorbeeld wordt de geplande Taak EnergyData gemaakt op meerdere externe computers. De geplande taak voert een script uit dat onbewerkte gegevens verzamelt en opslaat in een actief logboek op de externe computer.

$Cred = Get-Credential
$O = New-ScheduledJobOption -WakeToRun -StartIfIdle -MultipleInstancePolicy Queue
$T = New-JobTrigger -Weekly -At "9:00 PM" -DaysOfWeek Monday -WeeksInterval 2
Invoke-Command -ComputerName (Get-Content Servers.txt) -Credential $Cred -ScriptBlock {
  $params = @{
      Name = "Get-EnergyData"
      FilePath = "\\Srv01\Scripts\Get-EnergyData.ps1"
      ScheduledJobOption = $using:O
      Trigger = $using:T
  }
  Register-ScheduledJob @params
}

De $Cred variabele slaat referenties op in een PSCredential-object voor een gebruiker met machtigingen voor het maken van geplande taken. Met $O de variabele worden de taakopties opgeslagen die zijn gemaakt met New-ScheduledJobOption. Met $T de variabele worden de taaktriggers opgeslagen die zijn gemaakt met New-JobTrigger.

De Invoke-Command cmdlet gebruikt de parameter ComputerName om een lijst met servernamen op te halen uit het Servers.txt bestand. Met de referentieparameter wordt het referentieobject opgehaald dat is opgeslagen in $Cred. De parameter ScriptBlock voert een Register-ScheduledJob opdracht uit op de computers in het Servers.txt bestand.

De parameters voor Register-ScheduledJob worden gedefinieerd door $params. De naamparameters specificeert de taak is benoemd Get-EnergyData op elke externe computer. FilePath biedt de locatie van het EnergyData.ps1 script. Het script bevindt zich op een bestandsserver die beschikbaar is voor alle deelnemende computers. De taak wordt uitgevoerd volgens het schema dat is opgegeven door de taaktriggers in $T en de taakopties in $O.

Met Register-ScheduledJob @params de opdracht maakt u de geplande taak met de parameters uit het scriptblok.

Voorbeeld 5: Een geplande taak maken die een script uitvoert op externe computers

In dit voorbeeld wordt de geplande taak CollectEnergyData gemaakt op de lokale computer. De taak wordt uitgevoerd op meerdere externe computers.

$Admin = Get-Credential
$T = New-JobTrigger -Weekly -At "9:00 PM" -DaysOfWeek Monday -WeeksInterval 2
Register-ScheduledJob -Name "CollectEnergyData" -Trigger $T -MaxResultCount 99 -ScriptBlock {
  $params = @{
    AsJob = $true
    ComputerName = (Get-Content Servers.txt)
    FilePath = '\\Srv01\Scripts\Get-EnergyData.ps1'
    Credential = $using:Admin
    Authentication = 'CredSSP'
  }
  Invoke-Command @params
}

De $Admin variabele slaat referenties op voor een gebruiker met machtigingen om de opdrachten uit te voeren in een PSCredential-object . Met $T de variabele worden de taaktriggers opgeslagen die zijn gemaakt met New-JobTrigger.

De Register-ScheduledJob cmdlet gebruikt de parameter Name om de geplande taak CollectEnergyData op de lokale computer te maken. De parameter Trigger geeft de taaktriggers in $T en de parameter MaxResultCount verhoogt het aantal opgeslagen resultaten tot 99.

De parameter ScriptBlock definieert de Invoke-Command parameters met $params. Met de parameter AsJob wordt het achtergrondtaakobject op de lokale computer gemaakt, ook al wordt het Energydata.ps1 script uitgevoerd op de externe computers. De parameter ComputerName haalt een lijst met servernamen op uit het Servers.txt bestand. De referentieparameter geeft een gebruikersaccount op dat gemachtigd is om scripts uit te voeren op de externe computers. En de verificatieparameter geeft een waarde van CredSSP op om gedelegeerde referenties toe te staan.

De Invoke-Command @params opdracht wordt uitgevoerd met de parameters uit het scriptblok.

Parameters

-ArgumentList

Hiermee geeft u waarden op voor de parameters van het script dat is opgegeven door de FilePath-parameter of voor de opdracht die is opgegeven door de ScriptBlock-parameter .

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

Hiermee wordt u gevraagd om bevestiging voordat u de cmdlet uitvoert.

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

Hiermee geeft u een gebruikersaccount met machtigingen voor het uitvoeren van de geplande taak. Standaard is dit de huidige gebruiker.

Typ een gebruikersnaam, zoals User01 of Domain01\User01, of voer een PSCredential-object in, zoals een object uit de Get-Credential cmdlet. Als u alleen een gebruikersnaam invoert, wordt u gevraagd om een wachtwoord.

Referenties worden opgeslagen in een PSCredential-object en het wachtwoord wordt opgeslagen als securestring.

Notitie

Zie Hoe veilig is SecureString?voor meer informatie over SecureString-gegevensbeveiliging.

Type:PSCredential
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-FilePath

Hiermee geeft u een script op dat door de geplande taak wordt uitgevoerd. Voer het pad naar een .ps1 bestand op de lokale computer in. Als u standaardwaarden voor de scriptparameters wilt opgeven, gebruikt u de parameter ArgumentList . Elke Register-ScheduledJob opdracht moet de scriptblock - of FilePath-parameters gebruiken.

Type:String
Position:1
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-InitializationScript

Hiermee geeft u het volledig gekwalificeerde pad naar een Windows PowerShell script (.ps1). Het initialisatiescript wordt uitgevoerd in de sessie die is gemaakt voor de achtergrondtaak vóór de opdrachten die zijn opgegeven door de parameter ScriptBlock of het script dat is opgegeven door de FilePath-parameter . U kunt het initialisatiescript gebruiken om de sessie te configureren, zoals het toevoegen van bestanden, functies of aliassen, het maken van mappen of het controleren op vereisten.

Als u een script wilt opgeven waarmee de primaire taakopdrachten worden uitgevoerd, gebruikt u de parameter FilePath .

Als het initialisatiescript een fout genereert, zelfs een niet-afsluitfout, wordt het huidige exemplaar van de geplande taak niet uitgevoerd en is de status mislukt.

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

Hiermee geeft u op hoeveel vermeldingen voor taakresultaten worden onderhouden voor de geplande taak. De standaardwaarde is 32.

Windows PowerShell slaat de uitvoeringsgeschiedenis en de resultaten van elke geactiveerde instantie van de geplande taak op schijf op. De waarde van deze parameter bepaalt het aantal resultaten van het taakexemplaren dat is opgeslagen voor deze geplande taak. Wanneer het aantal resultaten van het taakexemplaren deze waarde overschrijdt, verwijdert Windows PowerShell de resultaten van het oudste taakexemplaren om ruimte te maken voor de resultaten van het nieuwste taakexemplaren.

De uitvoeringsgeschiedenis van de taak en taakresultaten worden opgeslagen in de $home\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs\<JobName>\Output\<Timestamp> mappen op de computer waarop de taak wordt gemaakt. Gebruik de Get-Job cmdlet om de uitvoeringsgeschiedenis te bekijken. Gebruik de Receive-Job cmdlet om de taakresultaten op te halen.

Met de parameter MaxResultCount wordt de waarde van de eigenschap ExecutionHistoryLength van de geplande taak ingesteld.

Als u de huidige uitvoeringsgeschiedenis en taakresultaten wilt verwijderen, gebruikt u de parameter ClearExecutionHistory van de Set-ScheduledJob cmdlet.

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

Hiermee geeft u een naam voor de geplande taak. De naam wordt ook gebruikt voor alle gestarte exemplaren van de geplande taak. De naam moet uniek zijn op de computer. Deze parameter is vereist.

Type:String
Position:0
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-RunAs32

Hiermee wordt de geplande taak uitgevoerd in een 32-bits proces.

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

Wordt gebruikt om op te geven hoe vaak de taak moet worden uitgevoerd. Gebruik deze optie bijvoorbeeld om elke 15 minuten een taak uit te voeren.

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

Hiermee start u onmiddellijk een taak zodra de Register-ScheduledJob cmdlet wordt uitgevoerd. Deze parameter elimineert de noodzaak om Task Scheduler te activeren om direct na de registratie een Windows PowerShell script uit te voeren en vereist niet dat gebruikers een trigger maken die een begindatum en -tijd aangeeft.

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

Hiermee stelt u opties voor de geplande taak in. Voer een ScheduledJobOptions-object in, zoals een object dat u maakt met behulp van de New-ScheduledJobOption cmdlet of een hash-tabelwaarde.

U kunt opties instellen voor een geplande taak wanneer u de planningstaak registreert of de Set-ScheduledJobOption cmdlets Set-ScheduledJob gebruikt om de opties te wijzigen.

Veel van de opties en de standaardwaarden bepalen of en wanneer een geplande taak wordt uitgevoerd. Controleer deze opties voordat u een taak plant. Zie voor een beschrijving van de geplande taakopties, inclusief de standaardwaarden.New-ScheduledJobOption

Gebruik de volgende sleutels om een hash-tabel te verzenden. In de volgende hashtabel worden de sleutels weergegeven met hun standaardwaarden.

@{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:Microsoft.PowerShell.ScheduledJob.ScheduledJobOptions
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-ScriptBlock

Hiermee geeft u de opdrachten op die door de geplande taak worden uitgevoerd. Plaats de opdrachten tussen accolades ({}) om een scriptblok te maken. Als u standaardwaarden voor opdrachtparameters wilt opgeven, gebruikt u de parameter ArgumentList .

Elke Register-ScheduledJob opdracht moet de scriptblock - of FilePath-parameters gebruiken.

Type:ScriptBlock
Position:1
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-Trigger

Hiermee geeft u de triggers voor de geplande taak. Voer een of meer ScheduledJobTrigger-objecten in, zoals de objecten die door de New-JobTrigger cmdlet worden geretourneerd, of een hash-tabel met taaktriggersleutels en -waarden.

Een taaktrigger start de planningstaak. De trigger kan een eenmalige of terugkerende geplande gebeurtenis of een gebeurtenis opgeven, bijvoorbeeld wanneer een gebruiker zich aanmeldt of Windows wordt gestart.

De parameter Trigger is optioneel. U kunt een trigger toevoegen wanneer u de geplande taak maakt, de Add-JobTrigger, Set-JobTriggerof Set-ScheduledJob cmdlets gebruikt om later taaktriggers toe te voegen of te wijzigen, of de Start-Job cmdlet gebruiken om de geplande taak onmiddellijk te starten. U kunt ook een geplande taak maken en onderhouden zonder een trigger die als sjabloon wordt gebruikt.

Gebruik de volgende sleutels om een hash-tabel te verzenden:

  • Frequentie: Dagelijks, Wekelijks, AtStartup, AtLogon
  • Op: Elke geldige tijdtekenreeks
  • DaysOfWeek - Elke combinatie van dagnamen
  • Interval : een geldig frequentie-interval
  • RandomDelay: Elke geldige tijdspannetekenreeks
  • Gebruiker: Elke geldige gebruiker. Alleen gebruikt met de atLogon-frequentiewaarde

Bijvoorbeeld:

@{Frequency="Once"; At="3am"; DaysOfWeek="Monday", "Wednesday"; Interval=2; RandomDelay="30minutes"; User="Domain1\User01"}

Type:Microsoft.PowerShell.ScheduledJob.ScheduledJobTrigger[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-Verificatie

Hiermee geeft u het mechanisme op dat wordt gebruikt om de referenties van de gebruiker te verifiëren. De standaardwaarde is Standaard.

De aanvaardbare waarden voor deze parameter zijn:

  • Default
  • Basic
  • Credssp
  • Digest
  • Kerberos
  • Negotiate
  • NegotiateWithImplicitCredential

Zie AuthenticationMechanism voor meer informatie over de waarden van deze parameter.

Waarschuwing

CredSSP-verificatie (Credential Security Service Provider), waarin de referenties van de gebruiker worden doorgegeven aan een externe computer om te worden geverifieerd, is ontworpen voor opdrachten waarvoor verificatie is vereist voor meer dan één resource, zoals toegang tot een externe netwerkshare. Dit mechanisme verhoogt het beveiligingsrisico van de externe bewerking. Als de externe computer is aangetast, kunnen de referenties die eraan worden doorgegeven, worden gebruikt om de netwerksessie te beheren.

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

Hiermee wordt weergegeven wat er zou gebeuren als u de cmdlet uitvoert. De cmdlet wordt niet uitgevoerd.

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

Invoerwaarden

Geen

U kunt geen invoer naar de pijplijn verzenden naar deze cmdlet.

Uitvoerwaarden

Microsoft.PowerShell.ScheduledJob.ScheduledJobDefinition

Notities

Elke geplande taak wordt opgeslagen in een submap van de $home\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs map op de lokale computer. De submap heeft de naam van de geplande taak en bevat een XML-bestand voor de geplande taak en records van de uitvoeringsgeschiedenis. Zie about_Scheduled_Jobs_Advanced voor meer informatie over geplande taken op schijf.

Geplande taken die u in Windows PowerShell maakt, worden weergegeven in Task Scheduler in de map Task SchedulerLibrary\Microsoft\Windows\PowerShell\ScheduledJobs. U kunt Task Scheduler gebruiken om de geplande taak weer te geven en te bewerken.

U kunt Task Scheduler, het schtasks.exe opdrachtregelprogramma en de Task Scheduler-cmdlets gebruiken om geplande taken te beheren die u maakt met de cmdlets Geplande taak. U kunt echter niet de cmdlets Geplande taak gebruiken om taken te beheren die u in Task Scheduler maakt.

Als een geplande taakopdracht mislukt, retourneert Windows PowerShell een foutbericht. Als de taak echter mislukt wanneer Task Scheduler deze probeert uit te voeren, is de fout niet beschikbaar voor Windows PowerShell.

Als een geplande taak niet wordt uitgevoerd, gebruikt u de volgende methoden om de reden te vinden:

  • Controleer of de taaktrigger juist is ingesteld.
    • Controleer of aan de voorwaarden in de taakopties is voldaan.
  • Controleer of het gebruikersaccount waaronder de taak wordt uitgevoerd, gemachtigd is om de opdrachten of scripts in de taak uit te voeren.
  • Controleer de taakplannergeschiedenis op fouten.
  • Controleer het gebeurtenislogboek van Task Scheduler op fouten.

Zie about_Scheduled_Jobs_Troubleshooting voor meer informatie.