Register-EngineEvent

  • Riferimento
Modulo:
Microsoft.PowerShell.Utility

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 $Eventvariabili 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.

PSEventJob

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.