Share via

Register-ScheduledJob

  • Référence
Module:
PSScheduledJob

Crée un travail planifié.

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

L’applet Register-ScheduledJob de commande crée des travaux planifiés sur l’ordinateur local.

Un travail planifié est un travail en arrière-plan Windows PowerShell qui peut être démarré automatiquement selon une planification ponctuelle ou périodique. Les travaux planifiés sont stockés sur le disque et inscrits dans le Planificateur de tâches. Les travaux peuvent être gérés dans le Planificateur de tâches ou à l’aide des applets de commande de travail planifiées dans Windows PowerShell.

Lorsqu’un travail planifié démarre, il crée une instance du travail planifié. Les instances de tâche planifiée sont identiques aux tâches en arrière-plan Windows PowerShell, sauf que les résultats sont enregistrés sur le disque. Utilisez les applets de commande Job, telles que Start-Job, Get-Jobet Receive-Job pour démarrer, afficher et obtenir les résultats des instances de travail.

Permet Register-ScheduledJob de créer un travail planifié. Pour spécifier les commandes exécutées par le travail planifié, utilisez le paramètre ScriptBlock . Pour spécifier un script exécuté par le travail, utilisez le paramètre FilePath .

Les travaux planifiés Windows PowerShell utilisent les mêmes déclencheurs de travail et les mêmes options de travail que le planificateur de tâches utilise pour les tâches planifiées.

Paramètre Déclencheur d’ajout d’un ou de plusieurs déclencheurs de Register-ScheduledJob travail qui démarrent le travail. Le paramètre Déclencheur est facultatif. Vous pouvez donc ajouter des déclencheurs lorsque vous créez le travail planifié, ajouter des déclencheurs de travail ultérieurement, ajouter le paramètre RunNow pour démarrer le travail immédiatement, utiliser l’applet Start-Job de commande pour démarrer le travail immédiatement à tout moment ou enregistrer le travail planifié sans détrigueur comme modèle pour d’autres travaux.

Le paramètre Options vous permet de personnaliser les paramètres d’options du travail planifié. Le paramètre Options est facultatif. Vous pouvez donc définir des options de travail lorsque vous créez le travail planifié ou modifiez-les à tout moment. Comme les paramètres d'options de tâche peuvent empêcher l'exécution de la tâche planifiée, passez en revue les options de tâche et définissez-les avec soin.

Register-ScheduledJob est l’une des collections d’applets de commande de planification de travaux dans le module PSScheduledJob inclus dans Windows PowerShell.

Pour plus d’informations sur les travaux planifiés, consultez les articles À propos du module PSScheduledJob . Importez le module PSScheduledJob , puis tapez : Get-Help about_Scheduled* ou consultez about_Scheduled_Jobs.

Cette applet de commande a été introduite dans Windows PowerShell 3.0.

Exemples

Exemple 1 : Créer un travail planifié

Cet exemple crée un travail planifié sur l’ordinateur local.

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

Register-ScheduledJob utilise le paramètre Name pour créer le Archive-Scripts travail planifié. Le paramètre ScriptBlock s’exécute Get-ChildItem qui recherche les fichiers de manière .ps1 récursive dans le $HOME répertoire. L’applet Copy-Item de commande copie les fichiers dans un répertoire spécifié par le paramètre de destination .

Étant donné que le travail planifié ne contient pas de déclencheur, il n’est pas démarré automatiquement. Vous pouvez ajouter des déclencheurs de travail avec Add-JobTrigger, utiliser l’applet Start-Job de commande pour démarrer le travail à la demande ou utiliser le travail planifié comme modèle pour d’autres travaux planifiés.

Exemple 2 : Créer un travail planifié avec des déclencheurs et des options personnalisées

Cet exemple montre comment créer une tâche planifiée qui a un déclencheur de tâche et des options de tâche personnalisées.

$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

La $O variable stocke l’objet d’option de travail créé par l’applet New-ScheduledJobOption de commande. Les options démarrent le travail planifié même si l’ordinateur n’est pas inactif, réveille l’ordinateur pour exécuter le travail, le cas échéant, et permet à plusieurs instances du travail d’exécuter dans une série.

La $T variable stocke le résultat de l’applet New-JobTrigger de commande pour créer un déclencheur de travail qui démarre un travail tous les autres lundis à 19h00.

La $path variable stocke le chemin d’accès au UpdateVersion.ps1 fichier de script.

