Register-EngineEvent (Microsoft.PowerShell.Utility)

Register-EngineEvent

Модуль:

Microsoft.PowerShell.Utility

Подписывается на события, генерируемые обработчиком PowerShell и командлетом New-Event.

Синтаксис

Register-EngineEvent
        [-SourceIdentifier] <String>
        [[-Action] <ScriptBlock>]
        [-MessageData <PSObject>]
        [-SupportEvent]
        [-Forward]
        [-MaxTriggerCount <Int32>]
        [<CommonParameters>]

Описание

Командлет Register-EngineEvent подписывается на события, генерируемые обработчиком PowerShell и командлетом New-Event. Используйте параметр SourceIdentifier, чтобы указать событие.

Этот командлет можно использовать для подписки на события механизма OnIdle или Exiting, а также на события, генерируемые командлетом New-Event. Эти события автоматически добавляются в очередь событий вашего сеанса без подписки. Однако подписка позволяет пересылать события, указывать действие для реагирования на события и отменять подписку.

Когда вы подписываетесь на событие, к вашему сеансу добавляется подписчик на событие. Чтобы получить подписчиков событий в сеансе, используйте командлет Get-EventSubscriber. Чтобы отменить подписку, используйте командлет Unregister-Event, который удаляет подписчика на событие из сеанса.

Когда событие, на которое вы подписаны, возникает, оно добавляется в очередь событий вашего сеанса. Чтобы получить события в очереди событий, используйте командлет Get-Event.

Примеры

Пример 1. Регистрация события механизма PowerShell на удаленных компьютерах.

В этом примере событие механизма PowerShell регистрируется на двух удаленных компьютерах.

$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S {
  Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward
}

New-PSSession создает управляемый пользователем сеанс (PSSession) на каждом из удаленных компьютеров. Командлет Invoke-Command запускает Register-EngineEvent команду в удаленных сеансах. Register-EngineEvent использует параметр SourceIdentifier для идентификации события. Параметр Forward указывает механизму пересылать события из удаленного сеанса в локальный сеанс.

Пример 2. Выполнение указанного действия при возникновении события «Выход».

В этом примере показано, как запустить Register-EngineEvent, чтобы выполнить определенное действие при возникновении события PowerShell.Exiting.

Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
    Get-History | Export-Clixml $HOME\history.clixml
}

Параметр SupportEvent добавлен, чтобы скрыть подписку на события. В этом случае при выходе PowerShell история команд из завершившегося сеанса экспортируется в XML-файл в каталог $HOME пользователя.

Пример 3. Создание определяемого пользователем события и подписка на него.

В этом примере создается подписка на события из источника MyEventSource. Это произвольный источник, который мы собираемся использовать для отслеживания хода выполнения задания. Register-EngineEvent используется для создания подписки. Блок сценария для параметра Действие записывает данные о событии в текстовый файл.

Register-EngineEvent -SourceIdentifier MyEventSource -Action {
    "Event: {0}" -f $event.messagedata | Out-File c:\temp\MyEvents.txt -Append
}

Start-Job -Name TestJob -ScriptBlock {
    While ($True) {
        Register-EngineEvent -SourceIdentifier MyEventSource -Forward
        Start-Sleep -seconds 2
        "Doing some work..."
        New-Event -SourceIdentifier MyEventSource -Message ("{0} -  Work done..." -f (Get-Date))
    }
}
Start-Sleep -seconds 4
Get-EventSubscriber
Get-Job

SubscriptionId   : 12
SourceObject     :
EventName        :
SourceIdentifier : MyEventSource
Action           : System.Management.Automation.PSEventJob
HandlerDelegate  :
SupportEvent     : False
ForwardEvent     : False

Id     Name            PSJobTypeName   State         HasMoreData     Location             Command
--     ----            -------------   -----         -----------     --------             -------
18     MyEventSource                   Running       True                                 …
19     TestJob         BackgroundJob   Running       True            localhost            …

Register-EngineEvent создал идентификатор задания 18. Start-Job создал идентификатор задания 19. В примере №4 мы удаляем подписку на события и задания, а затем проверяем файл журнала.

Пример 4. Отмена регистрации событий и очистка заданий

Это продолжение примера 3. В этом примере мы ждем 10 секунд, чтобы произошло несколько событий. Затем мы отменяем регистрацию подписки на событие.

PS> Start-Sleep -seconds 10
PS> Get-EventSubscriber | Unregister-Event
PS> Get-Job

Id     Name            PSJobTypeName   State         HasMoreData     Location             Command
--     ----            -------------   -----         -----------     --------             -------
18     MyEventSource                   Stopped       False                                …
19     TestJob         BackgroundJob   Running       True            localhost            …

PS> Stop-Job -Id 19
PS> Get-Job | Remove-Job
PS> Get-Content C:\temp\MyEvents.txt
Event: 2/18/2020 2:36:19 PM -  Work done...
Event: 2/18/2020 2:36:21 PM -  Work done...
Event: 2/18/2020 2:36:23 PM -  Work done...
Event: 2/18/2020 2:36:25 PM -  Work done...
Event: 2/18/2020 2:36:27 PM -  Work done...
Event: 2/18/2020 2:36:29 PM -  Work done...
Event: 2/18/2020 2:36:31 PM -  Work done...

Командлет Unregister-Event останавливает задание, связанное с подпиской на событие (идентификатор задания 18). Задание с идентификатором 19 все еще выполняется и создает новые события. Мы используем командлеты Job, чтобы остановить задание и удалить ненужные объекты задания. Get-Content отображает содержимое файла журнала.

Параметры

-Action

Указывает команды для обработки событий. Команды в Действии выполняются при возникновении события, а не отправляют его в очередь событий. Заключите команды в фигурные скобки ({}), чтобы создать блок сценария.

Значение параметра Action может включать в себя $Event, $EventSubscriber, $Sender, $. EventArgs и автоматические переменные $Args, которые предоставляют информацию о событии в блок скрипта Action. Дополнительные сведения см. в разделе about_Automatic_Variables.

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

Тип :

ScriptBlock

Позиция:

101

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-Forward

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

Тип :

SwitchParameter

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-MaxTriggerCount

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

Тип :

Int32

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-MessageData

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

Тип :

PSОбъект

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-SourceIdentifier

Указывает идентификатор источника события, на которое вы подписываетесь. Идентификатор источника должен быть уникальным в текущем сеансе. Этот параметр является обязательным.

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

Значение зависит от источника события. Это может быть произвольное значение, созданное вами для использования с командлетом New-Event. Механизм PowerShell поддерживает значения PSEngineEvent, PowerShell.Exiting и PowerShell.OnIdle.

Тип :

String

Позиция:

100

Значение по умолчанию:

None

Необходимый:

True

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-SupportEvent

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

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

Тип :

SwitchParameter

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

Входы

Нет

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

Выходы

Нет

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

PSEventJob

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

Примечания

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

При подписке на событие Exiting командлеты, которые могут быть выполнены с помощью параметра Action, ограничиваются командлетами в Microsoft.PowerShell.Core. и модули Microsoft.PowerShell.Utility. Событие Exiting генерируется только тогда, когда сеанс завершается под контролем PowerShell. Событие не запускается при закрытии главного приложения или окна терминала.

Двигатель считается работающим на холостом ходу, если в нем не работает трубопровод. Событие OnIdle генерируется, когда PowerShell бездействует в течение 300 миллисекунд (мс).