Register-ObjectEvent
Přihlásí se k odběru událostí generovaných objektem rozhraní Microsoft .NET Framework.
Syntax
Default (Výchozí)
Register-ObjectEvent
[-InputObject] <PSObject>
[-EventName] <String>
[[-SourceIdentifier] <String>]
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>]
Description
Rutina Register-ObjectEvent se přihlásí k odběru událostí generovaných objekty .NET v místním počítači nebo ve vzdáleném počítači.
Při vyvolání předplacené události je přidána do fronty událostí ve vaší relaci. K získání událostí ve frontě událostí použijte příkaz Get-Event.
Pomocí parametrů Register-ObjectEvent můžete zadat hodnoty vlastností událostí, které vám pomůžou identifikovat událost ve frontě. Pomocí parametru Action můžete také určit akce, které se mají provést při vyvolání odebírané události, a parametr Předat k odesílání vzdálených událostí do fronty událostí v místní relaci.
Když se přihlásíte k odběru události, přidá se do vaší relace odběratel události. Pokud chcete získat odběratele událostí v relaci, použijte cmdlet Get-EventSubscriber. Pokud chcete předplatné zrušit, použijte rutinu Unregister-Event, která odstraní odběratele události z relace.
Příklady
Příklad 1: Přihlášení k odběru událostí při spuštění nového procesu
Tento příklad se přihlásí k odběru událostí vygenerovaných při spuštění nového procesu.
Příkaz používá objekt ManagementEventWatcher k získání událostí eventArrived. Objekt dotazu určuje, že události jsou události vytváření instance pro Win32_Process třídy.
$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"
Příklad 2: Určení akce, která má reagovat na událost
Když zadáte akci, události, které jsou vyvolány, nejsou přidány do fronty událostí. Místo toho akce reaguje na událost. V tomto příkladu je vyvolána událost vytvoření instance označující, že je spuštěn nový proces, je vyvolána nová ProcessCreated událost.
$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
Akce používá $Sender a $EventArgs automatické proměnné, které jsou naplněny pouze pro akce událostí.
Příkaz Register-ObjectEvent vrátí objekt úlohy, který představuje akci, která se spouští jako úloha na pozadí. Ke správě úlohy na pozadí můžete použít rutiny úloh, jako jsou Get-Job a Receive-Job. Další informace naleznete v části about_Jobs.
Příklad 3: Přihlášení k odběru událostí objektů na vzdálených počítačích
Tento příklad ukazuje, jak se přihlásit k odběru událostí objektů ve vzdálených počítačích. Tento příklad používá funkci Enable-ProcessCreationEvent definovanou v souboru skriptu ProcessCreationEvent.ps1. Tento skript je k dispozici pro všechny počítače v příkladu.
# 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 }
Nejprve vytvoříme psSessions na dvou vzdálených počítačích a uložíme je do proměnné $S. Dále rutina Invoke-Command spustí skript ProcessCreationEvent.ps1 v každé z psSessions v $S. Tato akce vytvoří funkci Enable-ProcessCreationEvent ve vzdálených relacích.
Nakonec spustíme funkci Enable-ProcessCreationEvent ve vzdálených relacích.
Funkce obsahuje příkaz Register-ObjectEvent, který se přihlásí k odběru událostí vytváření instancí v objektu Win32_Process prostřednictvím objektu ManagementEventWatch er a jeho událostí EventArrived.
Příklad 4: Použití dynamického modulu v objektu PSEventJob
Tento příklad ukazuje, jak používat dynamický modul v objektu PSEventJob, který se vytvoří při zahrnutí akce do registrace události. Nejprve vytvoříme objekt časovače a povolíme ho a pak nastavíme interval časovače na 500 (milisekund). Rutina Register-ObjectEvent zaregistruje uplynulou událost objektu časovače. Objekt PSEventJob je uložen v proměnné $Job a je k dispozici také ve vlastnosti Action odběratele události. Další informace najdete v tématu Get-EventSubscriber.
Při každém uplynutí intervalu časovače se vyvolá událost a provede se akce. V tomto případě rutina Get-Random vygeneruje náhodné číslo mezi 0 a 100 a uloží ho do proměnné $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
&) vyvoláme příkaz v modulu, který zobrazí hodnotu proměnné $Random.
Další informace o modulech najdete v about_Modules.
Parametry
-Action
Určuje příkazy pro zpracování události. Příkazy v akci se spustí při vyvolání události místo odeslání události do fronty událostí. Uzavřete příkazy do složených závorek ({ } ) a vytvořte blok skriptu.
Hodnota parametru Action může zahrnovat $Event, $EventSubscriber, $Sender, $EventArgsa $Args automatických proměnných. Tyto proměnné poskytují informace o události do bloku skriptu akce. Viz about_Automatic_Variablespro více informací.
Když zadáte akci, Register-ObjectEvent vrátí objekt úlohy události, který tuto akci představuje. Ke správě úlohy události můžete použít příkazy Job cmdlet.
Vlastnosti parametru
| Typ: | ScriptBlock |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | 101 |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-EventName
Určuje událost, ke které se přihlašujete k odběru.
Hodnota tohoto parametru musí být název události, kterou objekt .NET zveřejňuje. Například třída ManagementEventWatcher má události s názvem EventArrived a Zastaveno. Pokud chcete najít název události, použijte rutinu Get-Member.
Vlastnosti parametru
| Typ: | String |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | 1 |
| Povinné: | True |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-Forward
Označuje, že rutina odesílá události pro toto předplatné do vzdálené relace. Tento parametr použijte při registraci událostí na vzdáleném počítači nebo ve vzdálené relaci.
Vlastnosti parametru
| Typ: | SwitchParameter |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-InputObject
Určuje objekt .NET, který generuje události. Zadejte proměnnou, která obsahuje objekt, nebo zadejte příkaz nebo výraz, který objekt získá.
Vlastnosti parametru
| Typ: | PSObject |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | 0 |
| Povinné: | True |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-MaxTriggerCount
Určuje maximální počet aktivací události.
Vlastnosti parametru
| Typ: | Int32 |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-MessageData
Určuje všechna další data, která se mají přidružit k tomuto odběru událostí. Hodnota tohoto parametru se zobrazí ve vlastnosti MessageData všech událostí přidružených k tomuto odběru.
Vlastnosti parametru
| Typ: | PSObject |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-SourceIdentifier
Určuje název, který vyberete pro předplatné. Název, který vyberete, musí být v aktuální relaci jedinečný. Výchozí hodnota je identifikátor GUID, který PowerShell přiřadí.
Hodnota tohoto parametru se zobrazí v hodnotě SourceIdentifier vlastnost odběratel objektu a všechny objekty události přidružené k tomuto odběru.
Vlastnosti parametru
| Typ: | String |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | 100 |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
-SupportEvent
Označuje, že cmdlet skryje odběr událostí. Tento parametr použijte, pokud je aktuální odběr součástí složitějšího mechanismu registrace událostí a neměl by být zjištěn nezávisle.
Pokud chcete zobrazit nebo zrušit předplatné vytvořené pomocí parametru supportEvent
Vlastnosti parametru
| Typ: | SwitchParameter |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | Named |
| Povinné: | False |
| Hodnota z kanálu: | False |
| Hodnota z kanálu podle názvu vlastnosti: | False |
| Hodnota ze zbývajících argumentů: | False |
CommonParameters
Tato rutina podporuje běžné parametry: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction a -WarningVariable. Další informace najdete v about_CommonParameters.
Vstupy
None
Objekty nelze pipetovat do Register-ObjectEvent.
Výstupy
None or System.Management.Automation.PSEventJob
Pokud použijete parametr Action, Register-ObjectEvent vrátí objekt System.Management.Automation.PSEventJob. Jinak nevygeneruje žádný výstup.
Poznámky
Události, odběry událostí a fronta událostí existují pouze v aktuální relaci. Pokud zavřete aktuální sezení, fronta událostí se vyprázdní a odběr události se zruší.