Condividi tramite

Register-ScheduledJob

  • Riferimento
Modulo:
PSScheduledJob

Crea un processo pianificato.

Sintassi

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

Descrizione

Il cmdlet Register-ScheduledJob crea processi pianificati nel computer locale.

Un processo pianificato è un processo in background Windows PowerShell che può essere avviato automaticamente in una pianificazione singola o ricorrente. I processi pianificati vengono archiviati su disco e registrati in Utilità di pianificazione, quindi possono essere gestiti da Utilità di pianificazione o tramite i cmdlet Processi pianificati in Windows PowerShell.

Quando viene avviato un processo pianificato, crea un'istanza del processo pianificato. Le istanze del processo pianificato sono identiche ai processi in background di Windows PowerShell, ad eccezione del fatto che i risultati vengono salvati su disco. Usare i cmdlet Processo, ad esempio Start-Job, Get-Job e Receive-Job per avviare, visualizzare e ottenere i risultati delle istanze del processo.

Usare Register-ScheduledJob per creare un nuovo processo pianificato. Per specificare i comandi eseguiti dal processo pianificato, usare il parametro ScriptBlock; per specificare uno script eseguito dal processo, usare il parametro FilePath.

Windows PowerShell processi pianificati usano gli stessi trigger del processo e le stesse opzioni di processo usate dall'utilità di pianificazione per le attività pianificate.

Il parametro Trigger di Register-ScheduledJob aggiunge uno o più trigger di processo che avviano il processo. Il parametro Trigger è facoltativo, quindi è possibile aggiungere trigger quando si crea il processo pianificato, aggiungere i trigger di processo in un secondo momento, aggiungere il parametro RunNow per avviare immediatamente il processo, usare il cmdlet Start-Job per avviare immediatamente il processo o salvare il processo pianificato non eseguito come modello per altri processi.

Il parametro Options consente di personalizzare le impostazioni delle opzioni per il processo pianificato. Anche il parametro Options è facoltativo, quindi è possibile impostare le opzioni di processo quando si crea il processo pianificato o modificarle in qualsiasi momento. Poiché le impostazioni delle opzioni per il processo possono impedire l'esecuzione del processo pianificato, controllare le opzioni di processo e impostarle attentamente.

Register-ScheduledJob è una delle raccolte di cmdlet di pianificazione dei processi nel modulo PSScheduledJob incluso in Windows PowerShell.

Per altre informazioni sui lavori pianificati, vedere gli argomenti Informazioni nel modulo PSScheduledJob. Importare il modulo PSScheduledJob e quindi digitare: Get-Help about_Scheduled* o vedere about_Scheduled_Jobs.

Questo cmdlet è stato introdotto in Windows PowerShell 3.0.

Esempio

Esempio 1: Create un processo pianificato

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

Questo comando crea un processo pianificato Archive-Scripts. Il valore di parametro ScriptBlock contiene un comando che cerca in modo ricorsivo i file con estensione ps1 nella directory $home e li copia in una directory di una condivisione file.

Poiché il processo pianificato non contiene un trigger, non viene avviato automaticamente. È possibile usare i trigger di processo aggiuntivi in un secondo momento, usare il cmdlet Start-Job per avviare il processo su richiesta o usare il processo pianificato come modello per altri processi pianificati.

Esempio 2: Create un processo pianificato con trigger e opzioni personalizzate

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

Questo esempio mostra come creare un processo pianificato con un trigger di processo e opzioni di processo personalizzate.

Esempio 3: Usare tabelle hash per specificare un trigger e opzioni di processo

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

Questo comando ha lo stesso effetto del comando descritto nell'esempio 2. Crea un processo pianificato, ma usa le tabelle hash per specificare i valori dei parametri Trigger e ScheduledJobOption.

Esempio 4: Create processi pianificati nei computer remoti

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

Questo comando crea il processo pianificato EnergyData in più computer remoti. Il processo pianificato esegue uno script che raccoglie i dati non elaborati e li salva in un log in esecuzione. I processi pianificati vengono creati ed eseguiti nel computer remoto, dove archiviano anche i risultati.

Il comando usa il cmdlet Invoke-Command per eseguire un comando Register-ScheduledJob nei computer nel file Servers.txt. Il comando Invoke-Command usa il parametro Credential per fornire le credenziali di un utente che dispone dell'autorizzazione per creare processi pianificati nei computer nel file Servers.txt.

Il comando Register-ScheduledJob crea un processo pianificato nel computer remoto che esegue lo script di EnergyData.ps1 specificato dal trigger del processo nella variabile $T. Lo script si trova in un file server disponibile a tutti i computer nell'ambito.

Esempio 5: Create un processo pianificato che esegue uno script nei computer remoti

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 }

Questo comando usa il cmdlet Register-ScheduledJob per creare il processo pianificato CollectEnergyData nel computer locale. Il comando usa il parametro Trigger per specificare la pianificazione del processo e il parametro MaxResultCount per aumentare il numero di risultati salvati a 99.

