Condividi tramite

Register-EngineEvent

Modulo:
Microsoft.PowerShell.Utility Module

Sottoscrive gli eventi generati dal motore di PowerShell e dal cmdlet New-Event.

Sintassi

Default (impostazione predefinita). 

Register-EngineEvent
    [-SourceIdentifier] <String>
    [[-Action] <ScriptBlock>]
    [-MessageData <PSObject>]
    [-SupportEvent]
    [-Forward]
    [-MaxTriggerCount <Int32>]
    [<CommonParameters>]

Descrizione

Il cmdlet Register-EngineEvent sottoscrive gli eventi generati dal motore di PowerShell e dal cmdlet New-Event. Usare il parametro SourceIdentifier per specificare l'evento.

È possibile usare questo cmdlet per sottoscrivere l' OnIdle di o Exiting engine events and events generate dal 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, alla sessione viene aggiunto un sottoscrittore di eventi. Per ottenere gli abbonati agli eventi nella sessione, usare il cmdlet Get-EventSubscriber. Per annullare la sottoscrizione, usare il cmdlet Unregister-Event che elimina il sottoscrittore dell'evento dalla sessione.

Quando viene generato l'evento sottoscritto, viene aggiunto alla coda di eventi nella tua sessione. Per ottenere eventi nella coda di eventi, utilizzare il cmdlet Get-Event.

Esempio

Esempio 1: Registrare un evento del motore di PowerShell sui computer remoti

Questo esempio registra un evento del motore di PowerShell su 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 cmdlet Invoke-Command esegue il comando Register-EngineEvent nelle sessioni remote. 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: Effettuare un'azione specificata quando si verifica l'evento di uscita

In questo esempio viene mostrato come avviare per compiere un'azione specifica quando si verifica l'evento di PowerShell.Exiting.

Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
    Get-History | Export-Clixml $HOME\history.clixml
}

Il parametro SupportEvent viene aggiunto per nascondere l'iscrizione all'evento. Quando PowerShell esce, in questo caso, la cronologia dei comandi dalla sessione di uscita viene esportata in un file XML nella directory $HOME dell'utente.

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 una fonte arbitraria che verrà usata per monitorare il progresso di un lavoro. Register-EngineEvent viene usato per creare la sottoscrizione. Il blocco di script per il parametro dell'azione 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..."
        $newEventSplat = @{
            SourceIdentifier = 'MyEventSource'
            MessageData      = ("{0} -  Work done..." -f (Get-Date))
        }
        New-Event @newEventSplat
    }
}
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 creato Id lavoro 18. Start-Job ha creato ID lavoro 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, attendiamo 10 secondi per lasciare che si verifichino diversi eventi. Quindi annulliamo l'iscrizione all'evento.

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 cmdlet Unregister-Event arresta l'attività associata all'abbonamento agli eventi (ID attività 18). L'ID lavoro 19 è ancora in esecuzione e sta creando nuovi eventi. I cmdlet di job arrestano il processo di lavoro e rimuovono gli oggetti di lavoro non necessari. Get-Content visualizza il contenuto del file di log.

Parametri

-Action

Specifica i comandi per gestire gli eventi. I comandi nell'Azione vengono eseguiti direttamente quando viene generato un evento, al posto di inviare l'evento alla coda di eventi. Racchiudi i comandi tra parentesi graffe ({}) per creare un blocco di script.

Il valore del parametro Action può includere le variabili automatiche $Event, $EventSubscriber, $Sender, $EventArgse $args, che forniscono informazioni sull'evento al blocco di script Action. Per altre informazioni, vedere about_Automatic_Variables.

Quando si specifica un'azione, Register-EngineEvent restituisce un oggetto di processo evento che rappresenta tale azione. È possibile utilizzare i cmdlet Job per gestire il job dell'evento.

Proprietà dei parametri

Tipo:ScriptBlock
Valore predefinito:None
Supporta i caratteri jolly:False
DontShow:False

Set di parametri

(All)
Posizione:101
Obbligatorio:False
Valore dalla pipeline:False
Valore dalla pipeline in base al nome della proprietà:False
Valore dagli argomenti rimanenti:False

-Forward

