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 Register-ScheduledJob cmdlet crea processi pianificati nel computer locale.

Un processo pianificato è un processo in background di Windows PowerShell che può essere avviato automaticamente in base a una pianificazione occasionale o ricorrente. I processi pianificati vengono archiviati su disco e registrati nell'Utilità di pianificazione. I processi possono essere gestiti nell'Utilità di pianificazione o usando i cmdlet processi pianificati in Windows PowerShell.

All'avvio di un processo pianificato, viene creata 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 job, ad esempio Start-Job, Get-Jobe 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 .

I processi pianificati di Windows PowerShell usano gli stessi trigger di 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 trigger di processo in un secondo momento, aggiungere il parametro RunNow per avviare immediatamente il processo, usare il cmdlet per avviare il Start-Job processo immediatamente in qualsiasi momento o salvare il processo pianificato non elaborato come modello per altri processi.

Il parametro Options consente di personalizzare le impostazioni delle opzioni per il processo pianificato. Il parametro Options è facoltativo, quindi è possibile impostare le opzioni di processo quando si crea il processo pianificato o li si modifica 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 raccolta di cmdlet di pianificazione dei processi nel modulo PSScheduledJob incluso in Windows PowerShell.

Per altre informazioni sui processi pianificati, vedere gli articoli Informazioni sul 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: Creare un processo pianificato

In questo esempio viene creato un processo pianificato nel computer locale.

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

Register-ScheduledJob usa il parametro Name per creare il Archive-Scripts processo pianificato. Il parametro ScriptBlock viene eseguito Get-ChildItem che cerca $HOME i file nella directory in modo .ps1 ricorsivo. Il Copy-Item cmdlet copia i file in una directory specificata dal parametro Destination .

Poiché il processo pianificato non contiene un trigger, non viene avviato automaticamente. È possibile aggiungere trigger di processo con Add-JobTrigger, usare il Start-Job cmdlet per avviare il processo su richiesta oppure usare il processo pianificato come modello per altri processi pianificati.

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

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

$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 variabile archivia l'oggetto opzione processo creato dal New-ScheduledJobOption cmdlet . Le opzioni avviano il processo pianificato anche se il computer non è inattiva, riattiva il computer per eseguire il processo, se necessario e consente l'esecuzione di più istanze del processo in una serie.

La $T variabile archivia il risultato del New-JobTrigger cmdlet per creare un trigger di processo che avvia un processo ogni lunedì alle 19:00.

La $path variabile archivia il percorso del UpdateVersion.ps1 file di script.

Register-ScheduledJob usa il parametro Name per creare il processo pianificato UpdateVersion . Il parametro FilePath usa $path per specificare lo script eseguito dal processo. Il parametro ScheduledJobOption usa le opzioni di processo archiviate in $O. Il parametro Trigger usa i trigger di processo archiviati in $T.

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

Questo esempio ha lo stesso effetto del comando nell'esempio 2. Crea un processo pianificato, usando tabelle hash per specificare i valori dei parametri Trigger e ScheduledJobOption . Le variabili e $Tdefinite nell'esempio $O 2 vengono sostituite con le tabelle hash.

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

Esempio 4: Creare processi pianificati nei computer remoti

In questo esempio viene creato il processo pianificato EnergyData in più computer remoti. Il processo pianificato esegue uno script che raccoglie i dati non elaborati e lo salva in un log in esecuzione nel computer remoto.

$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 variabile archivia le credenziali in un oggetto PSCredential per un utente con autorizzazioni per creare processi pianificati. La $O variabile archivia le opzioni di processo create con New-ScheduledJobOption. La $T variabile archivia i trigger di processo creati con New-JobTrigger.

Il Invoke-Command cmdlet usa il parametro ComputerName per ottenere un elenco di nomi di server dal Servers.txt file. Il parametro Credential ottiene l'oggetto credenziale archiviato in $Cred. Il parametro ScriptBlock esegue un Register-ScheduledJob comando nei computer nel Servers.txt file.

I parametri per Register-ScheduledJob sono definiti da $params. I parametri Name specificano che il processo viene denominato Get-EnergyData in ogni computer remoto. FilePath fornisce il percorso dello EnergyData.ps1 script. Lo script si trova in un file server disponibile per tutti i computer partecipanti. Il processo viene eseguito sulla pianificazione specificata dai trigger del processo in $T e le opzioni del processo in $O.

Il Register-ScheduledJob @params comando crea il processo pianificato con i parametri del blocco di script.

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

In questo esempio viene creato il processo pianificato Collect AggregateData nel computer locale. Il processo viene eseguito in più computer remoti.

$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 variabile archivia le credenziali per un utente con autorizzazioni per eseguire i comandi in un oggetto PSCredential . La $T variabile archivia i trigger di processo creati con New-JobTrigger.