Register-ScheduledJob utilise le paramètre Name pour créer le travail planifié UpdateVersion . Le paramètre FilePath utilise $path pour spécifier le script exécuté par le travail. Le paramètre ScheduledJobOption utilise les options de travail stockées dans $O. Le paramètre Déclencheur utilise les déclencheurs de travail stockés dans $T.

Exemple 3 : Utiliser des tables de hachage pour spécifier un déclencheur et des options de travail planifiées

Cet exemple a le même effet que la commande dans l’exemple 2. Il crée un travail planifié à l’aide de tables de hachage pour spécifier les valeurs des paramètres Trigger et ScheduledJobOption . Les $O variables définies $Tdans l’exemple 2 sont remplacées par des tables de hachage.

$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"

Exemple 4 : Créer des travaux planifiés sur des ordinateurs distants

Dans cet exemple, le travail planifié EnergyData est créé sur plusieurs ordinateurs distants. Le travail planifié exécute un script qui collecte les données brutes et les enregistre dans un journal en cours d’exécution sur l’ordinateur distant.

$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
}

La $Cred variable stocke les informations d’identification dans un objet PSCredential pour un utilisateur disposant des autorisations nécessaires pour créer des travaux planifiés. La $O variable stocke les options de travail créées avec New-ScheduledJobOption. La $T variable stocke les déclencheurs de travail créés avec New-JobTrigger.

L’applet Invoke-Command de commande utilise le paramètre ComputerName pour obtenir la liste des noms de serveurs à partir du Servers.txt fichier. Le paramètre Credential obtient l’objet d’informations d’identification stocké dans $Cred. Le paramètre ScriptBlock exécute une Register-ScheduledJob commande sur les ordinateurs du Servers.txt fichier.

Les paramètres pour Register-ScheduledJob 2000 sont définis par $params. Les paramètres Name spécifient que le travail est nommé Get-EnergyData sur chaque ordinateur distant. FilePath fournit l’emplacement du EnergyData.ps1 script. Le script se trouve sur un serveur de fichiers disponible pour tous les ordinateurs participants. Le travail s’exécute selon la planification spécifiée par les déclencheurs de travail et $T les options de travail dans $O.

La Register-ScheduledJob @params commande crée le travail planifié avec les paramètres du bloc de script.

Exemple 5 : Créer un travail planifié qui exécute un script sur des ordinateurs distants

Cet exemple crée le travail planifié Collect EnergyData sur l’ordinateur local. Le travail s’exécute sur plusieurs ordinateurs distants.

$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
}

La $Admin variable stocke les informations d’identification d’un utilisateur disposant d’autorisations pour exécuter les commandes dans un objet PSCredential . La $T variable stocke les déclencheurs de travail créés avec New-JobTrigger.

L’applet Register-ScheduledJob de commande utilise le paramètre Name pour créer le travail planifié Collect EnergyData sur l’ordinateur local. Le paramètre Déclencheur spécifie les déclencheurs de travail dans $T et le paramètre MaxResultCount augmente le nombre de résultats enregistrés à 99.

Le paramètre ScriptBlock définit les Invoke-Command paramètres avec $params. Le paramètre AsJob crée l’objet de travail en arrière-plan sur l’ordinateur local, même si le Energydata.ps1 script s’exécute sur les ordinateurs distants. Le paramètre ComputerName obtient la liste des noms de serveurs du Servers.txt fichier. Le paramètre Credential spécifie un compte d’utilisateur autorisé à exécuter des scripts sur les ordinateurs distants. Et, le paramètre d’authentification spécifie une valeur de CredSSP pour autoriser les informations d’identification déléguées.

Exécute Invoke-Command @params la commande avec les paramètres du bloc de script.

Paramètres

-ArgumentList

Spécifie les valeurs des paramètres du script spécifiés par le paramètre FilePath ou pour la commande spécifiée par le paramètre ScriptBlock .

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

-Authentication

Spécifie le mécanisme permettant d'authentifier les informations d'identification de l'utilisateur. La valeur par défaut est Default.

Les valeurs valides pour ce paramètre sont :

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

Pour plus d’informations sur les valeurs de ce paramètre, consultez AuthenticationMechanism.

Attention

L’authentification CredSSP (Credential Security Service Provider), dans laquelle les informations d’identification de l’utilisateur sont transmises à un ordinateur distant à authentifier, est conçue pour les commandes qui nécessitent une authentification sur plusieurs ressources, telles que l’accès à un partage réseau distant. Ce mécanisme augmente le risque de sécurité lié à l'opération distante. Si l'ordinateur distant n'est pas fiable, les informations d'identification qui lui sont passées peuvent être utilisées pour contrôler la session réseau.

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

