Register-EngineEvent

Modul:

Microsoft.PowerShell.Utility Module

Feliratkozik a PowerShell-motor és a New-Event parancsmag által létrehozott eseményekre.

Syntax

Default (Alapértelmezett)

Register-EngineEvent
    [-SourceIdentifier] <String>
    [[-Action] <ScriptBlock>]
    [-MessageData <PSObject>]
    [-SupportEvent]
    [-Forward]
    [-MaxTriggerCount <Int32>]
    [<CommonParameters>]

Description

A Register-EngineEvent parancsmag feliratkozik a PowerShell-motor és a New-Event parancsmag által létrehozott eseményekre. Az esemény megadásához használja a SourceIdentifier paramétert.

Ezzel a parancsmaggal feliratkozhat az OnIdle vagy az Exiting motoreseményekre, valamint a New-Event parancsmag által generált eseményekre. Ezeket az eseményeket a rendszer automatikusan hozzáadja az eseménysorhoz a munkamenetben előfizetés nélkül. Az előfizetéssel azonban továbbíthatja az eseményeket, megadhatja az eseményekre reagáló műveletet, és lemondhatja az előfizetést.

Amikor előfizet egy eseményre, a rendszer hozzáad egy esemény-előfizetőt a munkamenethez. Az esemény előfizetőinek a munkamenetben való lekéréséhez használja a Get-EventSubscriber parancsmagot. Az előfizetés lemondásához használja a Unregister-Event parancsmagot, amely törli az esemény-előfizetőt a munkamenetből.

Az előfizetett esemény létrehozásakor a rendszer hozzáadja azt az eseménysorhoz a munkamenetben. Ha eseményeket szeretne lekérni az eseménysorba, használja a Get-Event parancsmagot.

Példák

1. példa: PowerShell-motoresemény regisztrálása távoli számítógépeken

Ez a példa PowerShell-motoreseményre történő regisztrációt végez két távoli számítógépen.

$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S {
  Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward
}

New-PSSession minden távoli számítógépen létrehoz egy felhasználó által felügyelt munkamenetet (PSSession). A Invoke-Command parancsmag a távoli munkamenetekben futtatja a Register-EngineEvent parancsot. Register-EngineEvent a SourceIdentifier paramétert használja az esemény azonosításához. A Forward paraméter tájékoztatja a motort, hogy a távoli munkamenetből a helyi munkamenetbe továbbítja az eseményeket.

2. példa: Adott művelet végrehajtása a kilépési esemény bekövetkezésekor

Ez a példa bemutatja, hogyan futtathat Register-EngineEvent egy adott művelet végrehajtásához a PowerShell.Exiting esemény bekövetkezésekor.

Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
    Get-History | Export-Clixml $HOME\history.clixml
}

A SupportEvent paraméter hozzáadásra kerül az esemény-előfizetés elrejtésére. Amikor a PowerShell kilép, ebben az esetben a kilépési munkamenet parancselőzményei egy XML-fájlt exportálnak a felhasználó $HOME könyvtárába.

3. példa: Felhasználó által meghatározott esemény létrehozása és előfizetése

Ez a példa létrehoz egy előfizetést az eseményekhez a forrásból MyEventSource. Ez egy tetszőleges forrás, amelyet egy feladat előrehaladásának figyelésére fogunk használni. Register-EngineEvent az előfizetés létrehozásához használatos. A Művelet paraméter szkriptblokkja egy szövegfájlba naplózza az eseményadatokat.

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 18- os feladatazonosítót hozott létre. Start-Job létrehozta a 19-es feladat-azonosítót. A 4. példában eltávolítjuk az esemény-előfizetést és a feladatokat, majd megvizsgáljuk a naplófájlt.

4. példa: Események regisztrációja és feladatok törlése

Ez a 3. példa folytatása. Ebben a példában 10 másodpercig várunk, hogy több esemény is bekövetkezjön. Ezután megszüntetjük az esemény-előfizetés regisztrációját.

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

A Unregister-Event parancsmag leállítja az esemény-előfizetéshez társított feladatot (feladatazonosító: 18). A 19-es azonosító továbbra is fut, és új eseményeket hoz létre. A feladat parancsmagokkal állítjuk le a feladatot, és eltávolítjuk a szükségtelen feladatobjektumokat. Get-Content megjeleníti a naplófájl tartalmát.

Paraméterek

-Action

Az események kezelésére vonatkozó parancsokat adja meg. A művelet parancsai esemény létrehozásakor futnak, ahelyett, hogy az eseményt az eseménysorba küldik. A parancsokat kapcsos zárójelekbe ({}) ágyazva hozzon létre egy szkriptblokkot.

A Művelet paraméter értéke magában foglalhatja a $Event, $EventSubscriber, $Sender, $EventArgsés $Args automatikus változókat, amelyek információt nyújtanak az eseményről a Művelet szkriptblokknak. További információért tekintse meg az *about_Automatic_Variables* témakört a éscímkék alatt.

Művelet megadásakor Register-EngineEvent egy eseményfeladat-objektumot ad vissza, amely az adott műveletet jelöli. A Feladat parancsmagokkal kezelheti az eseményfeladatot.

Paramétertulajdonságok

Típus:	ScriptBlock
Alapértelmezett érték:	None
Támogatja a helyettesítő karaktereket:	False
DontShow:	False

Paraméterkészletek

(All)

Position:	101
Kötelező:	False
Folyamatból származó érték:	False
Folyamatból származó érték tulajdonságnév alapján:	False
Fennmaradó argumentumokból származó érték:	False

-Forward

