Register-EngineEvent
Přihlásí se k odběru událostí generovaných modulem Windows 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 Windows PowerShellu a rutinou New-Event. K určení události použijte parametr SourceIdentifier.
Tuto rutinu můžete použít k přihlášení k odběru události a událostí ukončujícího modulu vygenerovaných rutinou New-Event. Tyto události se automaticky přidají do fronty událostí ve vaší relaci bez přihlášení 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.
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 rutinu Get-Event.
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 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: Registrace události modulu PowerShellu na vzdálených počítačích
PS C:\> $S = New-PSSession -ComputerName "Server01, Server02"
PS C:\> Invoke-Command -Session $S { Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward }
Tento příkaz zaregistruje událost modulu Windows PowerShell na dvou vzdálených počítačích.
První příkaz vytvoří relaci spravovanou uživatelem (PSSession) na každém ze vzdálených počítačů.
Druhý příkaz používá rutinu Invoke-Command ke spuštění příkazu Register-EngineEvent ve vzdálených relacích.
Příkaz Register-EngineEvent používá k identifikaci události parametr SourceIdentifier. K předávání událostí ze vzdálené relace do místní relace používá parametr Forward.
Příklad 2: Provedení zadané akce při události Exiting
PS C:\> Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
Get-History | Export-Clixml $Home\history.clixml
}
Tento příkaz ukazuje, jak spustit Register-EngineEvent provést konkrétní akci, když dojde k události PowerShell.Exiting. Přidá se parametr SupportEvent pro skrytí odběru událostí. Když se Prostředí Windows PowerShell ukončí, v tomto případě se historie příkazů z ukončovací relace exportuje ve formátu XML do názvu souboru a cesty v adresáři uživatele $Home.
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, $EventArgs a $Args automatických proměnných, které poskytují informace o události bloku skriptu akce. Další informace naleznete v tématu about_Automatic_Variables (https://go.microsoft.com/fwlink/?LinkID=113212).
Při zadání akce 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 aktivačních událostí.
Hodnota parametru Action může zahrnovat $Event, $EventSubscriber, $Sender, $EventArgs a $Args automatických proměnných, které poskytují informace o události bloku skriptu akce. Další informace naleznete v tématu about_Automatic_Variables (https://go.microsoft.com/fwlink/?LinkID=113212).
Při zadání akce 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: | 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.
Podporované hodnoty EngineEvent zahrnují PowerShell.Exiting, PowerShell.OnIdle a PowerShell.OnScriptBlockInvoke.
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
Vstup do register-EngineEvent nelze.
Výstupy
None or System.Management.Automation.PSEventJob
Pokud použijete parametr action, Register-EngineEvent 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ší.