Condividi tramite

Register-ObjectEvent

Modulo:
Microsoft.PowerShell.Utility Module

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

Sintassi

Default (impostazione predefinita). 

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 tua sessione. Per ottenere eventi nella coda di eventi, utilizzare 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 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.

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 ulteriori 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 direttamente quando viene generato un evento, al posto di 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 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

-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.

Proprietà dei parametri

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

Set di parametri

(All)
Posizione:1
Obbligatorio:True
Valore dalla pipeline:False
Valore dalla pipeline in base al nome della proprietà:False
Valore dagli argomenti rimanenti: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.

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

-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 .

Proprietà dei parametri

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

Set di parametri

(All)
Posizione:0
Obbligatorio:True
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 è possibile attivare un evento.

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

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.

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 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.

Proprietà dei parametri

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

Set di parametri

(All)
Posizione:100
Obbligatorio:False
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. 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 .

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.