Jelzi, hogy a parancsmag eseményeket küld az ezzel az előfizetéssel kapcsolatos munkamenetnek a helyi számítógépen. Ezt a paramétert akkor használja, ha távoli számítógépen vagy távoli munkamenetben regisztrál eseményekre.

Paramétertulajdonságok

Típus:	SwitchParameter
Alapértelmezett érték:	None
Támogatja a helyettesítő karaktereket:	False
DontShow:	False

Paraméterkészletek

(All)

Position:	Named
Kötelező:	False
Folyamatból származó érték:	False
Folyamatból származó érték tulajdonságnév alapján:	False
Fennmaradó argumentumokból származó érték:	False

-MaxTriggerCount

Megadja a művelet végrehajtásának maximális számát az esemény-előfizetésben.

Paramétertulajdonságok

Típus:	Int32
Alapértelmezett érték:	None
Támogatja a helyettesítő karaktereket:	False
DontShow:	False

Paraméterkészletek

(All)

Position:	Named
Kötelező:	False
Folyamatból származó érték:	False
Folyamatból származó érték tulajdonságnév alapján:	False
Fennmaradó argumentumokból származó érték:	False

-MessageData

Az eseményhez társított további adatokat adja meg. A paraméter értéke megjelenik az eseményobjektum MessageData tulajdonságában.

Paramétertulajdonságok

Típus:	PSObject
Alapértelmezett érték:	None
Támogatja a helyettesítő karaktereket:	False
DontShow:	False

Paraméterkészletek

(All)

Position:	Named
Kötelező:	False
Folyamatból származó érték:	False
Folyamatból származó érték tulajdonságnév alapján:	False
Fennmaradó argumentumokból származó érték:	False

-SourceIdentifier

Megadja annak az eseménynek a forrásazonosítóját, amelyre feliratkozik. A forrásazonosítónak egyedinek kell lennie az aktuális munkamenetben. Ez a paraméter kötelező.

Ennek a paraméternek az értéke megjelenik az előfizető objektum SourceIdentifier tulajdonságának és az előfizetéshez társított összes eseményobjektumnak az értékében.

Az érték az esemény forrására jellemző. Ez lehet egy tetszőleges érték, amelyet a New-Event parancsmaggal való használatra hozott létre. A PowerShell motor támogatja a PSEngineEvent értékeket PowerShell.Exiting és PowerShell.OnIdle.

Paramétertulajdonságok

Típus:	String
Alapértelmezett érték:	None
Támogatja a helyettesítő karaktereket:	False
DontShow:	False

Paraméterkészletek

(All)

Position:	100
Kötelező:	True
Folyamatból származó érték:	False
Folyamatból származó érték tulajdonságnév alapján:	False
Fennmaradó argumentumokból származó érték:	False

-SupportEvent

Azt jelzi, hogy a parancsmag elrejti az esemény-előfizetést. Adja hozzá ezt a paramétert, ha az aktuális előfizetés egy összetettebb eseményregisztrációs mechanizmus része, és nem szabad egymástól függetlenül felderíteni.

A SupportEvent paraméterrel létrehozott előfizetés megtekintéséhez vagy lemondásához adja hozzá a Force paramétert a Get-EventSubscriber vagy Unregister-Event parancsmagokhoz.

Paramétertulajdonságok

Típus:	SwitchParameter
Alapértelmezett érték:	None
Támogatja a helyettesítő karaktereket:	False
DontShow:	False

Paraméterkészletek

(All)

Position:	Named
Kötelező:	False
Folyamatból származó érték:	False
Folyamatból származó érték tulajdonságnév alapján:	False
Fennmaradó argumentumokból származó érték:	False

CommonParameters

Ez a parancsmag a következő gyakori paramétereket támogatja: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction és -WarningVariable. További információért lásd about_CommonParameters.

Bevitelek

None

Ehhez a parancsmaghoz nem lehet objektumokat csövezni.

Kimenetek

None

Ez a parancsmag alapértelmezés szerint nem ad vissza kimenetet.

PSEventJob

A Action paraméter használatakor ez a parancsmag egy PSEventJob objektumot ad vissza.

Jegyzetek

Az események, az esemény-előfizetések és az eseménysor csak az aktuális munkamenetben léteznek. Ha bezárja az aktuális munkamenetet, a rendszer elveti az eseménysort, és megszakítja az esemény-előfizetést.

A Kilépés eseményre való feliratkozáskor az Action paraméter által végrehajtható parancsmagok a Microsoft.PowerShell.Core és Microsoft.PowerShell.Utility modulok parancsmagjaira korlátozódnak. A Kilépés esemény csak akkor aktiválódik, ha a munkamenet a PowerShell által kerül befejezésre. Az esemény nem aktiválódik a gazdaalkalmazás vagy a terminálablak bezárásakor.

A motor üresjáratban van, ha nem futtat csővezetéket. Az OnIdle esemény akkor aktiválódik, ha a PowerShell 300 ezredmásodperc (ms) tétlen volt.

Megjegyzés:

Ha a PSReadLine használatban van, a OnIdle esemény akkor aktiválódik, ha ReadKey() túllépi az időkorlátot (nincs gépelés 300 ms-ben). Az esemény jelezhető, miközben a felhasználó a parancssor szerkesztésének közepén van, például a felhasználó súgót olvas a használni kívánt paraméter kiválasztásához. A PSReadLine 2.2.0-béta4-től kezdődően OnIdle viselkedése csak akkor változott az esemény jelzésére, ha ReadKey() időtúllépés történt, és az aktuális szerkesztőpuffer üres.

Kapcsolódó hivatkozások

• Get-Event
• Új-Esemény
• Register-ObjectEvent
• Esemény eltávolítása
• Esemény-regisztráció törlése
• Várakozási esemény