New-Event (Microsoft.PowerShell.Utility)

New-Event

Модуль:

Microsoft.PowerShell.Utility

Создает новое событие.

Синтаксис

New-Event
   [-SourceIdentifier] <String>
   [[-Sender] <PSObject>]
   [[-EventArguments] <PSObject[]>]
   [[-MessageData] <PSObject>]
   [<CommonParameters>]

Описание

Командлет New-Event создает новое пользовательское событие.

Вы можете использовать настраиваемые события для уведомления пользователей об изменениях состояния вашей программы и любых изменениях, которые ваша программа может обнаружить, включая состояние оборудования или системы, состояние приложения, состояние диска, состояние сети или завершение фонового задания.

Пользовательские события автоматически добавляются в очередь событий вашего сеанса всякий раз, когда они возникают; вам не нужно на них подписываться. Однако если вы хотите переслать событие в локальный сеанс или указать действие в ответ на это событие, используйте командлет Register-EngineEvent, чтобы подписаться на пользовательское событие.

Когда вы подписываетесь на пользовательское событие, подписчик на событие добавляется в ваш сеанс. Если вы отмените подписку на событие с помощью командлета Unregister-Event, подписчик на событие и пользовательское событие будут удалены из сеанса. Если вы не подписаны на пользовательское событие, для его удаления необходимо изменить условия программы или закрыть сеанс PowerShell.

Примеры

Пример 1. Создайте новое событие в очереди событий.

PS C:\> New-Event -SourceIdentifier Timer -Sender windows.timer -MessageData "Test"

Эта команда создает новое событие в очереди событий PowerShell. Для отправки события он использует объект Windows.Timer.

Пример 2. Вызов события в ответ на другое событие

PS C:\> function Enable-ProcessCreationEvent
{
   $Query = New-Object System.Management.WqlEventQuery "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1), "TargetInstance isa 'Win32_Process'"
   $ProcessWatcher = New-Object System.Management.ManagementEventWatcher $Query
   $Identifier = "WMI.ProcessCreated"
   Register-ObjectEvent $ProcessWatcher "EventArrived" -SupportEvent $Identifier -Action
   {
      [void] (New-Event -SourceID "PowerShell.ProcessCreated" -Sender $Args[0] -EventArguments $Args[1].SourceEventArgs.NewEvent.TargetInstance)
   }
}

В этом примере функции используется командлет New-Event для вызова события в ответ на другое событие. Команда использует командлет Register-ObjectEvent для подписки на событие инструментария управления Windows (WMI), которое возникает при создании нового процесса. Команда использует параметр Action командлета для вызова командлета New-Event, который создает новое событие.

Поскольку события, которые вызывает New-Event, автоматически добавляются в очередь событий PowerShell, вам не нужно регистрироваться для этого события.

Параметры

-EventArguments

Указывает объект, содержащий параметры события.

Тип :

PSОбъект[]

Позиция:

2

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

None

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

False

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

False

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

False

-MessageData

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

Тип :

PSОбъект

Позиция:

3

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

None

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

False

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

False

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

False

-Sender

Указывает объект, вызывающий событие. По умолчанию используется механизм PowerShell.

Тип :

PSОбъект

Позиция:

1

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

None

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

False

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

False

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

False

-SourceIdentifier

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

Значение этого параметра отображается в свойстве SourceIdentifier событий.

Тип :

String

Позиция:

0

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

None

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

True

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

False

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

False

Входы

Нет

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

Выходы

PSEventArgs

Примечания

На платформах Linux или macOS нет источников событий.

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