Register-EngineEvent

  • Reference
Modul:
Microsoft.PowerShell.Utility

Přihlásí se k odběru událostí generovaných modulem PowerShellu a rutinou New-Event .

Syntax

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 událostí modulu OnIdle nebo Exiting Engine a událostí generovaný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.

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ř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 .

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 všech vzdálených počítačích. Rutina Invoke-Command spustí Register-EngineEvent příkaz ve vzdálených relacích. Register-EngineEventpoužívá parametr SourceIdentifier k identifikaci události. Parametr Forward říká modulu, aby předával události ze vzdálené relace do místní relace.

Příklad 2: Provedení zadané akce při ukončení události

Tento příklad ukazuje, jak spustit Register-EngineEvent 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í. Když PowerShell ukončí, v tomto případě se historie příkazů z ukončovací relace exportuje soubor XML v adresáři uživatele $HOME .

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 zdrojového 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 parametr akce 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řenou úlohu s ID 18. Start-Job vytvořenou úlohu s ID 19. V příkladu č. 4 odebereme odběr události a úlohy a pak zkontrolujeme soubor protokolu.

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 na 10 sekund, abychom umožnili několik událostí. 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...

Rutina Unregister-Event zastaví úlohu přidruženou k odběru událostí (ID úlohy 18). Id úlohy 19 je stále spuštěné a vytváří nové události. Rutiny Job zastavují úlohu a odebereme nepotřebné objekty úloh. 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 $Eventproměnné , , $Sender$EventSubscriber, $EventArgsa $Args automatické proměnné, které poskytují informace o události do bloku skriptu akce. Další informace najdete v tématu about_Automatic_Variables.

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 rutiny Úlohy.

Type:ScriptBlock
Position:101
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Forward

Označuje, že rutina odesílá události pro toto předplatné do relace v 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.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaxTriggerCount

Určuje maximální počet spuštění akce pro odběr události.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MessageData

Určuje další data přidružená k události. Hodnota tohoto parametru se zobrazí ve vlastnosti MessageData objektu události.

Type:PSObject
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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í v hodnotě SourceIdentifier vlastnost odběratel objektu a všech objektů 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 PSEngineEvent PowerShell.Exiting a PowerShell.OnIdle.

Type:String
Position:100
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-SupportEvent

Označuje, že rutina 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 do Get-EventSubscriber rutiny Unregister-Event parametr Force.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

PSEventJob

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ší.

Při přihlášení k odběru události Ukončení jsou rutiny, které lze spustit parametrem Akce , omezeny na rutiny v modulech Microsoft.PowerShell.Core a Microsoft.PowerShell.Utility . Událost Ukončení se aktivuje pouze v případě, že je relace ukončena pod kontrolou PowerShellu. Událost se neaktivuje při zavření hostitelské aplikace nebo okna terminálu.

Modul se považuje za nečinný, pokud neběží kanál. Událost OnIdle se aktivuje, když je PowerShell nečinný po dobu 300 milisekund (ms).

Poznámka:

Při použití PSReadLine se událost OnIdle aktivuje při ReadKey() vypršení časového limitu (bez zadání v 300ms). Událost může být signalizovat, když je uživatel uprostřed úprav příkazového řádku, například uživatel čte nápovědu k rozhodnutí, který parametr se má použít. Počínaje verzí PSReadLine 2.2.0-beta4 se chování OnIdle změnilo tak, aby signalizovalo událost pouze v případě, že dojde k ReadKey() vypršení časového limitu a aktuální vyrovnávací paměť pro úpravy je prázdná.