Register-ObjectEvent

Модуль:: Microsoft.PowerShell.Utility Module

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

Синтаксис

Default (по умолчанию)

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

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

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

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

В этом примере показано, как использовать динамический модуль в объекте PSEventJob psEventJob, который создается при включении Action в регистрацию событий. Сначала мы создадим и включите объект таймера, а затем задайте интервал таймера в 500 (миллисекундах). Командлет регистрирует событие объекта таймера. Объект PSEventJob сохраняется в переменной и также доступен в свойстве 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. Дополнительные сведения см. в разделе about_Automatic_Variables.

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

Свойства параметра

Тип:	ScriptBlock
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	101
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-EventName

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

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

Свойства параметра

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	1
Обязательно:	True
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-Forward

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

Свойства параметра

Тип:	SwitchParameter
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-InputObject

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

Свойства параметра

Тип:	PSObject
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	0
Обязательно:	True
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-MaxTriggerCount

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

Свойства параметра

Тип:	Int32
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-MessageData

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

Свойства параметра

Тип:	PSObject
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-SourceIdentifier

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

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

Свойства параметра

Тип:	String
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	100
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

-SupportEvent

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

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

Свойства параметра

Тип:	SwitchParameter
Default value:	None
Поддерживаются подстановочные знаки:	False
DontShow:	False

Наборы параметров

(All)

Position:	Named
Обязательно:	False
Значение из конвейера:	False
Значение из конвейера по имени свойства:	False
Значение из оставшихся аргументов:	False

CommonParameters

Этот командлет поддерживает общие параметры: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction и -WarningVariable. Дополнительные сведения см. в разделе about_CommonParameters.

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

None

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

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

None

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

PSEventJob

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

Примечания

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

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

Были ли сведения на этой странице полезными?

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

Register-ObjectEvent

Синтаксис

Default (по умолчанию)

Описание

Примеры

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

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

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

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

Параметры

-Action

Свойства параметра

Наборы параметров

-EventName

Свойства параметра

Наборы параметров

-Forward

Свойства параметра

Наборы параметров

-InputObject

Свойства параметра

Наборы параметров

-MaxTriggerCount

Свойства параметра

Наборы параметров

-MessageData

Свойства параметра

Наборы параметров

-SourceIdentifier

Свойства параметра

Наборы параметров

-SupportEvent

Свойства параметра

Наборы параметров

CommonParameters

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

None

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

None

PSEventJob

Примечания

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

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