Register-EngineEvent
Подписывается на события, генерируемые движком PowerShell и командлетом New-Event.
Синтаксис
Default (по умолчанию)
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 для идентификации события. Параметр Перенаправление позволяет движку перенаправить события из удаленного сеанса в локальный сеанс.
Пример 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 используется для создания подписки. Блок скрипта для параметра 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..."
$newEventSplat = @{
SourceIdentifier = 'MyEventSource'
MessageData = ("{0} - Work done..." -f (Get-Date))
}
New-Event @newEventSplat
}
}
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 создал ID задания 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 все еще выполняется и создает новые события. Мы используем командлеты задания, чтобы остановить задание и удалить ненужные объекты задания.
Get-Content отображает содержимое файла журнала.
Параметры
-Action
Задает команды для обработки событий. Команды в действии запускаются при возникновении события, вместо того чтобы отправлять событие в очередь событий. Заключите команды в фигурные скобки ({}) для создания блока скрипта.
Значение параметра действия
При указании действия Register-EngineEvent возвращает объект задания события, представляющий это действие. Командлеты Job можно использовать для управления работой события.
Свойства параметра
| Тип: | ScriptBlock |
| Default value: | None |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
(All)
| Position: | 101 |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-Forward
Указывает, что этот командлет отправляет события, связанные с подпиской, в сеанс на локальном компьютере. Используйте этот параметр при регистрации событий на удаленном компьютере или в удаленном сеансе.
Свойства параметра
| Тип: | SwitchParameter |
| Default value: | None |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-MaxTriggerCount
Указывает максимальное количество раз выполнения действия для подписки на события.
Свойства параметра
| Тип: | Int32 |
| Default value: | None |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-MessageData
Этот параметр является частью базового класса для всех событийных командлетов.
Register-EngineEvent не использует этот параметр. Все данные, передаваемые этому параметру, игнорируются.
Свойства параметра
| Тип: | PSObject |
| Default value: | None |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
(All)
| Position: | Named |
| Обязательно: | False |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-SourceIdentifier
Указывает исходный идентификатор события, к которому выполняется подписка. Идентификатор источника должен быть уникальным в текущем сеансе. Этот параметр является обязательным.
Значение этого параметра отображается в значении свойства SourceIdentifier объекта подписчика и всех объектов событий, связанных с этой подпиской.
Значение зависит от источника события. Это может быть произвольное значение, которое вы создали для использования с командлетом New-Event. Движок PowerShell поддерживает значения PSEngineEventPowerShell.Exiting и PowerShell.OnIdle.
Свойства параметра
| Тип: | String |
| Default value: | None |
| Поддерживаются подстановочные знаки: | False |
| DontShow: | False |
Наборы параметров
(All)
| Position: | 100 |
| Обязательно: | True |
| Значение из конвейера: | False |
| Значение из конвейера по имени свойства: | False |
| Значение из оставшихся аргументов: | False |
-SupportEvent
Указывает, что командлет скрывает подписку на событие. Добавьте этот параметр, если текущая подписка является частью более сложного механизма регистрации событий и не должна быть обнаружена независимо.
Чтобы просмотреть или отменить подписку, созданную с помощью параметра SupportEvent, добавьте параметр Force в командлеты Get-EventSubscriber или Unregister-Event.
Свойства параметра
| Тип: | 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.
Примечания
События, подписки на события и очередь событий существуют только в текущем сеансе. При закрытии текущего сеанса очередь событий удаляется, а подписка на события отменяется.
При подписке на событие выхода командлеты, которые могут выполняться параметром Действие, ограничены командлетами из модулей Microsoft.PowerShell.Core и Microsoft.PowerShell.Utility. Событие выхода запускается только при завершении сеанса, контролируемого PowerShell. Событие не запускается при закрытии ведущего приложения или окна терминала.
Двигатель считается неактивным, если он не запускает конвейер. Событие OnIdle запускается, когда PowerShell бездействует в течение 300 миллисекунд (мс).
Замечание
При использовании PSReadLine событие OnIdle запускается по истечении тайм-аута ReadKey(), когда нет ввода в течение 300 мс. Событие может быть сигналировано, когда пользователь находится в середине редактирования командной строки, например, пользователь считывает справку по выбору используемого параметра. Начиная с PSReadLine 2.2.0-beta4, поведение OnIdle изменилось таким образом, чтобы сигнализировать о событии только в том случае, если есть время ожидания ReadKey(), и текущий буфер редактирования пуст.
