Condividi tramite

Register-ObjectEvent

  • Riferimento
Modulo:
Microsoft.PowerShell.Utility

Sottoscrive gli eventi generati da un oggetto Microsoft .NET Framework.

Sintassi

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

Descrizione

Il cmdlet Register-ObjectEvent 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 di eventi nella sessione. Per ottenere eventi nella coda di eventi, usare il cmdlet Get-Event.

È 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 eventi nella sessione locale.

Quando si sottoscrive un evento, alla sessione viene aggiunto un sottoscrittore di eventi. 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 dell'evento dalla sessione.

Esempio

Esempio 1: Sottoscrivere eventi all'avvio di un nuovo processo

Questo esempio sottoscrive gli eventi generati all'avvio di un nuovo processo.

Il comando usa l'oggetto ManagementEventWatcher per ottenere 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 di eventi. L'azione risponde invece all'evento. In questo esempio, quando viene generato un evento di creazione dell'istanza che indica che viene avviato un nuovo processo, viene generato un nuovo evento di 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 e $EventArgs variabili automatiche che vengono popolate solo per le azioni degli eventi.

Il comando Register-ObjectEvent 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.

Esempio 3: Sottoscrivere eventi oggetto nei computer remoti

In questo esempio viene illustrato come sottoscrivere gli eventi oggetto nei computer remoti. In questo esempio viene utilizzata la funzione Enable-ProcessCreationEvent definita nel file di script ProcessCreationEvent.ps1. 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 }

Il primo viene creato PSSessions in due computer remoti e salvarli nella variabile $S. Il cmdlet Invoke-Command eseguire quindi lo script di ProcessCreationEvent.ps1 in ognuna delle sessioni PSSession in $S. Questa azione crea la funzione Enable-ProcessCreationEvent nelle sessioni remote. Infine, viene eseguita la funzione Enable-ProcessCreationEvent nelle sessioni remote.

La funzione include un comando Register-ObjectEvent che sottoscrive gli eventi di creazione dell'istanza nell'oggetto Win32_Process tramite l'oggetto ManagementEventWatcher eventArrived.

Esempio 4: Usare il modulo dinamico nell'oggetto PSEventJob

Questo esempio illustra come usare il modulo dinamico nell'oggetto PSEventJob creato quando si include un Action in una registrazione eventi. Prima di tutto creiamo e abilitiamo un oggetto timer, quindi impostiamo l'intervallo del timer su 500 (millisecondi). Il cmdlet registra l'evento trascorso dell'oggetto timer. L'oggetto PSEventJob viene salvato nella 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 cmdlet Get-Random genera un numero casuale compreso tra 0 e 100 e lo salva nella variabile $Random.

$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

Il PSEventJob dispone di una proprietà module di che contiene un modulo di script dinamico che implementa l'azione. Usando l'operatore di chiamata (&), viene richiamato il comando nel modulo per visualizzare il valore della variabile $Random.

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 variabili automatiche , , , e . Queste variabili forniscono informazioni sull'evento al blocco di 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 a cui si sta sottoscrivendo.

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 cmdlet Get-Member.

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 contenente 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 eventuali dati aggiuntivi da associare a questa sottoscrizione di eventi. Il valore di questo parametro viene visualizzato nella proprietà MessageData di tutti gli eventi associati a questa 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 cmdlet e .

Tipo:SwitchParameter
Posizione:Named
Valore predefinito:None
Necessario:False
Accettare l'input della pipeline:False
Accettare caratteri jolly:False

Input

None

Non è possibile inviare oggetti tramite pipe a Register-ObjectEvent.

Output

None or System.Management.Automation.PSEventJob

Quando si utilizza il parametro Action , restituisce un oggetto System.Management.Automation.PSEventJob. In caso contrario, non genera alcun output.

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.