Register-EngineEvent
Sottoscrive gli eventi generati dal motore di Windows PowerShell e dal cmdlet New-Event.
Sintassi
Register-EngineEvent
[-SourceIdentifier] <String>
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>] Descrizione
Il cmdlet Register-EngineEvent sottoscrive eventi generati dal motore di Windows PowerShell e dal cmdlet New-Event. Usare il parametro SourceIdentifier per specificare l'evento.
È possibile usare questo cmdlet per sottoscrivere l'evento e gli eventi del motore di uscita generati dal cmdlet New-Event. Questi eventi vengono aggiunti automaticamente alla coda degli eventi nella sessione senza effettuare la sottoscrizione. Tuttavia, la sottoscrizione consente di inoltrare gli eventi, specificare un'azione per rispondere agli eventi e annullare la sottoscrizione.
Quando viene generato l'evento sottoscritto, viene aggiunto alla coda degli eventi nella sessione locale. Per ottenere gli eventi nella coda degli eventi, usare il cmdlet Get-Event.
Quando si sottoscrive un evento viene aggiunto un sottoscrittore di eventi alla sessione. Per ottenere i sottoscrittori di eventi nella sessione, usare il cmdlet Get-EventSubscriber. Per annullare la sottoscrizione, usare il cmdlet Unregister-Event, che elimina il sottoscrittore di eventi dalla sessione.
Esempio
Esempio 1: Registrare un evento del motore di PowerShell nei computer remoti
PS C:\> $S = New-PSSession -ComputerName "Server01, Server02"
PS C:\> Invoke-Command -Session $S { Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward }Questo comando esegue la registrazione a un evento del motore di Windows PowerShell in due computer remoti.
Il primo comando crea una sessione gestita dall'utente (PSSession) in ognuno dei computer remoti.
Il secondo comando usa il cmdlet Invoke-Command per eseguire il comando Register-EngineEvent nelle sessioni remote.
Il comando Register-EngineEvent usa il parametro SourceIdentifier per identificare l'evento. Usa il parametro Forward per inoltrare gli eventi dalla sessione remota a quella locale.
Esempio 2: Eseguire un'azione specificata quando si verifica l'evento Exiting
PS C:\> Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
Get-History | Export-Clixml $Home\history.clixml
}Questo comando illustra come eseguire Register-EngineEvent per eseguire un'azione specifica quando si verifica l'evento PowerShell.Exiting . Il parametro SupportEvent viene aggiunto per nascondere la sottoscrizione dell'evento. Quando Windows PowerShell termina, in questo caso, la cronologia dei comandi della sessione di uscita viene esportata in formato XML in un nome file e un percorso nella directory $Home dell'utente.
Parametri
-Action
Specifica i comandi per gestire gli eventi. Quando viene generato un evento, vengono eseguiti i comandi in Action anziché inviare l'evento alla coda degli eventi. Racchiudere i comandi tra parentesi graffe ({}) per creare un blocco di script.
Il valore del parametro Action può includere le variabili automatiche $Event, $EventSubscriber, $Sender, $EventArgs e $Args che forniscono informazioni sull'evento al blocco di script Action. Per altre informazioni, vedere about_Automatic_Variables (https://go.microsoft.com/fwlink/?LinkID=113212).
Quando si specifica un'azione, Register-EngineEvent restituisce un oggetto processo di 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 trigger.
Il valore del parametro Action può includere le variabili automatiche $Event, $EventSubscriber, $Sender, $EventArgs e $Args che forniscono informazioni sull'evento al blocco di script Action. Per altre informazioni, vedere about_Automatic_Variables (https://go.microsoft.com/fwlink/?LinkID=113212).
Quando si specifica un'azione, Register-EngineEvent restituisce un oggetto processo di evento che rappresenta tale azione. È possibile usare i cmdlet Job per gestire il processo dell'evento.
| 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 alla sottoscrizione.
I valori EngineEvent supportati includono PowerShell.Exiting, PowerShell.OnIdle e PowerShell.OnScriptBlockInvoke.
| 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 dell'evento. 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 cmdlet di Get-EventSubscriber 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 l'input tramite pipe a Register-EngineEvent.
Output
None or System.Management.Automation.PSEventJob
Se si usa il parametro Action, Register-EngineEvent restituisce un oggetto System.Management.Automation.PSEventJob. In caso contrario, non genera alcun output.
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.