Register-EngineEvent
Подписывается на события, созданные подсистемой PowerShell и командлетом New-Event .
Синтаксис
Register-EngineEvent
[-SourceIdentifier] <String>
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>] Описание
Командлет Register-EngineEvent подписывается на события, созданные подсистемой PowerShell и командлетом New-Event . Для задания события используйте параметр SourceIdentifier.
Этот командлет можно использовать для подписки на событие и события, созданные командлетом New-Event Exiting Engine. Эти события автоматически добавляются в очередь событий сеанса без оформления подписки. Однако создание подписки позволяет перенаправлять события, задавать действия для реагирования на них, а также отменять подписку.
При возникновении события, для которого создана подписка, это событие добавляется в очередь событий сеанса. Чтобы получить события в очереди событий, используйте Get-Event командлет .
При подписке на событие в сеанс добавляется подписчик события. Чтобы получить подписчиков событий в сеансе, используйте Get-EventSubscriber командлет . Чтобы отменить подписку, используйте Unregister-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 поддерживает значения EngineEventPowerShell.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 . В противном случае командлет не формирует никаких выходных данных.
Примечания
Нет источников событий, доступных на платформах Linux или macOS.
События, подписки на события и очередь событий существуют только в текущем сеансе. Если закрыть текущий сеанс, очередь событий удаляется, а подписка на событие отменяется.