-Confirm

Vous demande une confirmation avant d’exécuter l’applet de commande.

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

-Credential

Spécifie un compte d'utilisateur qui a l'autorisation d'exécuter la tâche planifiée. La valeur par défaut est l’utilisateur actuel.

Tapez un nom d’utilisateur, tel que User01 ou Domain01\User01, ou entrez un objet PSCredential, tel qu’un de l’applet Get-Credential de commande. Si vous entrez uniquement un nom d’utilisateur, vous êtes invité à entrer un mot de passe.

Les informations d’identification sont stockées dans un objet PSCredential et le mot de passe est stocké en tant que SecureString.

Remarque

Pour plus d’informations sur la protection des données SecureString , consultez Comment secure is SecureString ?.

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

-FilePath

Spécifie un script exécuté par la tâche planifiée. Entrez le chemin d’accès à un .ps1 fichier sur l’ordinateur local. Pour spécifier des valeurs par défaut pour les paramètres de script, utilisez le paramètre ArgumentList . Chaque Register-ScheduledJob commande doit utiliser les paramètres ScriptBlock ou FilePath .

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

-InitializationScript

Spécifie le chemin complet d’un script Windows PowerShell (.ps1). Le script d’initialisation s’exécute dans la session créée pour le travail en arrière-plan avant les commandes spécifiées par le paramètre ScriptBlock ou le script spécifié par le paramètre FilePath . Vous pouvez utiliser le script d'initialisation pour configurer la session, par exemple, pour ajouter des fichiers, des fonctions ou des alias, pour créer des répertoires ou pour vérifier des conditions préalables.

Pour spécifier un script qui exécute les commandes de travail principale, utilisez le paramètre FilePath .

Si le script d’initialisation génère une erreur, même une erreur de non-fin, l’instance actuelle du travail planifié ne s’exécute pas et son état a échoué.

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

-MaxResultCount

Spécifie le nombre d'entrées de résultat de tâche qui sont conservées pour la tâche planifiée. La valeur par défaut est 32.

Windows PowerShell enregistre l'historique d'exécution et les résultats de chaque instance déclenchée de la tâche planifiée sur le disque. La valeur de ce paramètre détermine le nombre de résultats d'instance de tâche qui sont enregistrés pour cette tâche planifiée. Quand le nombre de résultats d'instance de tâche dépasse cette valeur, Windows PowerShell supprime les résultats de l'instance de tâche la plus ancienne pour libérer de l'espace pour les résultats de la dernière instance de tâche.

L’historique d’exécution du travail et les résultats du travail sont enregistrés dans le $HOME\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs\<JobName>\Output\<Timestamp> répertoires sur l’ordinateur sur lequel le travail est créé. Pour afficher l’historique d’exécution, utilisez l’applet de Get-Job commande. Pour obtenir les résultats du travail, utilisez l’applet Receive-Job de commande.

Le paramètre MaxResultCount définit la valeur de la propriété ExecutionHistoryLength du travail planifié.

Pour supprimer l’historique d’exécution actuel et les résultats du travail, utilisez le paramètre ClearExecutionHistory de l’applet Set-ScheduledJob de commande.

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

-Name

Spécifie un nom pour la tâche planifiée. Le nom est également utilisé pour toutes les instances démarrées de la tâche planifiée. Le nom doit être unique sur l'ordinateur. Ce paramètre est obligatoire.

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

-RunAs32

Exécute la tâche planifiée dans un processus 32 bits.

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

-RunEvery

Permet de spécifier la fréquence à laquelle exécuter le travail. Par exemple, utilisez cette option pour exécuter un travail toutes les 15 minutes.

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

-RunNow

Démarre immédiatement un travail, dès que l’applet Register-ScheduledJob de commande est exécutée. Ce paramètre élimine la nécessité de déclencher le planificateur de tâches pour exécuter un script Windows PowerShell immédiatement après l’inscription et n’exige pas que les utilisateurs créent un déclencheur qui spécifie une date et une heure de début.

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

-ScheduledJobOption

Définit les options de la tâche planifiée. Entrez un objet ScheduledJobOptions , tel qu’un objet que vous créez à l’aide de l’applet New-ScheduledJobOption de commande ou une valeur de table de hachage.

Vous pouvez définir des options pour un travail planifié lorsque vous inscrivez le travail de planification ou utilisez les applets de commande ou Set-ScheduledJob les Set-ScheduledJobOption applets de commande pour modifier les options.

