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. См. дополнительные сведения о заданиях.

Пример 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 }

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

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

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

В этом примере показано, как использовать динамический модуль в объекте PSEventJob , который создается при включении action в регистрацию события. Сначала мы создадим и включим объект таймера, а затем зададим интервал таймера равным 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 не отправляют его в очередь. а выполняют. Чтобы создать блок скрипта, заключите команды в скобки ( { } ).

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

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

Type:	ScriptBlock
Position:	101
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-EventName

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

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

Type:	String
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Forward

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

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InputObject

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

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

-MaxTriggerCount

Указывает максимальное число активаций события.

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MessageData

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

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

-SourceIdentifier

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

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

Type:	String
Position:	100
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SupportEvent

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

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

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Входные данные

None

Невозможно передать объекты в Register-ObjectEvent.

Выходные данные

None or System.Management.Automation.PSEventJob

При использовании параметра Register-ObjectEventAction возвращает объект System.Management.Automation.PSEventJob. В противном случае командлет не формирует никаких выходных данных.

Примечания

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

Поделиться через

Register-ObjectEvent

Синтаксис

Описание

Примеры

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

Пример 2. Указание действия для реагирования на событие

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

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

Параметры

-Action

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

Входные данные

Выходные данные

Примечания

Дополнительные ресурсы

Поделиться через

Register-ObjectEvent

Синтаксис

Описание

Примеры

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

Пример 2. Указание действия для реагирования на событие

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

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

Параметры

-Action

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

Входные данные

Выходные данные

Примечания

Связанные ссылки

Дополнительные ресурсы