Register-ObjectEvent (Microsoft.PowerShell.Utility)

Register-ObjectEvent

Модуль:

Microsoft.PowerShell.Utility

Подписывается на события, генерируемые объектом Microsoft .NET Framework.

Синтаксис

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

Описание

Командлет Register-ObjectEvent подписывается на события, генерируемые объектами .NET на локальном или удаленном компьютере.

Когда событие, на которое вы подписаны, возникает, оно добавляется в очередь событий вашего сеанса. Чтобы получить события в очереди событий, используйте командлет Get-Event.

Вы можете использовать параметры Register-ObjectEvent, чтобы указать значения свойств событий, которые помогут вам идентифицировать событие в очереди. Вы также можете использовать параметр Action, чтобы указать действия, которые необходимо выполнить при возникновении подписанного события, и параметр Forward, чтобы отправлять удаленные события в очередь событий в локальном сеансе.

Когда вы подписываетесь на событие, к вашему сеансу добавляется подписчик на событие. Чтобы получить подписчиков событий в сеансе, используйте командлет Get-EventSubscriber. Чтобы отменить подписку, используйте командлет Unregister-Event, который удаляет подписчика на событие из сеанса.

Примеры

Пример 1. Подписка на события при запуске нового процесса

В этом примере подписываются события, генерируемые при запуске нового процесса.

Команда использует объект ManagementEventWatcher для получения событий EventArrived. Объект запроса указывает, что события являются событиями создания экземпляра для класса 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"

Пример 2. Укажите действие в ответ на событие

Когда вы указываете действие, возникающие события не добавляются в очередь событий. Вместо этого действие реагирует на событие. В этом примере, когда возникает событие создания экземпляра, указывающее на запуск нового процесса, возникает новое событие 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

В действии используются автоматические переменные $Sender и $EventArgs, которые заполняются только для действий по событию.

Команда Register-ObjectEvent возвращает объект задания, представляющий действие, которое выполняется как фоновое задание. Для управления фоновым заданием можно использовать командлеты задания, такие как Get-Job и Receive-Job. Для получения дополнительной информации см. about_Jobs.

Пример 3. Подписка на события объекта на удаленных компьютерах

В этом примере показано, как подписаться на события объекта на удаленных компьютерах. В этом примере используется функция Enable-ProcessCreationEvent, определенная в файле сценария ProcessCreationEvent.ps1. Этот сценарий доступен для всех компьютеров в примере.

# 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 }

Сначала мы создаем PSSession на двух удаленных компьютерах и сохраняем их в переменной $S. Затем командлет Invoke-Command запускает сценарий ProcessCreationEvent.ps1 в каждом сеансе PSSession в $S. Это действие создает функцию Enable-ProcessCreationEvent в удаленных сеансах. Наконец, мы запускаем функцию Enable-ProcessCreationEvent в удаленных сеансах.

Функция включает команду Register-ObjectEvent, которая подписывается на события создания экземпляра объекта Win32_Process через объект ManagementEventWatcher и его EventArrived< /стронг> событие.

Пример 4. Использование динамического модуля в объекте PSEventJob.

В этом примере показано, как использовать динамический модуль в объекте PSEventJob, который создается при включении Действия в регистрацию события. Сначала мы создаем и активируем объект таймера, затем устанавливаем интервал таймера на 500 (миллисекунды). Командлет Register-ObjectEvent регистрирует событие Elapsed объекта таймера. Объект PSEventJob сохраняется в переменной $Job, а также доступен в свойстве Action подписчика событий. Дополнительные сведения см. в разделе Get-EventSubscriber.

По истечении интервала таймера возникает событие и выполняется действие. В этом случае командлет Get-Random генерирует случайное число от 0 до 100 и сохраняет его в переменной $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

PSEventJob имеет свойство Module, содержащее модуль динамического сценария, реализующий действие. Используя оператор вызова (&), мы вызываем команду в модуле для отображения значения переменной $Random.

Дополнительные сведения о модулях см. в разделе about_Modules.

Параметры

-Action

Указывает команды для обработки события. Команды в Действии выполняются при возникновении события, а не отправляют его в очередь событий. Заключите команды в фигурные скобки ( { } ), чтобы создать блок сценария.

Значение параметра Action может включать в себя $Event, $EventSubscriber, $Sender, $. EventArgs и автоматические переменные $Args. Эти переменные предоставляют информацию о событии блоку сценария Action. Дополнительные сведения см. в разделе about_Automatic_Variables.

Когда вы указываете действие, Register-ObjectEvent возвращает объект задания события, который представляет это действие. Для управления заданием события можно использовать командлеты задания.

Тип :

ScriptBlock

Позиция:

101

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-EventName

Указывает событие, на которое вы подписываетесь.

Значение этого параметра должно быть именем события, предоставляемого объектом .NET. Например, класс ManagementEventWatcher имеет события с именами EventArrived и Stopped. Чтобы найти имя события, используйте командлет Get-Member.

Тип :

String

Позиция:

1

Значение по умолчанию:

None

Необходимый:

True

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-Forward

Указывает, что командлет отправляет события для этой подписки в удаленный сеанс. Используйте этот параметр при регистрации на мероприятия на удаленном компьютере или в удаленном сеансе.

Тип :

SwitchParameter

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-InputObject

Указывает объект .NET, генерирующий события. Введите переменную, содержащую объект, или введите команду или выражение, позволяющее получить объект.

Тип :

PSОбъект

Позиция:

0

Значение по умолчанию:

None

Необходимый:

True

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-MaxTriggerCount

Указывает максимальное количество раз, которое может быть инициировано событие.

Тип :

Int32

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-MessageData

Указывает любые дополнительные данные, которые будут связаны с этой подпиской на событие. Значение этого параметра отображается в свойстве MessageData всех событий, связанных с этой подпиской.

Тип :

PSОбъект

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-SourceIdentifier

Указывает имя, которое вы выбираете для подписки. Выбранное имя должно быть уникальным в текущем сеансе. Значением по умолчанию является GUID, назначенный PowerShell.

Значение этого параметра отображается в значении свойства SourceIdentifier объекта подписчика и всех объектов событий, связанных с этой подпиской.

Тип :

String

Позиция:

100

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-SupportEvent

Указывает, что командлет скрывает подписку на события. Используйте этот параметр, если текущая подписка является частью более сложного механизма регистрации событий и не должна обнаруживаться независимо.

Чтобы просмотреть или отменить подписку, созданную с помощью параметра SupportEvent, используйте параметр Force в Get-EventSubscriber и Unregister- Командлеты событий.

Тип :

SwitchParameter

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

Входы

Нет

Вы не можете передавать объекты в этот командлет.

Выходы

Нет

По умолчанию этот командлет не возвращает никаких результатов.

PSEventJob

При использовании параметра Action этот командлет возвращает объект PSEventJob.

Примечания

События, подписки на события и очередь событий существуют только в текущем сеансе. Если вы закроете текущий сеанс, очередь событий будет удалена, а подписка на события будет отменена.