La plupart des options et leurs valeurs par défaut déterminent si et quand une tâche planifiée s'exécute. Veillez à consulter ces options avant de planifier une tâche. Pour obtenir une description des options de travail planifiées, y compris les valeurs par défaut, consultez New-ScheduledJobOption.

Pour envoyer une table de hachage, utilisez les clés suivantes. Dans la table de hachage suivante, les clés sont affichées avec leurs valeurs par défaut.

@{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

Spécifie les commandes exécutées par la tâche planifiée. Placez les commandes dans des accolades ({}) pour créer un bloc de script. Pour spécifier des valeurs par défaut pour les paramètres de commande, utilisez le paramètre ArgumentList .

Chaque Register-ScheduledJob commande doit utiliser les paramètres ScriptBlock ou FilePath .

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

-Trigger

Spécifie les déclencheurs de la tâche planifiée. Entrez un ou plusieurs objets ScheduledJobTrigger , tels que les objets retournés par l’applet New-JobTrigger de commande, ou une table de hachage des clés et des valeurs du déclencheur de travail.

Un déclencheur de travail démarre le travail de planification. Le déclencheur peut spécifier une planification ponctuelle ou périodique, ou un événement, tel que le moment où un utilisateur ouvre une session ou où Windows démarre.

Le paramètre Déclencheur est facultatif. Vous pouvez ajouter un déclencheur lorsque vous créez le travail planifié, utilisez les Add-JobTriggerapplets de commande ou Set-JobTriggerSet-ScheduledJob ajoutez ou modifiez des déclencheurs de travail ultérieurement ou utilisez l’applet Start-Job de commande pour démarrer immédiatement le travail planifié. Vous pouvez également créer et gérer une tâche planifiée sans un déclencheur qui est utilisée comme modèle.

Pour envoyer une table de hachage, utilisez les clés suivantes :

  • Fréquence : Quotidien, Hebdomadaire, AtStartup, AtLogon
  • À : n’importe quelle chaîne de temps valide
  • DaysOfWeek - Toute combinaison de noms de jour
  • Intervalle - Tout intervalle de fréquence valide
  • RandomDelay : toute chaîne d’intervalle de temps valide
  • Utilisateur : tout utilisateur valide. Utilisé uniquement avec la valeur de fréquence AtLogon

Par exemple :

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

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

-WhatIf

Montre ce qui se passe en cas d’exécution de l’applet de commande. L’applet de commande n’est pas exécutée.

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

Entrées

None

Vous ne pouvez pas diriger les objets vers cette applet de commande.

Sorties

ScheduledJobDefinition

Cette applet de commande retourne un objet ScheduledJobDefinition représentant le travail inscrit.

Notes

Chaque travail planifié est enregistré dans un sous-répertoire du $HOME\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs répertoire sur l’ordinateur local. Le sous-répertoire est nommé pour la tâche planifiée et contient un fichier XML pour cette tâche et les enregistrements de son historique d'exécution. Pour plus d’informations sur les travaux planifiés sur le disque, consultez about_Scheduled_Jobs_Advanced.

Les travaux planifiés que vous créez dans Windows PowerShell s’affichent dans le Planificateur de tâches dans le dossier Planificateur de Library\Microsoft\Windows\PowerShell\ScheduledJobs tâches. Vous pouvez utiliser le Planificateur de tâches pour afficher et modifier la tâche planifiée.

Vous pouvez utiliser le planificateur de tâches, l’outil schtasks.exe en ligne de commande et les applets de commande du planificateur de tâches pour gérer les travaux planifiés que vous créez avec les applets de commande De travail planifiées. Toutefois, vous ne pouvez pas utiliser les applets de commande de travail planifiées pour gérer les tâches que vous créez dans le Planificateur de tâches.

En cas d'échec d'une commande de la tâche planifiée, Windows PowerShell retourne un message d'erreur. Toutefois, si le travail échoue lorsque le Planificateur de tâches tente de l’exécuter, l’erreur n’est pas disponible pour Windows PowerShell.

Si un travail planifié n’est pas exécuté, utilisez les méthodes suivantes pour trouver la raison :

  • Vérifiez que le déclencheur de travail est correctement défini.
    • Vérifiez que les conditions définies dans les options de travail sont satisfaites.
  • Vérifiez que le compte d’utilisateur sous lequel le travail s’exécute est autorisé à exécuter les commandes ou les scripts du travail.
  • Vérifiez l’historique du planificateur de tâches pour connaître les erreurs.
  • Recherchez les erreurs dans le journal des événements du Planificateur de tâches.

Pour plus d’informations, consultez about_Scheduled_Jobs_Troubleshooting.