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 gebeurtenissen en gebeurtenissen van de OnIdle-engine of om gebeurtenissen af te sluiten die door de New-Event cmdlet zijn gegenereerd. Deze gebeurtenissen worden automatisch toegevoegd aan de gebeurteniswachtrij in uw sessie zonder u te abonneren. Met abonneren kunt u echter de gebeurtenissen doorsturen, een actie opgeven om te reageren op de gebeurtenissen en het abonnement opzeggen.

Wanneer u zich abonneert op een gebeurtenis, wordt er een gebeurtenisabonnee toegevoegd aan uw sessie. Gebruik de Get-EventSubscriber 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 de Get-Event cmdlet om gebeurtenissen in de gebeurteniswachtrij op te halen.

Voorbeelden

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

In dit voorbeeld wordt een PowerShell-engine-gebeurtenis geregistreerd 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 Doorsturen geeft de engine aan dat de gebeurtenissen van de externe sessie naar de lokale sessie moeten worden doorgestuurd.

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

In dit voorbeeld ziet u hoe u kunt uitvoeren om een specifieke actie uit te voeren Register-EngineEvent 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: Een door de gebruiker gedefinieerde gebeurtenis maken en abonneren

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 actieparameter 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 van voorbeeld 3. In dit voorbeeld wachten we 10 seconden om verschillende gebeurtenissen te laten plaatsvinden. Vervolgens heffen we de registratie van het gebeurtenisabonnement op.

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 afhandelen 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 Actie kan de $Eventvariabelen , $EventSubscriber, $Senderen $EventArgs$Args automatische variabelen bevatten, die informatie geven over de gebeurtenis aan het actiescriptblok. Zie about_Automatic_Variables voor meer informatie.

Wanneer u een actie opgeeft, Register-EngineEvent wordt een gebeurtenistaakobject geretourneerd dat die 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 naar de sessie op de lokale computer verzendt. 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 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 deze 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 of Unregister-Event cmdlets.

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

Invoerwaarden

None

U kunt geen objecten doorsluisen naar deze cmdlet.

Uitvoerwaarden

None

Deze cmdlet retourneert standaard geen uitvoer.

PSEventJob

Wanneer u de actieparameter gebruikt, retourneert deze cmdlet een PSEventJob-object .

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 afsluitgebeurtenis, zijn de cmdlets die kunnen worden uitgevoerd door de parameter Actie beperkt tot de cmdlets in de modules Microsoft.PowerShell.Core en Microsoft.PowerShell.Utility. De afsluitgebeurtenis wordt alleen geactiveerd wanneer de sessie wordt afgesloten onder beheer van PowerShell. De gebeurtenis wordt niet geactiveerd wanneer de hosttoepassing of het terminalvenster wordt gesloten.

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

Notitie

Wanneer PSReadLine wordt gebruikt, wordt de OnIdle-gebeurtenis geactiveerd wanneer ReadKey() er een time-out optreedt (geen typen in 300 ms). De gebeurtenis kan worden gesignaleerd terwijl de gebruiker zich midden in het bewerken van een opdrachtregel bevindt, bijvoorbeeld de gebruiker leest 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.