Register-EngineEvent
Подписывается на события, созданные подсистемой PowerShell и командлетом New-Event .
Синтаксис
Register-EngineEvent
[-SourceIdentifier] <String>
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>] Описание
Командлет Register-EngineEvent подписывается на события, созданные подсистемой PowerShell и командлетом New-Event . Для задания события используйте параметр SourceIdentifier.
Этот командлет можно использовать для подписки на события OnIdle или Exiting engine и события, созданные командлетом 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. Выполнение указанного действия при возникновении события Exiting
В этом примере показано, как выполнить Register-EngineEvent определенное действие при возникновении события PowerShell.Exiting .
Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
Get-History | Export-Clixml $Home\history.clixml
}Параметр SupportEvent добавляется для скрытия подписки на события. Когда PowerShell завершает работу, в этом случае журнал команд из сеанса выхода экспортируется XML-файл в каталог пользователя $Home .
Пример 3. Create и подписка на событие, определяемое пользователем
В этом примере создается подписка на события из источника MyEventSource. Это произвольный источник, который мы будем использовать для отслеживания хода выполнения задания. Register-EngineEvent используется для создания подписки. Блок скрипта для параметра Action записывает данные события в текстовый файл.
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 не отправляют его в очередь. а выполняют. Заключите команды в фигурные скобки ({}), чтобы создать блок скрипта.
Значение параметра Action может включать автоматические $Eventпеременные , $EventSubscriber, $Sender, $EventArgsи $Args , которые предоставляют сведения о событии в блок скрипта действия . Дополнительные сведения см. в статье about_Automatic_Variables.
При указании действия возвращает объект задания события, Register-EngineEvent представляющий это действие. Командлеты группы Job позволяют управлять заданием событий.
| Type: | ScriptBlock |
| Position: | 101 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Forward
Указывает, что командлет отправляет события для этой подписки в сеанс на локальном компьютере. Этот параметр используется при регистрации событий, полученных на удаленном компьютере или в удаленном сеансе.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MaxTriggerCount
Указывает максимальное количество выполнений действия для подписки на события.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MessageData
Указывает дополнительные данные, связанные с событием. Значение этого параметра отображается в свойстве MessageData объекта события.
| Type: | PSObject |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SourceIdentifier
Указывает идентификатор источника события, для которого создается подписка. Идентификатор источника должен быть уникальным в пределах текущего сеанса Это обязательный параметр.
Значение этого параметра отображается в значении свойства SourceIdentifier объекта подписчика, а также всех объектов событий, связанных с этой подпиской.
Значение зависит от источника события. Это может быть произвольное значение, созданное для использования с командлетом New-Event . Подсистема PowerShell поддерживает значения PSEngineEventPowerShell.Exiting и PowerShell.OnIdle.
| Type: | String |
| Position: | 100 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SupportEvent
Указывает, что командлет скрывает подписку на события. Добавьте этот параметр, если текущая подписка является частью более сложного механизма регистрации событий и не должна обнаруживаться независимо.
Чтобы просмотреть или отменить подписку, созданную с помощью параметра SupportEvent , добавьте параметр Force в Get-EventSubscriber командлеты или Unregister-Event .
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Входные данные
None
Невозможно передать входные данные в Register-EngineEvent.
Выходные данные
None or System.Management.Automation.PSEventJob
Если вы используете параметр Action , Register-EngineEvent возвращает объект System.Management.Automation.PSEventJob . В противном случае командлет не формирует никаких выходных данных.
Примечания
События, подписки на события и очередь событий существуют только в текущем сеансе. Если закрыть текущий сеанс, очередь событий удаляется, а подписка на событие отменяется.
При подписке на событие Exiting командлеты, которые могут выполняться с помощью параметра Action , ограничены командлетами в модулях Microsoft.PowerShell.Core и Microsoft.PowerShell.Utility . Событие Exiting запускается только при выходе из сеанса под управлением PowerShell. Событие не запускается при закрытии ведущего приложения или окна терминала.
Подсистема считается простаиваемой, если на нем не выполняется конвейер. Событие OnIdle запускается, когда PowerShell простаивает в течение 300 миллисекунда (мс).
Примечание
Когда используется PSReadLine, событие OnIdle запускается при ReadKey() тайм-ауте (без ввода в 300 мс). Событие может быть показано, когда пользователь находится в середине редактирования командной строки, например, пользователь читает справку, чтобы решить, какой параметр использовать. Начиная с PSReadLine 2.2.0-beta4, поведение OnIdle изменилось, чтобы сообщить о событии только в том случае, если истекло ReadKey() время ожидания и текущий буфер редактирования пуст.