Register-EngineEvent

  • Referencia
Modul:
Microsoft.PowerShell.Utility

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

Syntax

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 a parancsmag által New-Event létrehozott OnIdle vagy Kilépés motoreseményekre és 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 egy PowerShell-motoreseményre regisztrál 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 Register-EngineEvent távoli munkamenetekben futtatja a parancsot. Register-EngineEvent A SourceIdentifier paraméter használatával azonosítja az eseményt. A Továbbítás paraméter azt mondja meg a motornak, 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ása 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áadva az esemény-előfizetés elrejtéséhez. 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ó könyvtárába $HOME .

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 MyEventSource forrásból. 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álható. 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 létrehozott feladatazonosító: 18. Start-Job létrehozott feladatazonosító: 19. 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-s feladatazonosí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 a , $EventSubscriber, $Sender, $EventArgsés $Args automatikus változókat is tartalmazhat$Event, amelyek információt nyújtanak az eseményről a Művelet szkriptblokkban. További információ: about_Automatic_Variables.

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

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

-Forward

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

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

-MaxTriggerCount

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

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

-MessageData

Az eseményhez társított további adatokat adja meg. Ennek a paraméternek az értéke az eseményobjektum MessageData tulajdonságában jelenik meg.

Type:PSObject
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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 az előfizető objektum SourceIdentifier tulajdonságának és az előfizetéshez társított összes eseményobjektumnak az értékében jelenik meg.

Az érték az esemény forrására jellemző. Ez tetszőleges érték lehet, amelyet a New-Event parancsmaggal való használatra hozott létre. A PowerShell-motor támogatja a P Standard kiadás ngineEvent powershell.exiting és PowerShell.OnIdle értékeit.

Type:String
Position:100
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters: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-EventSubscriberUnregister-Event parancsmagokhoz.

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

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 Művelet paraméter használatakor ez a parancsmag egy P Standard kiadás ventJob 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ési eseményre való feliratkozáskor a Művelet paraméter által végrehajtható parancsmagok a Microsoft.PowerShell.Core és a Microsoft.PowerShell.Utility modulok parancsmagjaira korlátozódnak. A kilépési esemény csak akkor aktiválódik, ha a munkamenet a PowerShell felügyelete alatt van. Az esemény nem aktiválódik a gazdaalkalmazás vagy a terminálablak bezárásakor.

A motor tétlennek minősül, ha nem futtat folyamatot. Az OnIdle esemény akkor aktiválódik, ha a PowerShell 300 ezredmásodperc (ms) tétlen volt.

Feljegyzés

Ha a PSReadLine használatban van, az OnIdle esemény akkor aktiválódik, amikor 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-beta4 verziótól kezdve az OnIdle viselkedése úgy változott, hogy csak időtúllépés esetén ReadKey() jelezzen, és az aktuális szerkesztőpuffer üres.