Register-ObjectEvent

模組:

Microsoft.PowerShell.Utility

訂閱 Microsoft .NET Framework 物件所產生的事件。

Syntax

Register-ObjectEvent
        [-InputObject] <PSObject>
        [-EventName] <String>
        [[-SourceIdentifier] <String>]
        [[-Action] <ScriptBlock>]
        [-MessageData <PSObject>]
        [-SupportEvent]
        [-Forward]
        [-MaxTriggerCount <Int32>]
        [<CommonParameters>]

Description

Register-ObjectEvent Cmdlet 會訂閱本機電腦或遠端電腦上 .NET 物件所產生的事件。

當訂閱的事件被引發時，它會被新增到您工作階段的事件佇列中。 若要取得事件佇列中的事件，請使用 Get-Event Cmdlet。

您可以使用 的參數 Register-ObjectEvent 來指定事件的屬性值，以協助您識別佇列中的事件。 您也可以使用 Action 參數來指定引發訂閱事件時要採取的動作，並使用 Forward 參數將遠端事件傳送至本機會話中的事件佇列。

當您訂閱某個事件時，會將事件訂閱者新增到您的工作階段中。 若要取得會話中的事件訂閱者，請使用 Get-EventSubscriber Cmdlet。 若要取消訂閱，請使用 Unregister-Event Cmdlet，從會話中刪除事件訂閱者。

範例

範例 1：訂閱新進程啟動時的事件

這個範例會訂閱在新處理程序啟動時產生的事件。

此命令會使用 ManagementEventWatcher 物件來取得 EventArrived 事件。 查詢物件會指定事件是 Win32_Process 類別的實例建立事件。

$queryParameters = '__InstanceCreationEvent', (New-Object TimeSpan 0,0,1),
    "TargetInstance isa 'Win32_Process'"
$Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters
$ProcessWatcher = New-Object System.Management.ManagementEventWatcher $Query
Register-ObjectEvent -InputObject $ProcessWatcher -EventName "EventArrived"

範例 2：指定要回應事件的動作

指定動作時，並不會將被引發的事件新增到事件佇列。 取而代之的是，此動作會回應事件。 在此範例中，當引發實例建立事件，指出已啟動新的進程時，就會引發新的 ProcessCreated 事件。

$queryParameters = '__InstanceCreationEvent', (New-Object TimeSpan 0,0,1),
    "TargetInstance isa 'Win32_Process'"
$Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters
$ProcessWatcher = New-Object System.Management.ManagementEventWatcher $query
$newEventArgs = @{
    SourceIdentifier = 'PowerShell.ProcessCreated'
    Sender = $Sender
    EventArguments = $EventArgs.NewEvent.TargetInstance
}
$Action = { New-Event @newEventArgs }
Register-ObjectEvent -InputObject $ProcessWatcher -EventName "EventArrived" -Action $Action

Id   Name               PSJobTypeName   State       HasMoreData   Location   Command
--   ----               -------------   -----       -----------   --------   -------
 5   3db2d67a-efff-...                 NotStarted   False                    New-Event @newEventArgs

動作會使用 $Sender 和 $EventArgs 自動變數，這些變數只會針對事件動作填入。

Register-ObjectEvent此命令會傳回工作物件，代表做為背景作業執行的動作。 您可以使用作業 Cmdlet，例如 Get-Job 和 Receive-Job來管理背景工作。 如需詳細資訊，請參閱 about_Jobs。

範例 3：訂閱遠端電腦上的物件事件

這個範例示範如何訂閱遠端電腦上的物件事件。 這個範例會 Enable-ProcessCreationEvent 使用腳本檔案中 ProcessCreationEvent.ps1 定義的函式。 此文稿可供範例中的所有計算機使用。

# ProcessCreationEvent.ps1
function  Enable-ProcessCreationEvent {
    $queryParameters = "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1),
        "TargetInstance isa 'Win32_Process'"
    $Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters

    $objectEventArgs = @{
        Input = New-Object System.Management.ManagementEventWatcher $Query
        EventName = 'EventArrived'
        SourceIdentifier = 'WMI.ProcessCreated'
        MessageData = 'Test'
        Forward = $True
    }
    Register-ObjectEvent @objectEventArgs
}

$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S -FilePath ProcessCreationEvent.ps1
Invoke-Command -Session $S { Enable-ProcessCreationEvent }

第一個我們會在兩部遠端計算機上建立 PSSession， 並將其儲存在變數中 $S 。 接下來，Invoke-CommandCmdlet 會在 中的每個 PSSessions $S中執行ProcessCreationEvent.ps1腳本。 此動作會在 Enable-ProcessCreationEvent 遠端會話中建立 函式。 最後，我們會在遠程會話中執行 Enable-ProcessCreationEvent 函式。

函式包含一個Register-ObjectEvent命令，可透過ManagementEventWatcher物件及其EventArrived事件訂閱Win32_Process物件上的實例建立事件。

