Register-ObjectEvent
訂閱Microsoft .NET Framework 物件所產生的事件。
語法
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-Command
Cmdlet 會在 中的每個 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 參數的值可以包含 $Event
、$EventSubscriber
、$Sender
、 $EventArgs
和 $Args
自動變數。 這些變數會將事件 的相關信息提供給 Action 腳本區塊。 如需詳細資訊,請參閱 about_Automatic_Variables。
當您指定動作時, Register-ObjectEvent
會傳回代表該動作的事件作業物件。 您可以使用作業 Cmdlet 來管理事件作業。
類型: | ScriptBlock |
Position: | 101 |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-EventName
指定您要訂閱的事件。
此參數的值必須是 .NET 對象公開的事件名稱。 例如,ManagementEventWatcher 類別具有名為 EventArrived 和 Stopped 的事件。 若要尋找事件的事件名稱,請使用 Get-Member
Cmdlet。
類型: | String |
Position: | 1 |
預設值: | None |
必要: | True |
接受管線輸入: | False |
接受萬用字元: | False |
-Forward
指出 Cmdlet 會將此訂用帳戶的事件傳送至遠端會話。 當您在遠端電腦或遠端工作階段中註冊事件時,請使用此參數。
類型: | SwitchParameter |
Position: | Named |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-InputObject
指定產生事件的 .NET 物件。 輸入包含 物件的變數,或輸入取得物件的命令或表達式。
類型: | PSObject |
Position: | 0 |
預設值: | None |
必要: | True |
接受管線輸入: | False |
接受萬用字元: | False |
-MaxTriggerCount
指定可以觸發事件的最大次數。
類型: | Int32 |
Position: | Named |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-MessageData
指定要與此事件訂閱相關聯的任何其他數據。 此參數的值會出現在此訂用帳戶相關聯之所有事件的 MessageData 屬性中。
類型: | PSObject |
Position: | Named |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-SourceIdentifier
指定您為訂用帳戶選取的名稱。 您選取的名稱在目前工作階段中必須是唯一的。 預設值是 PowerShell 指派的 GUID。
此參數的值會出現在 訂閱者物件的SourceIdentifier 屬性值,以及與此訂閱相關聯的所有事件物件中。
類型: | String |
Position: | 100 |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-SupportEvent
指出 Cmdlet 會隱藏事件訂閱。 當目前的訂用帳戶是更複雜的事件註冊機制的一部分,且不應該獨立探索時,請使用此參數。
若要檢視或取消以 SupportEvent 參數建立的訂用帳戶,請使用 和 Unregister-Event
Cmdlet 的 Get-EventSubscriber
Force 參數。
類型: | SwitchParameter |
Position: | Named |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
輸入
None
您無法使用管線將物件傳送至此 Cmdlet。
輸出
None
根據預設,此 Cmdlet 不會傳回任何輸出。
當您使用 Action 參數時,這個 Cmdlet 會 傳回 PSEventJob 物件。
備註
事件、事件訂閱和事件佇列只存在於目前的會話中。 如果您關閉目前的會話,則會捨棄事件佇列,並取消事件訂閱。