Создает подписку на события, создаваемые обработчиком Windows PowerShell и командлетом New-Event.
Синтаксис
Register-EngineEvent [-SourceIdentifier] <string> [[-Действие] <scriptblock>] [-Forward] [-MessageData <psobject>] [-SupportEvent] [<CommonParameters>]
Описание
Командлет Register-EngineEvent создает подписку на события, создаваемые обработчиком Windows PowerShell и командлетом New-Event. Для задания события используйте параметр SourceIdentifier.
Этот командлет позволяет подписаться на "существующие" события обработчика, а также на события, создаваемые командлетом New-Event. Эти события автоматически добавляются в очередь событий сеанса без оформления подписки. Однако создание подписки позволяет перенаправлять события, задавать действия для реагирования на них, а также отменять подписку.
При возникновении события, для которого создана подписка, это событие добавляется в очередь событий сеанса. Чтобы получить события из очереди событий, используйте командлет Get-Event.
При создании подписки на событие в сеанс добавляется подписчик на это событие. Чтобы получить подписчики на события в сеансе, используйте командлет Get-EventSubscriber. Чтобы отменить подписку, воспользуйтесь командлетом Unregister-Event, удаляющим подписчик на событие из сеанса.
Параметры
-Действие <scriptblock>
Задает команды для обработки событий. Когда происходит событие, вместо передачи события в очередь событий выполняются эти команды. Чтобы создать блок скрипта, заключите команды в фигурные скобки ( { } ).
Значение параметра Action может включать автоматические переменные $Event, $EventSubscriber, $Sender, $SourceEventArgs и $SourceArgs, предоставляющие информацию о событии в блок скрипта Action. Дополнительные сведения см. в разделе about_Automatic_Variables.
Если задано действие, командлет Register-EngineEvent возвращает объект задания события, представляющего это действие. Командлеты Job позволяют управлять заданием события.
|
Обязательно? |
false |
|
Позиция? |
102 |
|
Значение по умолчанию |
нет |
|
Принимать входные данные из конвейера? |
false |
|
Принимать подстановочные знаки? |
false |
-Forward
Отправляет события по данной подписке сеансу на локальном компьютере. Этот параметр используется при регистрации для получения событий на удаленном компьютере или в удаленном сеансе.
|
Обязательно? |
false |
|
Позиция? |
named |
|
Значение по умолчанию |
False |
|
Принимать входные данные из конвейера? |
false |
|
Принимать подстановочные знаки? |
false |
-MessageData <psobject>
Задает дополнительные данные, связанные с событием. Значение этого параметра хранится в свойстве MessageData объекта события.
|
Обязательно? |
false |
|
Позиция? |
named |
|
Значение по умолчанию |
нет |
|
Принимать входные данные из конвейера? |
false |
|
Принимать подстановочные знаки? |
false |
-SourceIdentifier <string>
Задает идентификатор источника события, для которого создается подписка. Идентификатор источника должен быть уникальным в пределах текущего сеанса. Это обязательный параметр.
Значение этого параметра присваивается свойству SourceIdentifier объекта подписчика и объектов событий, связанных с данной подпиской.
|
Обязательно? |
true |
|
Позиция? |
101 |
|
Значение по умолчанию |
|
|
Принимать входные данные из конвейера? |
false |
|
Принимать подстановочные знаки? |
false |
-SupportEvent
Скрывает подписку на события. Этот параметр используется, если текущая подписка является частью более сложного механизма регистрации событий и не должна обнаруживаться независимым образом.
Чтобы просмотреть или отменить подписку, созданную с использованием параметра SupportEvent, воспользуйтесь параметром Force командлетов Get-EventSubscriber и Unregister-Event.
|
Обязательно? |
false |
|
Позиция? |
named |
|
Значение по умолчанию |
False |
|
Принимать входные данные из конвейера? |
false |
|
Принимать подстановочные знаки? |
false |
<CommonParameters>
Данный командлет поддерживает общие параметры -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer и -OutVariable. Дополнительные сведения см. в разделе about_Commonparameters.
Ввод и вывод
Входным типом является тип объектов, которые можно передавать командлету по конвейеру. Возвращаемым типом является тип объектов, возвращаемых командлетом.
|
Входные данные |
Нет Данные невозможно передать командлету Register-EngineEvent по конвейеру. |
|
Выходные данные |
Нет или System.Management.Automation.PSEventJob При использовании параметра Action командлет Register-EngineEvent возвращает объект System.Management.Automation.PSEventJob. В противном случае командлет не формирует никаких выходных данных. |
Примечания
События, подписки на события и очередь событий существуют только в рамках текущего сеанса. Если завершить текущий сеанс, очередь событий будет очищена и подписка на события будет отменена.
Пример 1
C:\PS>$s = new-pssession -computername Server01, Server02
C:\PS> invoke-command -session $s { Register-EngineEvent -sourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -forward }
Описание
-----------
Эта команда создает подписку на событие обработчика Windows PowerShell на двух удаленных компьютерах.
Первая команда создает сеанс PSSession на каждом из удаленных компьютеров.
Вторая команда использует командлет Invoke-Command для выполнения команды Register-EngineEvent в рамках удаленного сеанса.
Для определения события команда Register-EngineEvent использует параметр SourceIdentifier. А для перенаправления событий из удаленного сеанса в локальный сеанс используется параметр Forward.
Пример 2
C:\PS>$j = register-engineEvent -sourceIdentifier PowerShell.ProcessCreated -action { $processName | add-content processLog.txt }
C:\PS> get-event
C:\PS> $results = $j | receive-job
C:\PS> unregister-event PowerShell.ProcessCreated
Описание
-----------
Эта команда показывает, как использовать командлеты Job для управления объектом задания события, возвращаемым командлетом Register-EngineEvent при задании параметра Action.
Управление заданием события осуществляется так же, как и любым другим заданием Windows PowerShell. Дополнительные сведения см. в разделе about_jobs. В этом примере для получения результатов задания используется командлет Receive-Job.
Чтобы удалить задание из сеанса, используйте командлет Remove-Job. Чтобы отменить подписку на событие, используйте командлет Unregister-Event. Чтобы удалить события из очереди событий, используйте командлет Remove-Event.
См. также