Delen via

Register-EngineEvent

  • Referentie
Module:
Microsoft.PowerShell.Utility

Abonneert u op gebeurtenissen die worden gegenereerd door de PowerShell-engine en door de New-Event cmdlet.

Syntax

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

Description

De Register-EngineEvent cmdlet abonneert zich op gebeurtenissen die worden gegenereerd door de PowerShell-engine en de New-Event cmdlet. Gebruik de parameter SourceIdentifier om de gebeurtenis op te geven.

U kunt deze cmdlet gebruiken om u te abonneren op de onidle of afsluitende engine-gebeurtenissen en gebeurtenissen die door de New-Event cmdlet worden gegenereerd. Deze gebeurtenissen worden automatisch toegevoegd aan de gebeurteniswachtrij in uw sessie zonder zich te abonneren. Met abonneren kunt u echter de gebeurtenissen doorsturen, een actie opgeven om op de gebeurtenissen te reageren en het abonnement annuleren.

Wanneer u zich abonneert op een gebeurtenis, wordt een gebeurtenisabonnee toegevoegd aan uw sessie. Gebruik Get-EventSubscriber de cmdlet om de gebeurtenisabonnees in de sessie op te halen. Als u het abonnement wilt annuleren, gebruikt u de Unregister-Event cmdlet, waarmee de gebeurtenisabonnee uit de sessie wordt verwijderd.

Wanneer de geabonneerde gebeurtenis wordt gegenereerd, wordt deze toegevoegd aan de gebeurteniswachtrij in uw sessie. Gebruik Get-Event de cmdlet om gebeurtenissen in de gebeurteniswachtrij op te halen.

Voorbeelden

Voorbeeld 1: Een PowerShell-engine-gebeurtenis registreren op externe computers

In dit voorbeeld wordt geregistreerd voor een PowerShell-engine-gebeurtenis op twee externe computers.

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

New-PSSession maakt een door de gebruiker beheerde sessie (PSSession) op elk van de externe computers. De Invoke-Command cmdlet voert de Register-EngineEvent opdracht uit in de externe sessies. Register-EngineEvent gebruikt de parameter SourceIdentifier om de gebeurtenis te identificeren. De parameter Forward vertelt de engine om de gebeurtenissen van de externe sessie door te sturen naar de lokale sessie.

Voorbeeld 2: Een opgegeven actie uitvoeren wanneer de gebeurtenis Afsluiten plaatsvindt

In dit voorbeeld ziet u hoe u Register-EngineEvent uitvoert om een specifieke actie uit te voeren wanneer de gebeurtenis PowerShell.Exiting plaatsvindt.

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

De parameter SupportEvent wordt toegevoegd om het gebeurtenisabonnement te verbergen. Wanneer PowerShell wordt afgesloten, wordt in dit geval de opdrachtgeschiedenis van de afsluitende sessie geëxporteerd naar een XML-bestand in de map van $Home de gebruiker.

Voorbeeld 3: Creatie en abonneren op een door de gebruiker gedefinieerde gebeurtenis

In dit voorbeeld wordt een abonnement gemaakt voor gebeurtenissen uit de bron MyEventSource. Dit is een willekeurige bron die we gaan gebruiken om de voortgang van een taak te controleren. Register-EngineEvent wordt gebruikt om het abonnement te maken. Het scriptblok voor de parameter Action registreert de gebeurtenisgegevens in een tekstbestand.

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 taak-id 18 gemaakt. Start-Job taak-id 19 gemaakt. In voorbeeld 4 verwijderen we het gebeurtenisabonnement en de taken en inspecteren we vervolgens het logboekbestand.

Voorbeeld 4: Registratie van gebeurtenissen ongedaan maken en taken opschonen

Dit is een vervolg op voorbeeld 3. In dit voorbeeld wachten we 10 seconden om verschillende gebeurtenissen te laten plaatsvinden. Vervolgens maken we de registratie van het gebeurtenisabonnement ongedaan.

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

De Unregister-Event cmdlet stopt de taak die is gekoppeld aan het gebeurtenisabonnement (taak-id 18). Taak-id 19 wordt nog steeds uitgevoerd en er worden nieuwe gebeurtenissen gemaakt. We gebruiken de taak-cmdlets om de taak te stoppen en de overbodige taakobjecten te verwijderen. Get-Content geeft de inhoud van het logboekbestand weer.

Parameters

-Action

Hiermee geeft u opdrachten voor het verwerken van de gebeurtenissen. De opdrachten in de actie worden uitgevoerd wanneer een gebeurtenis wordt gegenereerd, in plaats van de gebeurtenis naar de gebeurteniswachtrij te verzenden. Plaats de opdrachten tussen accolades ({}) om een scriptblok te maken.

