Register-ObjectEvent

Syntax

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

Description

Cmdlet Register-ObjectEvent 會訂閱本機電腦或遠端電腦上 .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

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

輸入

None

您無法使用管線將物件傳送至此 Cmdlet。

輸出

None

根據預設，此 Cmdlet 不會傳回任何輸出。

PSEventJob

當您使用 Action 參數時，這個 Cmdlet 會 傳回 PSEventJob 物件。

備註

事件、事件訂閱和事件佇列只存在於目前的會話中。 如果您關閉目前的會話，則會捨棄事件佇列，並取消事件訂閱。

相關連結

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