Register-WmiEvent

Подписывает на событие инструментария управления Windows (WMI).

Синтаксис

Register-WmiEvent [-Class] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-ComputerName <string>] [-Credential <PSCredential>] [-Forward] [-MessageData <psobject>] [-Namespace <string>] [-SupportEvent] [-Timeout <Int64>] [<CommonParameters>]

Register-WmiEvent [-Query] <string> [[-SourceIdentifier] <string>] [[-Action] <scriptblock>] [-ComputerName <string>] [-Credential <PSCredential>] [-Forward] [-MessageData <psobject>] [-Namespace <string>] [-SupportEvent] [-Timeout <Int64>] [<CommonParameters>]

Описание

Командлет Register-WmiEvent создает подписку на события WMI на локальном или удаленном компьютере.

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

С помощью параметров командлета Register-WmiEvent можно создавать подписки на события на удаленных компьютерах и задавать значения свойств событий, которые позволяют идентифицировать события в очереди. Также можно использовать параметр Action для задания действий, выполняемых при возникновении события, для которого создана подписка.

При создании подписки на событие в сеанс добавляется подписчик на это событие. Чтобы получить подписчики на события в сеансе, используйте командлет Get-EventSubscriber. Чтобы отменить подписку, воспользуйтесь командлетом Unregister-Event, удаляющим подписчик на событие из сеанса.

Параметры

-Action <scriptblock>

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

Значение параметра Action может включать автоматические переменные $Event, $EventSubscriber, $Sender, $SourceEventArgs и $SourceArgs, предоставляющие информацию о событии в блок скрипта Action. Дополнительные сведения см. в разделе about_Automatic_Variables.

Если задано действие, командлет Register-WmiEvent возвращает объект задания события, представляющего это действие. Для управления заданием события можно использовать командлеты, имеющие в составе существительное "Job" (командлеты Job).

Обязательно?

false

Позиция?

102

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

The event is added to the event queue.

Принимать входные данные из конвейера?

false

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

false

-Class <string>

Задает событие, для которого создается подписка. Укажите класс WMI, который создает события. В каждой команде необходимо указывать параметр Class или Query.

Обязательно?

true

Позиция?

1

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

нет

Принимать входные данные из конвейера?

false

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

false

-ComputerName <string>

Задает удаленный компьютер. По умолчанию используется значение "Локальный компьютер". Введите имя NetBIOS, IP-адрес или полное доменное имя.

Обязательно?

false

Позиция?

named

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

Local computer

Принимать входные данные из конвейера?

false

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

false

-Credential <PSCredential>

Задает учетную запись пользователя, который располагает разрешением для выполнения этого действия. Введите имя пользователя, например "User01" или "Domain01\User01". Или укажите объект PSCredential, например один из объектов, возвращенных командлетом Get-Credential. При вводе имени пользователя система запросит пароль.

Обязательно?

false

Позиция?

named

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

The credentials of the current user

Принимать входные данные из конвейера?

false

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

false

-Forward

Отправляет события по данной подписке сеансу на локальном компьютере. Этот параметр используется при регистрации для получения событий на удаленном компьютере или в удаленном сеансе.

Обязательно?

false

Позиция?

named

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

Принимать входные данные из конвейера?

false

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

false

-MessageData <psobject>

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

Обязательно?

false

Позиция?

named

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

None. The MessageData property is NULL.

Принимать входные данные из конвейера?

false

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

false

-Namespace <string>

Задает пространство имен класса WMI.

Обязательно?

false

Позиция?

named

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

нет

Принимать входные данные из конвейера?

false

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

false

-Query <string>

Задает запрос на языке запросов WMI (WQL), определяющий класс событий WMI. Пример запроса: "select * from __InstanceDeletionEvent".

Обязательно?

true

Позиция?

1

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

нет

Принимать входные данные из конвейера?

false

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

false

-SourceIdentifier <string>

Задает имя, выбранное для подписки. Выбираемое имя должно быть уникальным в пределах текущего сеанса. По умолчанию используется значение GUID, назначенное Windows PowerShell.

Значение этого параметра присваивается свойству SourceIdentifier объекта подписчика и объектов событий, связанных с данной подпиской.

Обязательно?

false

Позиция?

101

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

GUID

Принимать входные данные из конвейера?

false

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

false

-SupportEvent

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

Чтобы просмотреть или отменить подписку, созданную с использованием параметра SupportEvent, воспользуйтесь параметром Force командлетов Get-EventSubscriber и Unregister-Event.

Обязательно?

false

Позиция?

named

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

False

Принимать входные данные из конвейера?

false

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

false

-Timeout <Int64>

Определяет время ожидания оболочкой Windows PowerShell завершения выполняемой команды.

По умолчанию используется значение 0 (ноль), указывающее, что время ожидания не задано; в этом случае Windows PowerShell ожидает завершения команды бесконечно долго.

Обязательно?

false

Позиция?

named

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

0

Принимать входные данные из конвейера?

false

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

false

<CommonParameters>

Данный командлет поддерживает общие параметры -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer и -OutVariable. Дополнительные сведения см. в разделе about_Commonparameters.

Ввод и вывод

Входным типом является тип объектов, которые можно передавать командлету по конвейеру. Возвращаемым типом является тип объектов, возвращаемых командлетом.

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

Нет

Объекты невозможно передать командлету Register-WmiEvent по конвейеру.

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

Нет

Этот командлет не формирует никаких выходных данных.

Примечания

Чтобы использовать этот командлет в Windows Vista и более поздних версиях Windows, необходимо запускать Windows PowerShell командой "Запуск от имени администратора".

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

Пример 1

C:\PS>register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "ProcessStarted"

Описание
-----------
Эта команда создает подписку на события, создаваемые классом Win32_ProcessStartTrace. Этот класс создает событие при каждом запуске процесса.






Пример 2

C:\PS>register-wmiEvent -query "select * from __instancecreationevent within 5 where targetinstance isa 'win32_process'" -sourceIdentifier "WMIProcess" -messageData "Test 01" -timeout 500

Описание
-----------
В этой команде используется запрос для подписки на события создания экземпляров класса Win32_process.






Пример 3

C:\PS>$action = { get-history | where { $_.commandline -like "*start-process*" } | export-cliXml "commandHistory.clixml" }

C:\PS> register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "ProcessStarted" -action $action

Id	Name			State	HasMoreData   Location  Command
--	----			-----	-----------   --------  -------
1	 ProcessStarted  NotStarted False				 get-history | where {...

Описание
-----------
В этом примере показано, как использовать действие для реагирования на событие. В этом случае при запуске процесса все команды Start-Process текущего сеанса записываются в XML-файл. 

При использовании параметра Action командлет Register-WmiEvent возвращает фоновое задание, представляющее действие события. Для управления заданиями событий можно использовать командлеты Job, например Get-Job и Receive-Job.

Дополнительные сведения см. в разделе about_Jobs.






Пример 4

C:\PS>register-wmiEvent -class 'Win32_ProcessStartTrace' -sourceIdentifier "Start" -computername Server01 

C:\PS> get-event -sourceIdentifier "Start"

Описание
-----------
В этом примере показано, как выполнить регистрацию на получение сведений о событиях, происходящих на удаленном компьютере Server01. 

WMI передает события на локальный компьютер и сохраняет их в очереди событий в текущем сеансе. Чтобы извлечь события, выполните локальную команду Get-Event.






См. также