範例 4：在 PSEventJob 物件中使用動態模組

此範例示範如何在事件註冊中包含 Action 時所建立的 PSEventJob 物件中使用動態模組。 首先，我們會建立並啟用定時器對象，然後將定時器的間隔設定為 500 (毫秒) 。 Cmdlet Register-ObjectEvent 會註冊定時器物件的 Elapsed 事件。 PSEventJob 物件會儲存在 變數中$Job，也可以在事件訂閱者的 Action 屬性中使用。 如需詳細資訊，請參閱 Get-EventSubscriber。

每當定時器間隔經過時，就會引發事件並執行動作。 在此情況下， Get-Random Cmdlet 會產生介於 0 到 100 之間的隨機數位，並將它儲存在 變數中 $Random 。

$Timer = New-Object Timers.Timer
$Timer.Interval = 500
$Timer.Enabled = $True
$objectEventArgs = @{
    InputObject = $Timer
    EventName = 'Elapsed'
    SourceIdentifier = 'Timer.Random'
    Action = {$Random = Get-Random -Min 0 -Max 100}
}
$Job = Register-ObjectEvent @objectEventArgs
$Job | Format-List -Property *
& $Job.module {$Random}
& $Job.module {$Random}

State         : Running
Module        : __DynamicModule_53113769-31f2-42dc-830b-8749325e28d6
StatusMessage :
HasMoreData   : True
Location      :
Command       : $Random = Get-Random -Min 0 -Max 100
JobStateInfo  : Running
Finished      : System.Threading.ManualResetEvent
InstanceId    : 47b5ec9f-bfe3-4605-860a-4674e5d44ca8
Id            : 7
Name          : Timer.Random
ChildJobs     : {}
PSBeginTime   : 6/27/2019 10:19:06 AM
PSEndTime     :
PSJobTypeName :
Output        : {}
Error         : {}
Progress      : {}
Verbose       : {}
Debug         : {}
Warning       : {}
Information   : {}
60
47

PSEventJob 具有Module屬性，其中包含實作動作的動態腳本模組。 使用呼叫運算子 (&) ，我們會叫用模組中的 命令來顯示變數的值 $Random 。

如需模組的詳細資訊，請參閱 about_Modules。

參數

-Action

指定要處理事件的命令。 當事件被引發時，將會執行 Action 中的命令，而不會將事件傳送到事件佇列。 使用大括弧 ( { } ) 括住命令以建立指令碼區塊。

Action 參數的值可以包含 $Event、$EventSubscriber、$Sender、 $EventArgs和 $Args 自動變數。 這些變數會將事件的相關信息提供給 Action 腳本區塊。 如需詳細資訊，請參閱 about_Automatic_Variables。

當您指定動作時， Register-ObjectEvent 會傳回代表該動作的事件作業物件。 您可以使用各種 Job Cmdlet 來管理事件工作。

Type:	ScriptBlock
Position:	101
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-EventName

指定您要訂閱的事件。

此參數的值必須是 .NET 對象公開的事件名稱。 例如， ManagementEventWatcher 類別具有名為 EventArrived 和 Stopped 的事件。 若要尋找事件的事件名稱，請使用 Get-Member Cmdlet。

Type:	String
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Forward

指出 Cmdlet 會將此訂用帳戶的事件傳送至遠端會話。 當您要訂閱遠端電腦上或遠端工作階段中的事件時，請使用此參數。

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InputObject

指定產生事件的 .NET 物件。 輸入包含物件的變數，或輸入可取得物件的命令或運算式。

Type:	PSObject
Position:	0
Default value:	None
Required:	True
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

指定您為訂閱選取的名稱。 您所選取的名稱在目前的工作階段中必須是唯一的。 預設值是 PowerShell 指派的 GUID。

此參數的值會出現在訂閱者物件的 SourceIdentifier 屬性值，以及與此訂閱相關聯的所有事件物件中。

Type:	String
Position:	100
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SupportEvent

表示此 Cmdlet 會隱藏事件訂閱。 當目前的訂用帳戶是較複雜事件註冊機制的一部分，且不應獨立探索時，請使用此參數。

若要檢視或取消使用 SupportEvent 參數建立的訂用帳戶，請使用 和 Unregister-Event Cmdlet 的 Get-EventSubscriberForce 參數。

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

輸入

None

您無法使用管線會傳送至 Register-ObjectEvent。

輸出

None or System.Management.Automation.PSEventJob

當您使用 Action 參數時， Register-ObjectEvent 會傳回 System.Management.Automation.PSEventJob 物件。 否則，它不會產生任何輸出。

備註

事件、事件訂閱與事件佇列僅存在目前工作階段中。 若關閉目前工作階段，便會捨棄事件佇列，並取消事件訂閱。

相關連結

• Get-Event
• New-Event
• Register-EngineEvent
• Remove-Event
• Unregister-Event
• Wait-Event