Register-ObjectEvent

模組:: Microsoft.PowerShell.Utility Module

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

語法

Default (預設值)

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 }

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

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

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

此範例示範如何在事件註冊中包含 Action 時所建立 的 PSEventJob 物件中使用動態模組。首先，我們會建立並啟用定時器物件，然後將定時器的間隔設定為 500 （毫秒）。 Register-ObjectEvent Cmdlet 會註冊定時器物件的經過事件。 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 來管理事件任務。

參數屬性

類型:	ScriptBlock
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	101
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-EventName

指定您要訂閱的事件。

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

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	1
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Forward

指出 Cmdlet 會將此訂用帳戶的事件傳送至遠端會話。當您在遠端電腦或遠端會話中註冊活動時，請使用此參數。

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-InputObject

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

參數屬性

類型:	PSObject
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	0
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-MaxTriggerCount

指定可以觸發事件的最大次數。

參數屬性

類型:	Int32
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-MessageData

指定要與此事件訂閱相關聯的任何其他數據。此參數的值會出現在此訂用帳戶相關聯之所有事件的 MessageData 屬性中。

參數屬性

類型:	PSObject
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-SourceIdentifier

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

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

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	100
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-SupportEvent

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

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

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CommonParameters

此 Cmdlet 支援一般參數：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。如需詳細資訊，請參閱 about_CommonParameters。

輸入

None

您不能將物件透過管道傳送到此 Cmdlet。

輸出

None

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

PSEventJob

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

備註

事件、事件訂閱和事件佇列只存在於當前會話中。如果您關閉當前的會話，事件佇列將被丟棄，事件訂閱將被取消。

意見反應

此頁面對您有幫助嗎？

共用方式為

Register-ObjectEvent

語法

Default (預設值)

Description

範例

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

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

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

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

參數

-Action

參數屬性

參數集

-EventName

參數屬性

參數集

-Forward

參數屬性

參數集

-InputObject

參數屬性

參數集

-MaxTriggerCount

參數屬性

參數集

-MessageData

參數屬性

參數集

-SourceIdentifier

參數屬性

參數集

-SupportEvent

參數屬性

參數集

CommonParameters

輸入

None

輸出

None

PSEventJob

備註

相關連結

意見反應