Register-EngineEvent
Subskrybuj zdarzenia generowane przez aparat programu PowerShell i polecenie New-Event cmdlet.
Składnia
Register-EngineEvent
[-SourceIdentifier] <String>
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>] Opis
Polecenie Register-EngineEvent cmdlet subskrybuje zdarzenia generowane przez aparat programu PowerShell i New-Event polecenie cmdlet. Użyj parametru SourceIdentifier , aby określić zdarzenie.
Tego polecenia cmdlet można użyć do subskrybowania zdarzeń i zdarzeń aparatu OnIdle lub exiting engine generowanych przez New-Event polecenie cmdlet. Te zdarzenia są automatycznie dodawane do kolejki zdarzeń w sesji bez subskrybowania. Jednak subskrybowanie umożliwia przekazywanie zdarzeń, określanie akcji reagowania na zdarzenia i anulowanie subskrypcji.
Po zasubskrybowaniu zdarzenia subskrybent zdarzenia zostanie dodany do sesji. Aby uzyskać subskrybentów zdarzeń w sesji, użyj Get-EventSubscriber polecenia cmdlet . Aby anulować subskrypcję, użyj Unregister-Event polecenia cmdlet , które usuwa subskrybenta zdarzeń z sesji.
Po podniesieniu zdarzenia subskrybowanego zostanie ono dodane do kolejki zdarzeń w sesji. Aby uzyskać zdarzenia w kolejce zdarzeń, użyj Get-Event polecenia cmdlet .
Przykłady
Przykład 1. Rejestrowanie zdarzenia aparatu programu PowerShell na komputerach zdalnych
W tym przykładzie rejestrowane jest zdarzenie aparatu programu PowerShell na dwóch komputerach zdalnych.
$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S {
Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PsEngineEvent]::Exiting) -Forward
}New-PSSession Tworzy sesję zarządzaną przez użytkownika (PSSession) na każdym z komputerów zdalnych. Polecenie Invoke-Command cmdlet uruchamia Register-EngineEvent polecenie w sesjach zdalnych.
Register-EngineEvent używa parametru SourceIdentifier w celu zidentyfikowania zdarzenia. Parametr Forward informuje aparat o przesłaniu dalej zdarzeń z sesji zdalnej do sesji lokalnej.
Przykład 2. Wykonywanie określonej akcji po wystąpieniu zdarzenia Zakończenia
W tym przykładzie pokazano, jak uruchomić polecenie Register-EngineEvent , aby wykonać określoną akcję po wystąpieniu zdarzenia PowerShell.Exiting .
Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
Get-History | Export-Clixml $Home\history.clixml
}Parametr SupportEvent jest dodawany w celu ukrycia subskrypcji zdarzeń. Po zakończeniu działania programu PowerShell historia poleceń z sesji zakończenia jest eksportowana do pliku XML w katalogu użytkownika $Home .
Przykład 3: Twórca i subskrybowanie zdarzenia zdefiniowanego przez użytkownika
W tym przykładzie tworzona jest subskrypcja dla zdarzeń ze źródła MyEventSource. Jest to dowolne źródło, którego będziemy używać do monitorowania postępu zadania. Register-EngineEvent służy do tworzenia subskrypcji. Blok skryptu dla parametru Akcja rejestruje dane zdarzenia w pliku tekstowym.
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 utworzono zadanie o identyfikatorze 18. Start-Job utworzono zadanie o identyfikatorze 19. W przykładzie #4 usuwamy subskrypcję zdarzeń i zadania, a następnie sprawdzamy plik dziennika.
Przykład 4. Wyrejestrowywanie zdarzeń i czyszczenie zadań
Jest to kontynuacja przykładu 3. W tym przykładzie poczekamy 10 sekund, aby umożliwić wystąpienie kilku zdarzeń. Następnie wyrejestrujemy subskrypcję zdarzeń.
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...Polecenie Unregister-Event cmdlet zatrzymuje zadanie skojarzone z subskrypcją zdarzeń (identyfikator zadania 18). Identyfikator zadania 19 jest nadal uruchomiony i tworzy nowe zdarzenia. Używamy poleceń cmdlet zadania , aby zatrzymać zadanie i usunąć niepotrzebne obiekty zadań. Get-Content wyświetla zawartość pliku dziennika.
Parametry
-Action
Określa polecenia do obsługi zdarzeń. Polecenia w akcji są uruchamiane po wystąpieniu zdarzenia zamiast wysyłania zdarzenia do kolejki zdarzeń. Dołącz polecenia w nawiasach klamrowych ({}), aby utworzyć blok skryptu.
Wartość parametru Akcja może zawierać $Eventzmienne , , $EventSubscriber, $Sender$EventArgs, i $Args automatyczne, które dostarczają informacje o zdarzeniu do bloku skryptu akcji. Aby uzyskać więcej informacji, zobacz about_Automatic_Variables.
Po określeniu akcji Register-EngineEvent zwraca obiekt zadania zdarzenia, który reprezentuje akcję. Polecenia cmdlet zadania umożliwiają zarządzanie zadaniem zdarzenia.
| Type: | ScriptBlock |
| Position: | 101 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Forward
Wskazuje, że polecenie cmdlet wysyła zdarzenia dla tej subskrypcji do sesji na komputerze lokalnym. Użyj tego parametru podczas rejestrowania zdarzeń na komputerze zdalnym lub w sesji zdalnej.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MaxTriggerCount
Określa maksymalną liczbę wykonań akcji dla subskrypcji zdarzeń.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MessageData
Określa dodatkowe dane skojarzone ze zdarzeniem. Wartość tego parametru jest wyświetlana we właściwości MessageData obiektu zdarzenia.
| Type: | PSObject |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SourceIdentifier
Określa identyfikator źródłowy zdarzenia, do którego subskrybujesz. Identyfikator źródłowy musi być unikatowy w bieżącej sesji. Ten parametr jest wymagany.
Wartość tego parametru jest wyświetlana w wartości właściwości SourceIdentifier obiektu subskrybenta i wszystkich obiektów zdarzeń skojarzonych z tą subskrypcją.
Wartość jest specyficzna dla źródła zdarzenia. Może to być dowolna wartość utworzona do użycia z poleceniem New-Event cmdlet . Aparat programu PowerShell obsługuje wartości PSEngineEventprogramu PowerShell.Exiting i PowerShell.OnIdle.
| Type: | String |
| Position: | 100 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SupportEvent
Wskazuje, że polecenie cmdlet ukrywa subskrypcję zdarzeń. Dodaj ten parametr, gdy bieżąca subskrypcja jest częścią bardziej złożonego mechanizmu rejestracji zdarzeń i nie powinna być odnajdywane niezależnie.
Aby wyświetlić lub anulować subskrypcję utworzoną za pomocą parametru SupportEvent, dodaj parametr Force do Get-EventSubscriber poleceń cmdlet lub .Unregister-Event
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Dane wejściowe
None
Nie można przekazać potoku wejściowego do Register-EngineEventelementu .
Dane wyjściowe
None or System.Management.Automation.PSEventJob
Jeśli używasz parametru Akcja , Register-EngineEvent zwraca obiekt System.Management.Automation.PSEventJob . W przeciwnym razie nie generuje żadnych danych wyjściowych.
Uwagi
Zdarzenia, subskrypcje zdarzeń i kolejka zdarzeń istnieją tylko w bieżącej sesji. Jeśli zamkniesz bieżącą sesję, kolejka zdarzeń zostanie odrzucona i subskrypcja zdarzeń zostanie anulowana.
Podczas subskrybowania zdarzenia Zakończenia polecenia cmdlet, które można wykonać za pomocą parametru Akcja , są ograniczone do poleceń cmdlet w modułach Microsoft.PowerShell.Core i Microsoft.PowerShell.Utility . Zdarzenie Zakończenia jest wyzwalane tylko wtedy, gdy sesja zostanie zakończona pod kontrolą programu PowerShell. Zdarzenie nie jest wyzwalane, gdy aplikacja hosta lub okno terminalu jest zamknięte.
Aparat jest uważany za bezczynny, jeśli nie uruchamia potoku. Zdarzenie OnIdle jest wyzwalane, gdy program PowerShell został bezczynny dla 300 milisekund (ms).
Uwaga
Gdy funkcja PSReadLine jest używana, zdarzenie OnIdle jest wyzwalane po ReadKey() przekroczeniu limitu czasu (bez wpisywania w 300 ms). Zdarzenie może być zasygnalizowane, gdy użytkownik jest w trakcie edytowania wiersza polecenia, na przykład użytkownik odczytuje pomoc w podjęciu decyzji o tym, który parametr ma być używany. Począwszy od programu PSReadLine 2.2.0-beta4, zachowanie OnIdle zmieniło się tak, aby sygnalizować zdarzenie tylko wtedy, gdy wystąpi ReadKey() limit czasu, a bieżący bufor edycji jest pusty.