New-Event

创建新事件。

语法

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

说明

New-Event cmdlet 创建新的自定义事件。

你可以使用自定义事件通知用户你程序中的状态更改以及你的程序可以检测到的任何更改,包括硬件或系统状况、应用程序状态、磁盘状态、网络状态或后台作业的完成。

每次引发自定义事件时,它们都会自动添加到会话中的事件队列;你无需订阅这些事件。 但是,如果你希望将事件转发到本地会话或指定一个操作来响应该事件,请使用 Register-EngineEvent cmdlet 来订阅自定义事件。

订阅自定义事件时,会向会话中添加事件订阅服务器。 如果你使用 Unregister-Event cmdlet 取消事件订阅,则会从会话中删除事件订阅者和自定义事件。 如果不订阅自定义事件,若要删除事件,必须更改程序状况或关闭 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 cmdlet 引发一个事件来响应另一个事件。 该命令使用 Register-ObjectEvent cmdlet 来订阅创建新进程时引发的 Windows Management Instrumentation (WMI) 事件。 该命令使用该 cmdlet 的 Action 参数来调用将创建新事件的 New-Event cmdlet。

因为 New-Event 引发的事件将自动添加到 PowerShell 事件队列,因此你不需要注册该事件。

参数

-EventArguments

指定包含事件选项的对象。

类型:PSObject[]
Position:2
默认值:None
必需:False
接受管道输入:False
接受通配符:False

-MessageData

指定与事件关联的其他数据。 此参数的值显示在事件对象的 MessageData 属性中。

类型:PSObject
Position:3
默认值:None
必需:False
接受管道输入:False
接受通配符:False

-Sender

指定引发事件的对象。 默认值为 PowerShell 引擎。

类型:PSObject
Position:1
默认值:None
必需:False
接受管道输入:False
接受通配符:False

-SourceIdentifier

指定新事件的名称。 此参数是必需的,并且在会话中必须是唯一的。

此参数的值显示在事件的 SourceIdentifier 属性中。

类型:String
Position:0
默认值:None
必需:True
接受管道输入:False
接受通配符:False

输入

None

不能通过管道将对象传递给此 cmdlet。

输出

PSEventArgs

备注

Linux 或 macOS 平台上没有可用的事件源。

新自定义事件、事件订阅和事件队列仅存在于当前会话中。 如果关闭当前会话,将丢弃事件队列并取消事件订阅。