Il Register-ScheduledJob cmdlet usa il parametro Name per creare il processo pianificato Collect AggregateData nel computer locale. Il parametro Trigger specifica i trigger di processo in $T e il parametro MaxResultCount aumenta il numero di risultati salvati a 99.

Il parametro ScriptBlock definisce i Invoke-Command parametri con $params. Il parametro AsJob crea l'oggetto processo in background nel computer locale, anche se lo Energydata.ps1 script viene eseguito nei computer remoti. Il parametro ComputerName ottiene un elenco di nomi di server dal Servers.txt file. Il parametro Credential consente di specificare un account utente autorizzato a eseguire script nei computer remoti. Il parametro Authentication specifica inoltre un valore credSSP per consentire le credenziali delegate.

Invoke-Command @params Esegue il comando con i parametri del blocco di script.

Parametri

-ArgumentList

Specifica i valori per i parametri dello script specificati 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. Il valore predefinito è Default.

I valori validi per questo parametro sono:

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

Per altre informazioni sui valori di questo parametro, vedere AuthenticationMechanism.

Attenzione

L'autenticazione credSSP (Credential Security Service Provider), 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:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Confirm

Richiede conferma 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 del Get-Credential cmdlet. Se si immette solo un nome utente, viene richiesta una password.

Le credenziali vengono archiviate in un oggetto PSCredential e la password viene archiviata come SecureString.

Nota

Per altre informazioni sulla protezione dei dati SecureString , vedere How secure is SecureString?.

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

-FilePath

Specifica uno script eseguito dal processo pianificato. Immettere il percorso di un .ps1 file nel computer locale. Per specificare i valori predefiniti per i parametri dello script, usare il parametro ArgumentList . Ogni Register-ScheduledJob comando deve usare i parametri 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 dei comandi specificati dal parametro ScriptBlock o dallo script specificato 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 in $HOME\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs\<JobName>\Output\<Timestamp> directory nel computer in cui viene creato il processo. Per visualizzare la cronologia di esecuzione, usare il Get-Job cmdlet . Per ottenere i risultati del processo, usare il Receive-Job cmdlet .

Il parametro MaxResultCount imposta il valore della proprietà ExecutionHistoryLength del processo pianificato.

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

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:None
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 Register-ScheduledJob cmdlet. Questo parametro elimina la necessità di attivare l'Utilità di pianificazione per eseguire uno script di Windows PowerShell immediatamente dopo la registrazione e non richiede agli utenti di creare un trigger che specifica una data e un'ora di inizio.

Type:SwitchParameter
Position:Named
Default value:None
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 New-ScheduledJobOption cmdlet 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 Set-ScheduledJobOption cmdlet 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 Register-ScheduledJob comando deve usare i parametri 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 New-JobTrigger cmdlet o una tabella hash di chiavi e valori del trigger di 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 Add-JobTriggercmdlet , Set-JobTriggero Set-ScheduledJob per aggiungere o modificare i trigger di processo in un secondo momento oppure usare il Start-Job cmdlet 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:

  • Frequenza: Giornaliero, Settimanale, AtStartup, AtLogon
  • At: Qualsiasi stringa di ora valida
  • DaysOfWeek - Qualsiasi combinazione di nomi dei giorni
  • Interval - Qualsiasi intervallo di frequenza valido
  • RandomDelay: qualsiasi stringa timepan valida
  • Utente: qualsiasi utente valido. Usato solo con il valore della frequenza AtLogon

Ad esempio:

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

Mostra gli effetti dell'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 tramite pipe oggetti a questo cmdlet.

Output

ScheduledJobDefinition

Questo cmdlet restituisce un oggetto ScheduledJobDefinition che rappresenta il processo registrato.

Note

Ogni processo pianificato viene salvato in una sottodirectory della $HOME\AppData\Local\Microsoft\Windows\PowerShell\ScheduledJobs directory nel computer locale. La sottodirectory per il processo pianificato viene denominata 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 nell'Utilità di pianificazione nella cartella Utilità di pianificazione Library\Microsoft\Windows\PowerShell\ScheduledJobs . È possibile usare Utilità di pianificazione per visualizzare e modificare il processo pianificato.

È possibile usare Utilità di pianificazione, lo schtasks.exe strumento da riga di comando e i cmdlet dell'Utilità di pianificazione per gestire i processi pianificati creati con i cmdlet Processi pianificati. Tuttavia, non è possibile usare i cmdlet processi pianificati per gestire le attività create nell'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 quando l'Utilità di pianificazione tenta di eseguirla, l'errore non è disponibile per 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 con 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 verificare la presenza di errori.
  • Controllare la presenza di errori nel registro eventi dell'Utilità di pianificazione.

Per altre informazioni, vedere about_Scheduled_Jobs_Troubleshooting.