Condividi tramite

Register-ObjectEvent

  • Riferimento
Modulo:
Microsoft.PowerShell.Utility

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 P edizione Standard ventJob

Questo esempio illustra come usare il modulo dinamico nell'oggetto P edizione Standard ventJob 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 P edizione Standard ventJob 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

P edizione Standard ventJob dispone di una proprietà Module 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 $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 $Eventvariabili 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.

Type:ScriptBlock
Position:101
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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 .

Type:String
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters: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.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:PSObject
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-MaxTriggerCount

Specifica il numero massimo di volte in cui è possibile attivare un evento.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:PSObject
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:String
Position:100
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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 .

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.