De waarde van de parameter Action kan de $Eventautomatische variabelen , $EventSubscriber, $Sender, $EventArgsen $Args bevatten, die informatie over de gebeurtenis bieden aan het scriptblok Actie . Zie about_Automatic_Variables voor meer informatie.

Wanneer u een actie opgeeft, Register-EngineEvent wordt een gebeurtenistaakobject geretourneerd dat deze actie vertegenwoordigt. U kunt de taak-cmdlets gebruiken om de gebeurtenistaak te beheren.

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

-Forward

Geeft aan dat de cmdlet gebeurtenissen voor dit abonnement verzendt naar de sessie op de lokale computer. Gebruik deze parameter wanneer u zich registreert voor gebeurtenissen op een externe computer of in een externe sessie.

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

-MaxTriggerCount

Hiermee geeft u het maximum aantal keren op dat de actie wordt uitgevoerd voor het gebeurtenisabonnement.

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

-MessageData

Hiermee geeft u aanvullende gegevens op die zijn gekoppeld aan de gebeurtenis. De waarde van deze parameter wordt weergegeven in de eigenschap MessageData van het gebeurtenisobject.

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

-SourceIdentifier

Hiermee geeft u de bron-id op van de gebeurtenis waarop u zich abonneert. De bron-id moet uniek zijn in de huidige sessie. Deze parameter is vereist.

De waarde van deze parameter wordt weergegeven in de waarde van de eigenschap SourceIdentifier van het abonneeobject en van alle gebeurtenisobjecten die aan dit abonnement zijn gekoppeld.

De waarde is specifiek voor de bron van de gebeurtenis. Dit kan een willekeurige waarde zijn die u hebt gemaakt voor gebruik met de New-Event cmdlet. De PowerShell-engine ondersteunt de PSEngineEvent-waardenPowerShell.Exiting en PowerShell.OnIdle.

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

-SupportEvent

Geeft aan dat de cmdlet het gebeurtenisabonnement verbergt. Voeg deze parameter toe wanneer het huidige abonnement deel uitmaakt van een complexer mechanisme voor gebeurtenisregistratie en het niet onafhankelijk mag worden gedetecteerd.

Als u een abonnement wilt weergeven of annuleren dat is gemaakt met de parameter SupportEvent , voegt u de parameter Force toe aan de Get-EventSubscriber cmdlets of Unregister-Event .

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

Invoerwaarden

None

U kunt invoer niet doorspezen naar Register-EngineEvent.

Uitvoerwaarden

None or System.Management.Automation.PSEventJob

Als u de parameter Action gebruikt, Register-EngineEvent retourneert het object System.Management.Automation.PSEventJob . Anders wordt er geen uitvoer gegenereerd.

Notities

Gebeurtenissen, gebeurtenisabonnementen en de gebeurteniswachtrij bestaan alleen in de huidige sessie. Als u de huidige sessie sluit, wordt de gebeurteniswachtrij verwijderd en wordt het gebeurtenisabonnement geannuleerd.

Wanneer u zich abonneert op de gebeurtenis Afsluiten , zijn de cmdlets die kunnen worden uitgevoerd door de parameter Action beperkt tot de cmdlets in de modules Microsoft.PowerShell.Core en Microsoft.PowerShell.Utility . De gebeurtenis Afsluiten wordt alleen geactiveerd wanneer de sessie wordt afgesloten onder beheer van PowerShell. De gebeurtenis wordt niet geactiveerd wanneer het hosttoepassings- of terminalvenster wordt gesloten.

De engine wordt beschouwd als niet-actief als er geen pijplijn wordt uitgevoerd. De gebeurtenis OnIdle wordt geactiveerd wanneer PowerShell gedurende 300 milliseconden (ms) inactief is geweest.

Notitie

Wanneer PSReadLine in gebruik is, wordt de gebeurtenis OnIdle geactiveerd wanneer ReadKey() er een time-out optreedt (geen typen binnen 300 ms). De gebeurtenis kan worden gesignaleerd terwijl de gebruiker bezig is met het bewerken van een opdrachtregel. De gebruiker leest bijvoorbeeld help om te bepalen welke parameter moet worden gebruikt. Vanaf PSReadLine 2.2.0-beta4 is het OnIdle-gedrag gewijzigd om de gebeurtenis alleen aan te geven als er een ReadKey() time-out is en de huidige bewerkingsbuffer leeg is.