Register-ObjectEvent
Se suscribe a los eventos generados por un objeto de Microsoft .NET Framework.
Sintaxis
Register-ObjectEvent
[-InputObject] <PSObject>
[-EventName] <String>
[[-SourceIdentifier] <String>]
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>] Description
El cmdlet Register-ObjectEvent se suscribe a eventos generados por objetos .NET en el equipo local o en un equipo remoto.
Cuando se genera el evento suscrito, se agrega a la cola de eventos de la sesión. Para obtener eventos en la cola de eventos, use el cmdlet Get-Event.
Puede usar los parámetros de Register-ObjectEvent para especificar los valores de propiedad de los eventos que pueden ayudarle a identificar el evento en la cola. También puede usar el parámetro Action para especificar las acciones que se deben realizar cuando se genera un evento suscrito y el parámetro Forward para enviar eventos remotos a la cola de eventos en la sesión local.
Cuando se suscribe a un evento, se agrega un suscriptor de eventos a la sesión. Para obtener los suscriptores de eventos en la sesión, use el cmdlet Get-EventSubscriber. Para cancelar la suscripción, use el cmdlet Unregister-Event, que elimina el suscriptor de eventos de la sesión.
Ejemplos
Ejemplo 1: Suscribirse a eventos cuando se inicia un nuevo proceso
En este ejemplo se suscribe a eventos generados cuando se inicia un nuevo proceso.
El comando usa el objeto managementEventWatcher de
$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"Ejemplo 2: Especificar una acción para responder a un evento
Al especificar una acción, los eventos que se generan no se agregan a la cola de eventos. En su lugar, la acción responde al evento . En este ejemplo, cuando se genera un evento de creación de instancias que indica que se inicia un nuevo proceso, se genera un nuevo 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 @newEventArgsLa acción usa el $Sender y $EventArgs variables automáticas que se rellenan solo para las acciones de evento.
El comando Register-ObjectEvent devuelve un objeto de trabajo que representa la acción, que se ejecuta como un trabajo en segundo plano. Puede usar los cmdlets job, como Get-Job y Receive-Job, para administrar el trabajo en segundo plano. Para obtener más información, vea about_Jobs.
Ejemplo 3: Suscribirse a eventos de objeto en equipos remotos
En este ejemplo se muestra cómo suscribirse a eventos de objeto en equipos remotos. En este ejemplo se usa la función Enable-ProcessCreationEvent que se define en el archivo de script de ProcessCreationEvent.ps1. Este script está disponible para todos los equipos del ejemplo.
# 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 primera que creamos PSSessions en dos equipos remotos y las guardamos en la variable $S. A continuación, el cmdlet Invoke-Command ejecuta el script de ProcessCreationEvent.ps1 en cada una de las PSSessions de $S. Esta acción crea la función Enable-ProcessCreationEvent en las sesiones remotas.
Por último, ejecutamos la función Enable-ProcessCreationEvent en las sesiones remotas.
La función incluye un comando Register-ObjectEvent que se suscribe a eventos de creación de instancias en el objeto Win32_Process a través del objeto ManagementEventWatcher y su evento EventArrived.
Ejemplo 4: Uso del módulo dinámico en el objeto PSEventJob
En este ejemplo se muestra cómo usar el módulo dinámico en el
Cada vez que transcurre el intervalo del temporizador, se genera un evento y se ejecuta la acción. En este caso, el cmdlet Get-Random genera un número aleatorio entre 0 y 100 y lo guarda en la variable $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
47El PSEventJob de &), invocamos el comando en el módulo para mostrar el valor de la variable $Random.
Para obtener más información sobre los módulos, consulte about_Modules.
Parámetros
-Action
Especifica los comandos para controlar el evento. Los comandos de Action se ejecutan cuando se genera un evento, en lugar de enviar el evento a la cola de eventos. Incluya los comandos entre llaves ( { } ) para crear un bloque de script.
El valor del parámetro Action de
Al especificar una acción, Register-ObjectEvent devuelve un objeto de trabajo de evento que representa esa acción. Puede usar los cmdlets job para administrar el trabajo de evento.
| Tipo: | ScriptBlock |
| Posición: | 101 |
| Valor predeterminado: | None |
| Requerido: | False |
| Aceptar entrada de canalización: | False |
| Aceptar caracteres comodín: | False |
-EventName
Especifica el evento al que se va a suscribir.
El valor de este parámetro debe ser el nombre del evento que expone el objeto .NET. Por ejemplo, la clase managementEventWatcher de Get-Member.
| Tipo: | String |
| Posición: | 1 |
| Valor predeterminado: | None |
| Requerido: | True |
| Aceptar entrada de canalización: | False |
| Aceptar caracteres comodín: | False |
-Forward
Indica que el cmdlet envía eventos para esta suscripción a una sesión remota. Use este parámetro cuando se registren eventos en un equipo remoto o en una sesión remota.
| Tipo: | SwitchParameter |
| Posición: | Named |
| Valor predeterminado: | None |
| Requerido: | False |
| Aceptar entrada de canalización: | False |
| Aceptar caracteres comodín: | False |
-InputObject
Especifica el objeto .NET que genera los eventos. Escriba una variable que contenga el objeto o escriba un comando o expresión que obtenga el objeto .
| Tipo: | PSObject |
| Posición: | 0 |
| Valor predeterminado: | None |
| Requerido: | True |
| Aceptar entrada de canalización: | False |
| Aceptar caracteres comodín: | False |
-MaxTriggerCount
Especifica el número máximo de veces que se puede desencadenar un evento.
| Tipo: | Int32 |
| Posición: | Named |
| Valor predeterminado: | None |
| Requerido: | False |
| Aceptar entrada de canalización: | False |
| Aceptar caracteres comodín: | False |
-MessageData
Especifica los datos adicionales que se van a asociar a esta suscripción de eventos. El valor de este parámetro aparece en la propiedad MessageData de todos los eventos asociados a esta suscripción.
| Tipo: | PSObject |
| Posición: | Named |
| Valor predeterminado: | None |
| Requerido: | False |
| Aceptar entrada de canalización: | False |
| Aceptar caracteres comodín: | False |
-SourceIdentifier
Especifica un nombre que seleccione para la suscripción. El nombre que seleccione debe ser único en la sesión actual. El valor predeterminado es el GUID que asigna PowerShell.
El valor de este parámetro aparece en el valor del SourceIdentifier propiedad del objeto de suscriptor y todos los objetos de evento asociados a esta suscripción.
| Tipo: | String |
| Posición: | 100 |
| Valor predeterminado: | None |
| Requerido: | False |
| Aceptar entrada de canalización: | False |
| Aceptar caracteres comodín: | False |
-SupportEvent
Indica que el cmdlet oculta la suscripción de eventos. Use este parámetro cuando la suscripción actual forme parte de un mecanismo de registro de eventos más complejo y no se debe detectar de forma independiente.
Para ver o cancelar una suscripción que se creó con el parámetro supportEvent
| Tipo: | SwitchParameter |
| Posición: | Named |
| Valor predeterminado: | None |
| Requerido: | False |
| Aceptar entrada de canalización: | False |
| Aceptar caracteres comodín: | False |
Entradas
None
No se pueden canalizar objetos a Register-ObjectEvent.
Salidas
None or System.Management.Automation.PSEventJob
Al usar el parámetro Action
Notas
Los eventos, las suscripciones de eventos y la cola de eventos solo existen en la sesión actual. Si cierra la sesión actual, se descarta la cola de eventos y se cancela la suscripción de eventos.