Il processo Collect EnergyData usa il cmdlet Invoke-Command per eseguire lo script di EnergyData.ps1 come sfondo sui computer elencati nel file di Servers.txt. Il comando Invoke-Command usa il parametro AsJob per creare l'oggetto processo in background nel computer locale, anche se lo script Energydata.ps1 viene eseguito nei computer remoti. Il comando usa il parametro Credential per specificare un account utente che dispone dell'autorizzazione per eseguire gli script nei computer remoti e il parametro Authentication con il valore CredSSP per consentire le credenziali delegate.

Parametri

-ArgumentList

Specifica i valori per i parametri dello script specificato dal parametro FilePath o per il comando specificato dal parametro ScriptBlock.

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

-Authentication

Specifica il meccanismo usato per autenticare le credenziali dell'utente. I valori validi per questo parametro sono:

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

Il valore predefinito è Default. Per altre informazioni sui valori di questo parametro, vedere Enumerazione AuthenticationMechanism nella libreria MSDN.

Attenzione: l'autenticazione del provider di servizi di sicurezza delle credenziali (CredSSP) in cui le credenziali dell'utente vengono passate a un computer remoto da autenticare, è progettato per i comandi che richiedono l'autenticazione in più di una risorsa, ad esempio l'accesso a una condivisione di rete remota. Questo meccanismo aumenta il rischio per la sicurezza dell'operazione remota. Se infatti il computer remoto viene compromesso, le credenziali che gli vengono passate possono essere usate per controllare la sessione di rete.

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

Richiede la conferma dell'utente prima di eseguire il cmdlet.

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

-Credential

Specifica un account utente che dispone dell'autorizzazione per eseguire il processo pianificato. Il valore predefinito è l'utente corrente.

Digitare un nome utente, ad esempio User01 o Domain01\User01 oppure immettere un oggetto PSCredential , ad esempio uno dal cmdlet Get-Credential. Se si immette solo un nome utente, viene richiesta una password.

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

-FilePath

Specifica uno script eseguito dal processo pianificato. Immettere il percorso di un file con estensione ps1 nel computer locale. Per specificare i valori predefiniti per i parametri di script usare il parametro ArgumentList. Ogni comando Register-ScheduledJob deve usare il parametro ScriptBlock o FilePath.

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

-InitializationScript

Specifica il percorso completo di uno script di Windows PowerShell (.ps1). Lo script di inizializzazione viene eseguito nella sessione creata per il processo in background prima che vengano specificati i comandi dal parametro ScriptBlock o lo script dal parametro FilePath. È possibile usare lo script di inizializzazione per configurare la sessione, ad esempio aggiungere file, funzioni e alias, creare directory o controllare prerequisiti.

Per specificare uno script che esegue i comandi del processo primario usare il parametro FilePath.

Se lo script di inizializzazione genera un errore (anche un errore non irreversibile), l'istanza corrente del processo pianificato non viene eseguita e il relativo stato è Non riuscito.

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

-MaxResultCount

Specifica quante voci di risultato del processo vengono mantenute per il processo pianificato. Il valore predefinito è (32).

Windows PowerShell salva la cronologia di esecuzione e i risultati di ogni istanza con trigger del processo pianificato su disco. Il valore di questo parametro determina il numero di risultati dell'istanza del processo salvato per il processo pianificato. Quando il numero di risultati dell'istanza del processo supera questo valore, Windows PowerShell elimina i risultati del processo meno recente per liberare spazio per i risultati dell'istanza del processo più recente.

La cronologia di esecuzione del processo e i risultati del processo vengono salvati nelle directory $home\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs\<JobName>\Output\<Timestamp> nel computer in cui viene creato il processo. Per visualizzare la cronologia di esecuzione, usare il cmdlet Get-Job. Per ottenere i risultati del processo, usare il cmdlet Receive-Job.

Il parametro MaxResultCount imposta la proprietà ExecutionHistoryLength del processo pianificato.

Per eliminare la cronologia di esecuzione corrente e i risultati del processo, usare il parametro ClearExecutionHistory del cmdlet Set-ScheduledJob.

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

-Name

Specifica un nome per il processo pianificato. Il nome viene usato anche per tutte le istanze avviate del processo pianificato. Il nome deve essere univoco nel computer. Questo parametro è obbligatorio.

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

-RunAs32

Esegue il processo pianificato in un processo a 32 bit.

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

-RunEvery

Consente di specificare la frequenza con cui eseguire il processo. Ad esempio, usare questa opzione per eseguire un processo ogni 15 minuti.

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

-RunNow

Avvia immediatamente un processo non appena viene eseguito il cmdlet Register-ScheduledJob . Questo parametro evita di dover attivare Utilità di pianificazione per eseguire uno script di Windows PowerShell subito dopo la registrazione e non richiede agli utenti di creare un trigger che specifichi una data e un'ora di inizio.

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

