Register-ObjectEvent
Přihlásí se k odběru událostí generovaných objektem rozhraní Microsoft .NET Framework.
Syntaxe
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í odebírané události se přidá do fronty událostí ve vaší relaci. K získání událostí ve frontě událostí použijte rutinu Get-Event
.
Parametry můžete použít Register-ObjectEvent
k určení hodnot vlastností událostí, které vám pomůžou identifikovat událost ve frontě. Pomocí parametru Akce můžete také určit akce, které se mají provést při vyvolání odebírané události, a předat parametr pro 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 tuto rutinu 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á událost 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
Akce používá $Sender
automatické $EventArgs
proměnné, které jsou naplněny pouze pro akce událostí.
Příkaz Register-ObjectEvent
vrátí objekt úlohy, který představuje akci, která běží jako úloha na pozadí. Ke správě úlohy na pozadí můžete použít rutiny Úlohy, například Get-Job
a Receive-Job
. Další informace najdete v tématu Informace o úlohách.
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á Enable-ProcessCreationEvent
funkci definovanou ProcessCreationEvent.ps1
v souboru skriptu. 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 }
První vytvoříme psSessions na dvou vzdálených počítačích a uložíme je do $S
proměnné. Dále rutina Invoke-Command
spustí ProcessCreationEvent.ps1
skript v každé psSessions in $S
. Tato akce vytvoří Enable-ProcessCreationEvent
funkci ve vzdálených relacích.
Nakonec funkci spustíme Enable-ProcessCreationEvent
ve vzdálených relacích.
Funkce obsahuje Register-ObjectEvent
příkaz, který se přihlásí k odběru událostí vytváření instancí na objektu Win32_Process prostřednictvím objektu ManagementEventWatcher a události 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ý je vytvořen 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 událost Uplynulé události objektu časovače. Objekt PSEventJob je uložen v $Job
proměnné a je také k dispozici ve vlastnosti Action odběratel 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ě Get-Random
rutina vygeneruje náhodné číslo od 0 do 100 a uloží ho $Random
do proměnné.
$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 má vlastnost Modulu, která obsahuje modul dynamického skriptu, který implementuje akci. Pomocí operátoru volání (&
) vyvoláme příkaz v modulu, který zobrazí hodnotu $Random
proměnné.
Další informace o modulech najdete v tématu 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
proměnné , $EventSubscriber
, $Sender
, $EventArgs
a $Args
automatické proměnné. Tyto proměnné poskytují informace o události do bloku skriptu akce . Další informace najdete v tématu about_Automatic_Variables.
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 rutiny Úlohy.
Typ: | ScriptBlock |
Position: | 101 |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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 ManagementEventWatcher třída obsahuje události s názvem EventArrived a Zastaveno. K vyhledání názvu události použijte rutinu Get-Member
.
Typ: | String |
Position: | 1 |
Default value: | None |
Vyžadováno: | True |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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.
Typ: | SwitchParameter |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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á.
Typ: | PSObject |
Position: | 0 |
Default value: | None |
Vyžadováno: | True |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | False |
-MaxTriggerCount
Určuje maximální počet aktivací události.
Typ: | Int32 |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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.
Typ: | PSObject |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | 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álostí přidružené k tomuto odběru.
Typ: | String |
Position: | 100 |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | False |
-SupportEvent
Označuje, že rutina 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 , použijte parametr Force pro rutiny Get-EventSubscriber
a Unregister-Event
rutiny.
Typ: | SwitchParameter |
Position: | Named |
Default value: | None |
Vyžadováno: | False |
Přijmout vstup kanálu: | False |
Přijmout zástupné znaky: | False |
Vstupy
None
Do této rutiny nemůžete roušit objekty.
Výstupy
None
Ve výchozím nastavení tato rutina nevrací žádný výstup.
Pokud použijete parametr Action , tato rutina vrátí objekt PSEventJob .
Poznámky
Události, odběry událostí a fronta událostí existují pouze v aktuální relaci. Pokud zavřete aktuální relaci, fronta událostí se zahodí a odběr události se zruší.