Indica che il cmdlet trasmette gli eventi di questa sottoscrizione alla sessione sul computer locale. Usare questo parametro quando si esegue la registrazione per gli eventi in un computer remoto o in una sessione remota.

Proprietà dei parametri

Tipo:SwitchParameter
Valore predefinito:None
Supporta i caratteri jolly:False
DontShow:False

Set di parametri

(All)
Posizione:Named
Obbligatorio:False
Valore dalla pipeline:False
Valore dalla pipeline in base al nome della proprietà:False
Valore dagli argomenti rimanenti:False

-MaxTriggerCount

Specifica il numero massimo di volte in cui viene eseguita l'azione per la sottoscrizione di eventi.

Proprietà dei parametri

Tipo:Int32
Valore predefinito:None
Supporta i caratteri jolly:False
DontShow:False

Set di parametri

(All)
Posizione:Named
Obbligatorio:False
Valore dalla pipeline:False
Valore dalla pipeline in base al nome della proprietà:False
Valore dagli argomenti rimanenti:False

-MessageData

Questo parametro fa parte della classe base per tutti i cmdlet Event. Il Register-EngineEvent non usa questo parametro. Tutti i dati passati a questo parametro vengono ignorati.

Proprietà dei parametri

Tipo:PSObject
Valore predefinito:None
Supporta i caratteri jolly:False
DontShow:False

Set di parametri

(All)
Posizione:Named
Obbligatorio:False
Valore dalla pipeline:False
Valore dalla pipeline in base al nome della proprietà:False
Valore dagli argomenti rimanenti:False

-SourceIdentifier

Specifica l'identificatore di origine dell'evento a cui si sta sottoscrivendo. L'identificatore di origine 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 cmdlet New-Event. Il motore di PowerShell supporta i valori PSEngineEvent, PowerShell.Exiting, e PowerShell.OnIdle.

Proprietà dei parametri

Tipo:String
Valore predefinito:None
Supporta i caratteri jolly:False
DontShow:False

Set di parametri

(All)
Posizione:100
Obbligatorio:True
Valore dalla pipeline:False
Valore dalla pipeline in base al nome della proprietà:False
Valore dagli argomenti rimanenti:False

-SupportEvent

Indica che il cmdlet nasconde l'abbonamento agli eventi. Aggiungi questo parametro quando l'abbonamento corrente fa parte di un meccanismo di registrazione di eventi più complesso e non deve essere individuato in modo autonomo.

Per visualizzare o annullare una sottoscrizione creata con il parametro SupportEvent, aggiungere il parametro Force ai cmdlet Get-EventSubscriber o Unregister-Event.

Proprietà dei parametri

Tipo:SwitchParameter
Valore predefinito:None
Supporta i caratteri jolly:False
DontShow:False

Set di parametri

(All)
Posizione:Named
Obbligatorio:False
Valore dalla pipeline:False
Valore dalla pipeline in base al nome della proprietà:False
Valore dagli argomenti rimanenti:False

CommonParameters

Questo cmdlet supporta i parametri comuni: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Per altre informazioni, vedi about_CommonParameters.

Input

None

Gli oggetti non possono essere inviati tramite pipe a questo cmdlet.

Output

None

Per impostazione predefinita, questo cmdlet non restituisce alcun output.

PSEventJob

Quando si utilizza il parametro Action, questo cmdlet restituisce un oggetto PSEventJob.

Note

Gli eventi, le sottoscrizioni di eventi e la coda di eventi esistono solo nella sessione corrente. Se si chiude la sessione corrente, la coda di eventi viene eliminata e la sottoscrizione di eventi 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 attivato solo quando la sessione viene terminata sotto il controllo di PowerShell. L'evento non viene generato quando l'applicazione host o la finestra del terminale viene chiusa.

Il motore è considerato inattivo se non esegue una pipeline. L'evento OnIdle viene generato quando PowerShell è inattiva per 300 millisecondi (millisecondi).

Annotazioni

Quando PSReadLine è in uso, l'evento OnIdle viene generato quando si verifica il timeout di ReadKey() (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 del OnIdle è stato modificato per segnalare l'evento solo se esiste un timeout ReadKey() e il buffer di modifica corrente è vuoto.