Register-EngineEvent
Prenumererar på händelser som genereras av PowerShell-motorn och av cmdleten New-Event .
Syntax
Register-EngineEvent
[-SourceIdentifier] <String>
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>] Description
Cmdleten Register-EngineEvent prenumererar på händelser som genereras av PowerShell-motorn och cmdleten New-Event . Använd parametern SourceIdentifier för att ange händelsen.
Du kan använda den här cmdleten för att prenumerera på händelser och händelser som genereras av cmdleten New-Event OnIdle eller Exiting Engine. Dessa händelser läggs automatiskt till i händelsekön i sessionen utan att prenumerera. Genom att prenumerera kan du dock vidarebefordra händelserna, ange en åtgärd för att svara på händelserna och avbryta prenumerationen.
När du prenumererar på en händelse läggs en händelseprenumerant till i sessionen. Om du vill hämta händelseprenumeranterna i sessionen använder du cmdleten Get-EventSubscriber . Om du vill avbryta prenumerationen använder du cmdleten Unregister-Event , som tar bort händelseprenumeranten från sessionen.
När den prenumererade händelsen aktiveras läggs den till i händelsekön i din session. Om du vill hämta händelser i händelsekön använder du cmdleten Get-Event .
Exempel
Exempel 1: Registrera en PowerShell-motorhändelse på fjärrdatorer
Det här exemplet registreras för en PowerShell-motorhändelse på två fjärrdatorer.
$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S {
Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward
}New-PSSession skapar en användarhanterad session (PSSession) på var och en av fjärrdatorerna. Cmdleten Invoke-CommandRegister-EngineEvent kör kommandot i fjärrsessionerna.
Register-EngineEvent använder parametern SourceIdentifier för att identifiera händelsen. Parametern Vidarebefordra instruerar motorn att vidarebefordra händelserna från fjärrsessionen till den lokala sessionen.
Exempel 2: Vidta en angiven åtgärd när händelsen Avsluta inträffar
Det här exemplet visar hur du kör Register-EngineEvent för att vidta en specifik åtgärd när händelsen PowerShell.Exiting inträffar.
Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
Get-History | Export-Clixml $HOME\history.clixml
}Parametern SupportEvent läggs till för att dölja händelseprenumerationen. När PowerShell avslutas exporteras i det här fallet kommandohistoriken från den avslutande sessionen en XML-fil i användarens $HOME katalog.
Exempel 3: Skapa och prenumerera på en användardefinierad händelse
Det här exemplet skapar en prenumeration för händelser från källan MyEventSource. Det här är en godtycklig källa som vi ska använda för att övervaka förloppet för ett jobb. Register-EngineEvent används för att skapa prenumerationen. Skriptblocket för åtgärdsparametern loggar händelsedata till en textfil.
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 skapat jobb-ID 18. Start-Job skapat jobb-ID 19. I exempel nr 4 tar vi bort händelseprenumerationen och jobben och inspekterar sedan loggfilen.
Exempel 4: Avregistrera händelser och rensa jobb
Detta är en fortsättning på exempel 3. I det här exemplet väntar vi i 10 sekunder för att låta flera händelser inträffa. Sedan avregistrerar vi händelseprenumerationen.
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...Cmdleten Unregister-Event stoppar jobbet som är associerat med händelseprenumerationen (jobb-ID 18). Jobb-ID 19 körs fortfarande och skapar nya händelser. Vi använder jobb-cmdletarna för att stoppa jobbet och ta bort de onödiga jobbobjekten. Get-Content visar innehållet i loggfilen.
Parametrar
-Action
Anger kommandon för att hantera händelserna. Kommandona i åtgärden körs när en händelse aktiveras, i stället för att skicka händelsen till händelsekön. Omslut kommandona i klammerparenteser ({}) för att skapa ett skriptblock.
Värdet för parametern Åtgärd kan innehålla variablerna $Event, $EventSubscriber, $Sender, $EventArgsoch $Args automatisk, som ger information om händelsen till åtgärdsskriptblocket. Mer information finns i about_Automatic_Variables.
När du anger en åtgärd Register-EngineEvent returnerar ett händelsejobbobjekt som representerar den åtgärden. Du kan använda cmdletarna Jobb för att hantera händelsejobbet.
| Type: | ScriptBlock |
| Position: | 101 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Forward
Anger att cmdleten skickar händelser för den här prenumerationen till sessionen på den lokala datorn. Använd den här parametern när du registrerar dig för händelser på en fjärrdator eller i en fjärrsession.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MaxTriggerCount
Anger det maximala antalet gånger som åtgärden körs för händelseprenumerationen.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MessageData
Anger ytterligare data som är associerade med händelsen. Värdet för den här parametern visas i egenskapen MessageData för händelseobjektet.
| Type: | PSObject |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SourceIdentifier
Anger källidentifieraren för händelsen som du prenumererar på. Källidentifieraren måste vara unik i den aktuella sessionen. Den här parametern krävs.
Värdet för den här parametern visas i värdet för egenskapen SourceIdentifier för prenumerantobjektet och för alla händelseobjekt som är associerade med den här prenumerationen.
Värdet är specifikt för källan till händelsen. Detta kan vara ett godtyckligt värde som du skapade för att använda med cmdleten New-Event . PowerShell-motorn stöder PSEngineEvent-värdena PowerShell.Exiting och PowerShell.OnIdle.
| Type: | String |
| Position: | 100 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SupportEvent
Anger att cmdleten döljer händelseprenumerationen. Lägg till den här parametern när den aktuella prenumerationen ingår i en mer komplex mekanism för händelseregistrering och den inte bör identifieras oberoende av varandra.
Om du vill visa eller avbryta en prenumeration som har skapats med parametern SupportEvent lägger du tillforce-parametern i Get-EventSubscriber cmdletarna eller Unregister-Event .
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Indata
None
Du kan inte skicka objekt till den här cmdleten.
Utdata
None
Som standard returnerar den här cmdleten inga utdata.
När du använder parametern Åtgärd returnerar den här cmdleten ett PSEventJob-objekt .
Kommentarer
Händelser, händelseprenumerationer och händelsekön finns bara i den aktuella sessionen. Om du stänger den aktuella sessionen ignoreras händelsekön och händelseprenumerationen avbryts.
När du prenumererar på händelsen Avsluta begränsas de cmdletar som kan köras av åtgärdsparametern till cmdletarna i modulerna Microsoft.PowerShell.Core och Microsoft.PowerShell.Utility . Händelsen Avsluta utlöses endast när sessionen avslutas under kontroll av PowerShell. Händelsen utlöses inte när värdprogrammet eller terminalfönstret stängs.
Motorn anses vara inaktiv om den inte kör en pipeline. OnIdle-händelsen utlöses när PowerShell har varit inaktivt i 300 millisekunder (ms).
Kommentar
När PSReadLine används utlöses OnIdle-händelsen när ReadKey() tidsgränsen uppnås (ingen inmatning på 300 ms). Händelsen kan signaleras medan användaren är mitt i redigeringen av en kommandorad, till exempel läser användaren hjälp för att bestämma vilken parameter som ska användas. Från och med PSReadLine 2.2.0-beta4 ändrades OnIdle-beteendet för att signalera händelsen endast om det finns en ReadKey() timeout och den aktuella redigeringsbufferten är tom.
