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

При подписке на событие к текущему сеансу добавляется подписчик события. Чтобы получить подписчиков событий в сеансе, используйте 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 , созданном при включении действия в регистрацию события. Сначала мы создадим и включите объект таймера, а затем задайте интервал таймера в 500 (миллисекундах). Командлет Register-ObjectEvent регистрирует событие, прошедшее по истечении срока действия объекта таймера. Объект 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 представляющий это действие. Командлеты группы 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-EventSubscriber Force командлетов.Unregister-Event

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

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

None

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

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

None

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

PSEventJob

При использовании параметра Action этот командлет возвращает объект 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

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

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

Примечания

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

Обратная связь

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