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






См. также




Содержание