Register-ObjectEvent
Sottoscrive gli eventi generati da un oggetto di Microsoft .NET Framework.
Sintassi
Register-ObjectEvent
[-InputObject] <PSObject>
[-EventName] <String>
[[-SourceIdentifier] <String>]
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>]
Descrizione
Il Register-ObjectEvent
cmdlet sottoscrive gli eventi generati da oggetti .NET nel computer locale o in un computer remoto.
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 .
È possibile usare i parametri di Register-ObjectEvent
per specificare i valori delle proprietà degli eventi che consentono di identificare l'evento nella coda. È anche possibile utilizzare il parametro Action per specificare le azioni da eseguire quando viene generato un evento sottoscritto e il parametro Forward per inviare eventi remoti alla coda di eventi nella sessione locale.
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.
Esempio
Esempio 1: Sottoscrivere eventi all'avvio di un nuovo processo
Questo esempio sottoscrive gli eventi generati quando viene avviato un nuovo processo.
Il comando usa l'oggetto ManagementEventWatcher per ottenere gli eventi EventArrived . Un oggetto query specifica che gli eventi sono eventi di creazione di istanze per la classe Win32_Process .
$queryParameters = '__InstanceCreationEvent', (New-Object TimeSpan 0,0,1),
"TargetInstance isa 'Win32_Process'"
$Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters
$ProcessWatcher = New-Object System.Management.ManagementEventWatcher $Query
Register-ObjectEvent -InputObject $ProcessWatcher -EventName "EventArrived"
Esempio 2: Specificare un'azione per rispondere a un evento
Quando si specifica un'azione, gli eventi generati non vengono aggiunti alla coda degli eventi. Al contrario, l'azione risponde all'evento. In questo esempio, quando viene generato un evento di creazione di un'istanza che indica che viene avviato un nuovo processo, viene generato un nuovo evento ProcessCreated .
$queryParameters = '__InstanceCreationEvent', (New-Object TimeSpan 0,0,1),
"TargetInstance isa 'Win32_Process'"
$Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters
$ProcessWatcher = New-Object System.Management.ManagementEventWatcher $query
$newEventArgs = @{
SourceIdentifier = 'PowerShell.ProcessCreated'
Sender = $Sender
EventArguments = $EventArgs.NewEvent.TargetInstance
}
$Action = { New-Event @newEventArgs }
Register-ObjectEvent -InputObject $ProcessWatcher -EventName "EventArrived" -Action $Action
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
5 3db2d67a-efff-... NotStarted False New-Event @newEventArgs
L'azione usa le $Sender
variabili automatiche e $EventArgs
che vengono popolate solo per le azioni evento.
Il Register-ObjectEvent
comando restituisce un oggetto processo che rappresenta l'azione, che viene eseguita come processo in background. È possibile usare i cmdlet job, ad esempio Get-Job
e Receive-Job
, per gestire il processo in background. Per altre informazioni, vedere About Jobs (Informazioni sui processi).
Esempio 3: Sottoscrivere eventi oggetto nei computer remoti
Questo esempio mostra come sottoscrivere gli eventi oggetto in computer remoti. In questo esempio viene usata la Enable-ProcessCreationEvent
funzione definita nel ProcessCreationEvent.ps1
file di script. Questo script è disponibile per tutti i computer nell'esempio.
# ProcessCreationEvent.ps1
function Enable-ProcessCreationEvent {
$queryParameters = "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1),
"TargetInstance isa 'Win32_Process'"
$Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters
$objectEventArgs = @{
Input = New-Object System.Management.ManagementEventWatcher $Query
EventName = 'EventArrived'
SourceIdentifier = 'WMI.ProcessCreated'
MessageData = 'Test'
Forward = $True
}
Register-ObjectEvent @objectEventArgs
}
$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S -FilePath ProcessCreationEvent.ps1
Invoke-Command -Session $S { Enable-ProcessCreationEvent }
La prima operazione viene creata in due computer remoti e salvata nella $S
variabile . Successivamente, il Invoke-Command
cmdlet esegue lo ProcessCreationEvent.ps1
script in ognuna delle sessioni PSSession in $S
. Questa azione crea la Enable-ProcessCreationEvent
funzione nelle sessioni remote.
Infine, si esegue la Enable-ProcessCreationEvent
funzione nelle sessioni remote.
La funzione include un Register-ObjectEvent
comando che sottoscrive gli eventi di creazione di istanze nell'oggetto Win32_Process tramite l'oggetto ManagementEventWatcher e il relativo evento EventArrived.
Esempio 4: Usare il modulo dinamico nell'oggetto PSEventJob
In questo esempio viene illustrato come usare il modulo dinamico nell'oggetto PSEventJob creato quando si include un'azione in una registrazione eventi. Prima di tutto creiamo e abilitiamo un oggetto timer, quindi impostiamo l'intervallo del timer su 500 (millisecondi). Il Register-ObjectEvent
cmdlet registra l'evento Elapsed dell'oggetto timer. L'oggetto PSEventJob viene salvato nella $Job
variabile ed è disponibile anche nella proprietà Action del sottoscrittore dell'evento. Per altre informazioni, vedere Get-EventSubscriber.
Ogni volta che viene trascorso l'intervallo timer, viene generato un evento e viene eseguita l'azione. In questo caso, il Get-Random
cmdlet genera un numero casuale compreso tra 0 e 100 e lo salva nella $Random
variabile.
$Timer = New-Object Timers.Timer
$Timer.Interval = 500
$Timer.Enabled = $True
$objectEventArgs = @{
InputObject = $Timer
EventName = 'Elapsed'
SourceIdentifier = 'Timer.Random'
Action = {$Random = Get-Random -Min 0 -Max 100}
}
$Job = Register-ObjectEvent @objectEventArgs
$Job | Format-List -Property *
& $Job.module {$Random}
& $Job.module {$Random}
State : Running
Module : __DynamicModule_53113769-31f2-42dc-830b-8749325e28d6
StatusMessage :
HasMoreData : True
Location :
Command : $Random = Get-Random -Min 0 -Max 100
JobStateInfo : Running
Finished : System.Threading.ManualResetEvent
InstanceId : 47b5ec9f-bfe3-4605-860a-4674e5d44ca8
Id : 7
Name : Timer.Random
ChildJobs : {}
PSBeginTime : 6/27/2019 10:19:06 AM
PSEndTime :
PSJobTypeName :
Output : {}
Error : {}
Progress : {}
Verbose : {}
Debug : {}
Warning : {}
Information : {}
60
47
PSEventJob dispone di una proprietà Module che contiene un modulo script dinamico che implementa l'azione. Usando l'operatore di chiamata (&
), viene richiamato il comando nel modulo per visualizzare il valore della $Random
variabile.
Per altre informazioni sui moduli, vedere about_Modules.
Parametri
-Action
Specifica i comandi per gestire l'evento. 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
$EventSubscriber
$EventArgs
, , e $Args
. Queste variabili forniscono informazioni sull'evento al blocco script Action . Per altre informazioni, vedere about_Automatic_Variables.
Quando si specifica un'azione, Register-ObjectEvent
restituisce un oggetto processo evento che rappresenta tale azione. È possibile usare i cmdlet Job per gestire il processo dell'evento.
Tipo: | ScriptBlock |
Posizione: | 101 |
Valore predefinito: | None |
Necessario: | False |
Accettare l'input della pipeline: | False |
Accettare caratteri jolly: | False |
-EventName
Specifica l'evento da sottoscrivere.
Il valore di questo parametro deve essere il nome dell'evento esposto dall'oggetto .NET. Ad esempio, la classe ManagementEventWatcher include eventi denominati EventArrived e Stopped. Per trovare il nome dell'evento di un evento, usare il Get-Member
cmdlet .
Tipo: | String |
Posizione: | 1 |
Valore predefinito: | None |
Necessario: | True |
Accettare l'input della pipeline: | False |
Accettare caratteri jolly: | False |
-Forward
Indica che il cmdlet invia eventi per questa sottoscrizione a una sessione remota. Usare questo parametro quando si esegue la registrazione per gli eventi in un computer remoto o in una sessione remota.
Tipo: | SwitchParameter |
Posizione: | Named |
Valore predefinito: | None |
Necessario: | False |
Accettare l'input della pipeline: | False |
Accettare caratteri jolly: | False |
-InputObject
Specifica l'oggetto .NET che genera gli eventi. Immettere una variabile che contiene l'oggetto oppure digitare un comando o un'espressione che ottiene l'oggetto.
Tipo: | PSObject |
Posizione: | 0 |
Valore predefinito: | None |
Necessario: | True |
Accettare l'input della pipeline: | False |
Accettare caratteri jolly: | False |
-MaxTriggerCount
Specifica il numero massimo di volte in cui è possibile attivare un evento.
Tipo: | Int32 |
Posizione: | Named |
Valore predefinito: | None |
Necessario: | False |
Accettare l'input della pipeline: | False |
Accettare caratteri jolly: | False |
-MessageData
Specifica i dati aggiuntivi da associare alla sottoscrizione di eventi. Il valore di questo parametro viene visualizzato nella proprietà MessageData di tutti gli eventi associati alla sottoscrizione.
Tipo: | PSObject |
Posizione: | Named |
Valore predefinito: | None |
Necessario: | False |
Accettare l'input della pipeline: | False |
Accettare caratteri jolly: | False |
-SourceIdentifier
Specifica un nome selezionato per la sottoscrizione. Il nome selezionato deve essere univoco nella sessione corrente. Il valore predefinito è il GUID assegnato da PowerShell.
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.
Tipo: | String |
Posizione: | 100 |
Valore predefinito: | None |
Necessario: | False |
Accettare l'input della pipeline: | False |
Accettare caratteri jolly: | False |
-SupportEvent
Indica che il cmdlet nasconde la sottoscrizione di eventi. Usare 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 , usare il parametro Force dei Get-EventSubscriber
cmdlet e Unregister-Event
.
Tipo: | SwitchParameter |
Posizione: | Named |
Valore predefinito: | None |
Necessario: | False |
Accettare l'input della pipeline: | False |
Accettare caratteri jolly: | 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 PSEventJob .
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.