Register-ObjectEvent

Синтаксис

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

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

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

None

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

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

None

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

PSEventJob

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

Примечания

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

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

• Get-Event
• New-Event
• Register-EngineEvent
• Remove-Event
• Unregister-Event
• Wait-Event