-ScheduledJobOption

Imposta le opzioni per il processo pianificato. Immettere un oggetto ScheduledJobOptions , ad esempio quello creato usando il cmdlet New-ScheduledJobOption o un valore di tabella hash.

È possibile impostare le opzioni per un processo pianificato quando si registra il processo di pianificazione o si usano i cmdlet Set-ScheduledJobOption o Set-ScheduledJob per modificare le opzioni.

Molte opzioni e i relativi valori predefiniti determinano se e quando viene eseguito un processo pianificato. Assicurarsi di esaminare queste opzioni prima di pianificare un processo. Per una descrizione delle opzioni di processo pianificate, inclusi i valori predefiniti, vedere New-ScheduledJobOption.

Per inviare una tabella hash, usare le chiavi seguenti. Nella seguente tabella hash, le chiavi vengono visualizzate con i relativi valori predefiniti.

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

Specifica i comandi eseguiti dal processo pianificato. Racchiudere i comandi tra parentesi graffe ({}) per creare un blocco di script. Per specificare i valori predefiniti per i parametri di comando usare il parametro ArgumentList.

Ogni comando Register-ScheduledJob deve usare il parametro ScriptBlock o FilePath.

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

-Trigger

Specifica i trigger per il processo pianificato. Immettere uno o più oggetti ScheduledJobTrigger , ad esempio gli oggetti restituiti dal cmdlet New-JobTrigger oppure una tabella hash di chiavi e valori del trigger del processo.

Un trigger di processo avvia il processo di pianificazione. Il trigger può specificare una pianificazione occasionale o ricorrente oppure un evento, ad esempio quando un utente accede o quando viene avviato Windows.

Il parametro Trigger è facoltativo. È possibile aggiungere un trigger quando si crea il processo pianificato, usare i cmdlet Add-JobTrigger, Set-JobTrigger o Set-ScheduledJob per aggiungere o modificare i trigger di processo in un secondo momento oppure usare il cmdlet Start-Job per avviare immediatamente il processo pianificato. È anche possibile creare e mantenere un processo pianificato senza un trigger usato come modello.

Per inviare una tabella hash, usare le chiavi seguenti:

@{Frequency="Once" (o giornaliero, settimanale, AtStartup, AtLogon); At="3am" (o qualsiasi stringa temporale valida); DaysOfWeek="Monday", "Wednesday" (o qualsiasi combinazione di nomi dei giorni); Interval=2 (o qualsiasi intervallo di frequenza valido); RandomDelay="30minutes" (o qualsiasi stringa intervallo di tempo valida); User="Domain1\User01" (o qualsiasi utente valido; usato solo con il valore di frequenza AtLogon) }

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

-WhatIf

Mostra l'esito in caso di esecuzione del cmdlet. Il cmdlet non viene eseguito.

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

Input

None

Non è possibile inviare input tramite pipe a questo cmdlet.

Output

ScheduledJobDefinition

Note

  • Ogni processo pianificato viene salvato in una sottodirectory della directory $home\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs nel computer locale. La sottodirectory è denominata per il processo pianificato e contiene un file XML per il processo pianificato e i record della relativa cronologia di esecuzione. Per altre informazioni sui processi pianificati su disco, vedere about_Scheduled_Jobs_Advanced.

  • I processi pianificati creati in Windows PowerShell vengono visualizzati in Utilità di pianificazione nella cartella Libreria Utilità di pianificazione\Microsoft\Windows\PowerShell\ScheduledJobs. È possibile usare Utilità di pianificazione per visualizzare e modificare il processo pianificato.

  • È possibile usare Utilità di pianificazione, lo strumento da riga di comando SchTasks.exe e i cmdlet di Utilità di pianificazione per gestire i processi pianificati creati con i cmdlet Scheduled Job. Non è tuttavia possibile usare i cmdlet Scheduled Job per gestire le attività create in Utilità di pianificazione.

  • Se un comando di un processo pianificato non riesce, Windows PowerShell restituisce un messaggio di errore. Tuttavia, se il processo non riesce durante un tentativo di esecuzione con Utilità di pianificazione, l'errore non è disponibile in Windows PowerShell.

    Se un processo pianificato non viene eseguito, usare i metodi seguenti per trovare il motivo.

  • Verificare che il trigger del processo sia impostato correttamente. -- Verificare che le condizioni impostate nelle opzioni del processo siano soddisfatte.
  • Verificare che l'account utente in cui viene eseguito il processo disponga dell'autorizzazione per eseguire i comandi o gli script nel processo.
  • Controllare la cronologia dell'utilità di pianificazione per gli errori
  • Controllare il registro eventi dell'utilità di pianificazione per gli errori.

Per altre informazioni, vedere about_Scheduled_Jobs_Troubleshooting.