Register-EngineEvent
Sottoscrive gli eventi generati dal motore di PowerShell e dal New-Event
cmdlet .
Sintassi
Register-EngineEvent
[-SourceIdentifier] <String>
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>]
Descrizione
Il Register-EngineEvent
cmdlet sottoscrive gli eventi generati dal motore di PowerShell e dal New-Event
cmdlet . Usare il parametro SourceIdentifier per specificare l'evento.
È possibile usare questo cmdlet per sottoscrivere gli eventi e gli eventi del motore OnIdle o Exiting generati dal New-Event
cmdlet . Questi eventi vengono aggiunti automaticamente alla coda di eventi nella sessione senza eseguire la sottoscrizione. Tuttavia, la sottoscrizione consente di inoltrare gli eventi, specificare un'azione per rispondere agli eventi e annullare la sottoscrizione.
Quando si sottoscrive un evento viene aggiunto un sottoscrittore di eventi alla sessione. Per ottenere i sottoscrittori di eventi nella sessione, usare il Get-EventSubscriber
cmdlet . Per annullare la sottoscrizione, usare il Unregister-Event
cmdlet , che elimina il sottoscrittore di eventi dalla sessione.
Quando viene generato l'evento sottoscritto, viene aggiunto alla coda degli eventi nella sessione locale. Per ottenere eventi nella coda di eventi, usare il Get-Event
cmdlet .
Esempio
Esempio 1: Registrare un evento del motore di PowerShell nei computer remoti
Questo esempio registra per un evento del motore di PowerShell in due computer remoti.
$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S {
Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward
}
New-PSSession
crea una sessione gestita dall'utente (PSSession) in ognuno dei computer remoti. Il Invoke-Command
cmdlet esegue il Register-EngineEvent
comando nelle sessioni remote.
Register-EngineEvent
usa il parametro SourceIdentifier per identificare l'evento. Il parametro Forward indica al motore di inoltrare gli eventi dalla sessione remota alla sessione locale.
Esempio 2: Eseguire un'azione specificata quando si verifica l'evento Exiting
Questo esempio illustra come eseguire Register-EngineEvent
per eseguire un'azione specifica quando si verifica l'evento PowerShell.Exiting .
Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
Get-History | Export-Clixml $HOME\history.clixml
}
Il parametro SupportEvent viene aggiunto per nascondere la sottoscrizione di eventi. Quando PowerShell viene chiuso, in questo caso, la cronologia dei comandi dalla sessione di uscita viene esportata in un file XML nella directory dell'utente $HOME
.
Esempio 3: Creare e sottoscrivere un evento definito dall'utente
In questo esempio viene creata una sottoscrizione per gli eventi dall'origine MyEventSource. Si tratta di un'origine arbitraria che verrà usata per monitorare lo stato di avanzamento di un processo. Register-EngineEvent
viene usato per creare la sottoscrizione. Il blocco di script per il parametro Action registra i dati dell'evento in un file di testo.
Register-EngineEvent -SourceIdentifier MyEventSource -Action {
"Event: {0}" -f $event.messagedata | Out-File c:\temp\MyEvents.txt -Append
}
Start-Job -Name TestJob -ScriptBlock {
While ($True) {
Register-EngineEvent -SourceIdentifier MyEventSource -Forward
Start-Sleep -seconds 2
"Doing some work..."
New-Event -SourceIdentifier MyEventSource -Message ("{0} - Work done..." -f (Get-Date))
}
}
Start-Sleep -seconds 4
Get-EventSubscriber
Get-Job
SubscriptionId : 12
SourceObject :
EventName :
SourceIdentifier : MyEventSource
Action : System.Management.Automation.PSEventJob
HandlerDelegate :
SupportEvent : False
ForwardEvent : False
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
18 MyEventSource Running True …
19 TestJob BackgroundJob Running True localhost …
Register-EngineEvent
id processo creato 18. Start-Job
id processo creato 19. Nell'esempio 4 si rimuovono la sottoscrizione di eventi e i processi, quindi si esamina il file di log.
Esempio 4: Annullare la registrazione degli eventi e pulire i processi
Si tratta di una continuazione dell'esempio 3. In questo esempio si attende che si verifichino 10 secondi. Annullare quindi la registrazione della sottoscrizione di eventi.
PS> Start-Sleep -seconds 10
PS> Get-EventSubscriber | Unregister-Event
PS> Get-Job
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
18 MyEventSource Stopped False …
19 TestJob BackgroundJob Running True localhost …
PS> Stop-Job -Id 19
PS> Get-Job | Remove-Job
PS> Get-Content C:\temp\MyEvents.txt
Event: 2/18/2020 2:36:19 PM - Work done...
Event: 2/18/2020 2:36:21 PM - Work done...
Event: 2/18/2020 2:36:23 PM - Work done...
Event: 2/18/2020 2:36:25 PM - Work done...
Event: 2/18/2020 2:36:27 PM - Work done...
Event: 2/18/2020 2:36:29 PM - Work done...
Event: 2/18/2020 2:36:31 PM - Work done...
Il Unregister-Event
cmdlet arresta il processo associato alla sottoscrizione di eventi (ID processo 18). L'ID processo 19 è ancora in esecuzione e crea nuovi eventi. I cmdlet job arrestano il processo e rimuovono gli oggetti processo non richiesti. Get-Content
visualizza il contenuto del file di log.
Parametri
-Action
Specifica i comandi per gestire gli eventi. I comandi nell'azione vengono eseguiti quando viene generato un evento anziché inviare l'evento alla coda di eventi. Racchiudere i comandi tra parentesi graffe ({}
) per creare un blocco di script.
Il valore del parametro Action può includere le $Event
variabili automatiche , $Sender
$EventArgs
$EventSubscriber
, , e $Args
, che forniscono informazioni sull'evento al blocco script Action. Per altre informazioni, vedere about_Automatic_Variables.
Quando si specifica un'azione, Register-EngineEvent
restituisce un oggetto processo evento che rappresenta tale azione. È possibile usare i cmdlet Job per gestire il processo dell'evento.
Type: | ScriptBlock |
Position: | 101 |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Forward
Indica che il cmdlet invia eventi per questa sottoscrizione alla sessione nel computer locale. Usare questo parametro quando si esegue la registrazione per gli eventi in un computer remoto o in una sessione remota.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaxTriggerCount
Specifica il numero massimo di volte in cui viene eseguita l'azione per la sottoscrizione di eventi.
Type: | Int32 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MessageData
Specifica i dati aggiuntivi associati all'evento. Il valore di questo parametro viene visualizzato nella proprietà MessageData dell'oggetto evento.
Type: | PSObject |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SourceIdentifier
Specifica l'identificatore di origine dell'evento a cui si effettua la sottoscrizione. L'identificatore di origine selezionato deve essere univoco nella sessione corrente. Questo parametro è obbligatorio.
Il valore di questo parametro viene visualizzato nel valore della proprietà SourceIdentifier dell'oggetto sottoscrittore e di tutti gli oggetti evento associati a questa sottoscrizione.
Il valore è specifico dell'origine dell'evento. Può trattarsi di un valore arbitrario creato da usare con il New-Event
cmdlet . Il motore di PowerShell supporta i valori P edizione Standard ngineEvent di PowerShell.Exiting e PowerShell.OnIdle.
Type: | String |
Position: | 100 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SupportEvent
Indica che il cmdlet nasconde la sottoscrizione di eventi. Aggiungere questo parametro quando la sottoscrizione corrente fa parte di un meccanismo di registrazione eventi più complesso e non deve essere individuato in modo indipendente.
Per visualizzare o annullare una sottoscrizione creata con il parametro SupportEvent , aggiungere il parametro Force ai Get-EventSubscriber
cmdlet o Unregister-Event
.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Input
None
Non è possibile inviare tramite pipe oggetti a questo cmdlet.
Output
None
Per impostazione predefinita, questo cmdlet non restituisce alcun output.
Quando si usa il parametro Action, questo cmdlet restituisce un oggetto P edizione Standard ventJob.
Note
Gli eventi, le sottoscrizioni di eventi e la coda degli eventi esistono solo nella sessione corrente. Se si chiude la sessione corrente, la coda degli eventi viene rimossa e la sottoscrizione dell'evento viene annullata.
Quando si sottoscrive l'evento Exiting , i cmdlet che possono essere eseguiti dal parametro Action sono limitati ai cmdlet nei moduli Microsoft.PowerShell.Core e Microsoft.PowerShell.Utility . L'evento Exiting viene generato solo quando la sessione viene chiusa sotto il controllo di PowerShell. L'evento non viene generato quando l'applicazione host o la finestra del terminale viene chiusa.
Il motore viene considerato inattiva se non esegue una pipeline. L'evento OnIdle viene generato quando PowerShell è inattiva per 300 millisecondi (ms).
Nota
Quando PSReadLine è in uso, l'evento OnIdle viene generato quando ReadKey()
si verifica il timeout (nessuna digitazione in 300 ms). L'evento può essere segnalato mentre l'utente sta modificando una riga di comando, ad esempio l'utente sta leggendo la Guida per decidere quale parametro usare. A partire da PSReadLine 2.2.0-beta4, il comportamento OnIdle è stato modificato per segnalare l'evento solo se è presente un ReadKey()
timeout e il buffer di modifica corrente è vuoto.