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 используется для создания подписки. Блок скрипта для параметра 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 по-прежнему выполняется и создает новые события. Мы используем командлеты задания , чтобы остановить задание и удалить ненужные объекты задания. Get-Content отображает содержимое файла журнала.

Параметры

-Action

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

Значение параметра Action может включать $Eventпеременные , $EventSubscriber$EventArgs$Senderи $Args автоматические переменные, которые предоставляют сведения о событии в блок скрипта Action. Дополнительные сведения см. в статье 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 поддерживает значения PSEngineEvent PowerShell.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

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

Выходные данные

None

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

PSEventJob

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

Примечания

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

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

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

Примечание.

При использовании PSReadLine событие OnIdle запускается при ReadKey() истечении времени ожидания (без ввода в 300 мс). Событие может быть сигналировано, когда пользователь находится в середине редактирования командной строки, например, пользователь считывает справку по выбору используемого параметра. Начиная с PSReadLine 2.2.0-beta4, поведение OnIdle изменилось, чтобы сигнализировать о событии только в том случае, если имеется время ожидания, а текущий ReadKey() буфер редактирования пуст.