Register-EngineEvent
Přihlásí se k odběru událostí generovaných modulem PowerShellu a rutinou New-Event.
Syntax
Default (Výchozí)
Register-EngineEvent
[-SourceIdentifier] <String>
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>]
Description
Rutina Register-EngineEvent se přihlásí k odběru událostí generovaných modulem PowerShellu a rutinou New-Event. K určení události použijte parametr SourceIdentifier.
Pomocí této rutiny se můžete přihlásit k odběru OnIdle nebo Ukončení událostí modulu a událostí generovaných rutinou New-Event. Tyto události se automaticky přidají do fronty událostí vaší relace, aniž by bylo nutné se přihlásit k odběru. Přihlášení k odběru vám ale umožní přeposlat události, zadat akci, která bude reagovat na události, a zrušit odběr.
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ř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.
Příklady
Příklad 1: Registrace události modulu PowerShellu na vzdálených počítačích
Tento příklad zaregistruje událost modulu PowerShellu na dvou vzdálených počítačích.
$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S {
Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward
}
New-PSSession vytvoří relaci spravovanou uživatelem (PSSession) na každém ze vzdálených počítačů. Rutina Invoke-Command spustí příkaz Register-EngineEvent ve vzdálených relacích.
Register-EngineEvent k identifikaci události používá parametr SourceIdentifier. Parametr Forward nastavuje motor tak, aby předával události ze vzdálené relace do místní relace.
Příklad 2: Provedení zadané akce při události Exiting
Tento příklad ukazuje, jak spustit Register-EngineEvent a provést konkrétní akci, když dojde k události PowerShell.Exiting.
Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
Get-History | Export-Clixml $HOME\history.clixml
}
Přidá se parametr SupportEvent pro skrytí odběru událostí. Při ukončení PowerShellu se v tomto případě historie příkazů z ukončovací relace exportuje soubor XML do $HOME adresáře uživatele.
Příklad 3: Vytvoření a přihlášení k odběru uživatelem definované události
Tento příklad vytvoří odběr událostí ze zdroje MyEventSource. Jedná se o libovolný zdroj, který použijeme ke sledování průběhu úlohy.
Register-EngineEvent slouží k vytvoření předplatného. Blok skriptu pro Action parametr protokoluje data události do textového souboru.
Register-EngineEvent -SourceIdentifier MyEventSource -Action {
"Event: {0}" -f $event.messagedata | Out-File c:\temp\MyEvents.txt -Append
}
Start-Job -Name TestJob -ScriptBlock {
While ($True) {
Register-EngineEvent -SourceIdentifier MyEventSource -Forward
Start-Sleep -seconds 2
"Doing some work..."
New-Event -SourceIdentifier MyEventSource -Message ("{0} - Work done..." -f (Get-Date))
}
}
Start-Sleep -seconds 4
Get-EventSubscriber
Get-Job
SubscriptionId : 12
SourceObject :
EventName :
SourceIdentifier : MyEventSource
Action : System.Management.Automation.PSEventJob
HandlerDelegate :
SupportEvent : False
ForwardEvent : False
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
18 MyEventSource Running True …
19 TestJob BackgroundJob Running True localhost …
Register-EngineEvent vytvořil úlohu s ID 18.
Start-Job vytvořilo ID úlohy 19. V příkladu č. 4 odebereme odběr události a úlohy, a poté zkontrolujeme protokolový soubor.
Příklad 4: Zrušení registrace událostí a vyčištění úloh
Jedná se o pokračování příkladu 3. V tomto příkladu počkáme 10 sekund, aby mohlo dojít k několika událostem. Pak zrušíme registraci odběru událostí.
PS> Start-Sleep -seconds 10
PS> Get-EventSubscriber | Unregister-Event
PS> Get-Job
Id Name PSJobTypeName State HasMoreData Location Command
-- ---- ------------- ----- ----------- -------- -------
18 MyEventSource Stopped False …
19 TestJob BackgroundJob Running True localhost …
PS> Stop-Job -Id 19
PS> Get-Job | Remove-Job
PS> Get-Content C:\temp\MyEvents.txt
Event: 2/18/2020 2:36:19 PM - Work done...
Event: 2/18/2020 2:36:21 PM - Work done...
Event: 2/18/2020 2:36:23 PM - Work done...
Event: 2/18/2020 2:36:25 PM - Work done...
Event: 2/18/2020 2:36:27 PM - Work done...
Event: 2/18/2020 2:36:29 PM - Work done...
Event: 2/18/2020 2:36:31 PM - Work done...
Cmdlet Unregister-Event zastaví úlohu spojenou s odběrem událostí (ID úlohy 18). Id úlohy 19 je stále spuštěné a vytváří nové události. Používáme rutiny Job k zastavení úlohy a odstranění nepotřebných objektů úlohy.
Get-Content zobrazí obsah souboru protokolu.
Parametry
-Action
Určuje příkazy pro zpracování událostí. 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é proměnné, které poskytují informace o události do bloku skriptu Akce. Viz about_Automatic_Variablespro více informací.
Když zadáte akci, Register-EngineEvent 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 |
-Forward
Označuje, že cmdlet odesílá události týkající se tohoto předplatného do relace na místním počítači. 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 |
-MaxTriggerCount
Určuje maximální počet, kolikrát je akce provedena pro odběr 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 další data přidružená k události. Hodnota tohoto parametru se zobrazí ve vlastnosti MessageData objektu události.
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 identifikátor zdroje události, ke které se přihlašujete k odběru. Identifikátor zdroje musí být v aktuální relaci jedinečný. Tento parametr je povinný.
Hodnota tohoto parametru se zobrazí ve vlastnosti SourceIdentifier objektu odběratele a ve všech objektech událostí přidružených k tomuto odběru.
Hodnota je specifická pro zdroj události. Může to být libovolná hodnota, kterou jste vytvořili pro použití s rutinou New-Event. Modul PowerShellu podporuje hodnoty PSEngineEventPowerShell.Exiting a PowerShell.OnIdle.
Vlastnosti parametru
| Typ: | String |
| Default value: | None |
| Podporuje zástupné znaky: | False |
| DontShow: | False |
Sady parametrů
(All)
| Position: | 100 |
| Povinné: | True |
| 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 přidejte, 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, přidejte parametr Force do rutin Get-EventSubscriber nebo Unregister-Event.
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
Do tohoto cmdletu nemůžete předávat objekty.
Výstupy
None
Ve výchozím nastavení tato rutina nevrací žádný výstup.
PSEventJob
Pokud použijete parametr
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ší.
Při přihlášení k odběru události Ukončení jsou rutiny, které lze spustit parametrem Action, omezeny na rutiny z modulů Microsoft.PowerShell.Core a Microsoft.PowerShell.Utility. Událost Ukončení se aktivuje pouze tehdy, když je relace ukončena pod kontrolou PowerShell. Událost se neaktivuje při zavření hostitelské aplikace nebo okna terminálu.
Motor se považuje za nečinný, pokud neběží potrubí. Událost OnIdle se aktivuje, když je PowerShell nečinný po dobu 300 milisekund (ms).
Poznámka:
V případě, že se používá PSReadLine, se událost OnIdle aktivuje při vypršení časového limitu ReadKey() (bez zadávání po dobu 300 ms). Událost může být signalizována, když je uživatel uprostřed úprav příkazového řádku, například, když uživatel čte nápovědu, aby se rozhodl, který parametr se má použít. Počínaje verzí PSReadLine 2.2.0-beta4 se OnIdle chování změnilo tak, aby signalizovalo událost pouze v případě, že došlo k vypršení časového limitu ReadKey() a aktuální vyrovnávací paměť pro úpravy je prázdná.