Udostępnij za pośrednictwem

Register-EngineEvent

  • Odwołanie
Moduł:
Microsoft.PowerShell.Utility

Subskrybuje zdarzenia generowane przez silnik programu PowerShell oraz polecenie cmdlet New-Event.

Składnia

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

Opis

Polecenie cmdlet Register-EngineEvent subskrybuje zdarzenia, które są generowane przez silnik PowerShell i polecenie cmdlet New-Event. Użyj parametru SourceIdentifier, aby określić zdarzenie.

Tego polecenia cmdlet można użyć do subskrybowania OnIdle lub Zamykanie zdarzeń i zdarzeń aparatu generowanych przez 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 cmdletu Get-EventSubscriber. Aby anulować subskrypcję, użyj polecenia cmdlet Unregister-Event, które usuwa subskrybenta zdarzeń z sesji.

Po wystąpieniu zdarzenia subskrybowanego jest ono dodawane do kolejki zdarzeń w sesji. Aby uzyskać zdarzenia w kolejce zdarzeń, użyj polecenia cmdlet Get-Event.

Przykłady

Przykład 1: Rejestrowanie zdarzenia silnika programu PowerShell na komputerach zdalnych

W tym przykładzie rejestruje się zdarzenie w aparacie 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 cmdlet Invoke-Command uruchamia polecenie Register-EngineEvent w sesjach zdalnych. Register-EngineEvent używa parametru SourceIdentifier w celu zidentyfikowania zdarzenia. Parametr Forward informuje moduł o przekazywaniu zdarzeń z sesji zdalnej do sesji lokalnej.

Przykład 2: Wykonaj określoną akcję, gdy wystąpi zdarzenie zakończenia

W tym przykładzie pokazano, jak uruchomić Register-EngineEvent, aby wykonać określoną akcję, gdy wystąpi zdarzenie PowerShell.Exiting.

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

Dodano parametr SupportEvent w celu ukrycia subskrypcji zdarzeń. Gdy program PowerShell zakończy działanie, historia poleceń z kończącej się sesji jest eksportowana do pliku XML w katalogu $HOME użytkownika.

Przykład 3. Tworzenie i subskrybowanie zdarzenia zdefiniowanego przez użytkownika

W tym przykładzie jest tworzona subskrypcja 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 akcji zapisuje dane zdarzenia do pliku tekstowego.

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..."
        $newEventSplat = @{
            SourceIdentifier = 'MyEventSource'
            MessageData      = ("{0} -  Work done..." -f (Get-Date))
        }
        New-Event @newEventSplat
    }
}
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 identyfikator zadania 18. Start-Job utworzono zadanie z identyfikatorem 19. W przykładzie nr 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 cmdlet Unregister-Event zatrzymuje zadanie skojarzone z subskrypcją zdarzeń (identyfikator zadania 18). Identyfikator zadania 19 jest nadal uruchomiony i tworzy nowe zdarzenia. Używamy poleceń cmdlet Job, aby zatrzymać zadanie i usunąć zbędne obiekty zadań. Get-Content wyświetla zawartość pliku dziennika.

Parametry

-Action

Określa polecenia do obsługi zdarzeń. Polecenia w Akcja są wykonywane, gdy zostaje wywołane zdarzenie, zamiast wysyłania go do kolejki zdarzeń. Dołącz polecenia w nawiasach klamrowych ({}), aby utworzyć blok skryptu.

Wartość parametru Akcja może zawierać zmienne automatyczne $Event, $EventSubscriber, $Sender, $EventArgsi $Args, które dostarczają informacji dotyczących zdarzenia do bloku skryptu Akcja. 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.

Typ:ScriptBlock
Position:101
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-Forward

Wskazuje, że polecenie cmdlet wysyła zdarzenia związane z tą subskrypcją do sesji na komputerze lokalnym. Użyj tego parametru podczas rejestrowania zdarzeń na komputerze zdalnym lub w sesji zdalnej.

Typ:SwitchParameter
Position:Named
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-MaxTriggerCount

Określa maksymalną liczbę razy, kiedy akcja jest wykonana w ramach subskrypcji zdarzenia.

Typ:Int32
Position:Named
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-MessageData

Ten parametr jest częścią klasy bazowej dla wszystkich cmdletów zdarzeń. Register-EngineEvent nie używa tego parametru. Wszystkie dane przekazane do tego parametru są ignorowane.

Typ:PSObject
Position:Named
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-SourceIdentifier

Określa identyfikator źródłowy zdarzenia, do którego subskrybujesz. Identyfikator źródła 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 cmdlet New-Event. Silnik PowerShell obsługuje wartości PSEngineEventPowerShell.Exiting i PowerShell.OnIdle.

Typ:String
Position:100
Domyślna wartość:None
Wymagane:True
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

-SupportEvent

Wskazuje, że cmdlet ukrywa subskrypcję zdarzenia. 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 SupportEventEvent, dodaj parametr Force do poleceń cmdlet Get-EventSubscriber lub Unregister-Event.

Typ:SwitchParameter
Position:Named
Domyślna wartość:None
Wymagane:False
Akceptowanie danych wejściowych potoku:False
Akceptowanie symboli wieloznacznych:False

Dane wejściowe

None

Nie można potokować obiektów z tym poleceniem cmdlet.

Dane wyjściowe

None

Domyślnie to polecenie cmdlet nie zwraca żadnych danych wyjściowych.

PSEventJob

Jeśli używasz parametru action , to polecenie cmdlet zwraca obiekt PSEventJob.

Uwagi

Zdarzenia, subskrypcje zdarzeń i kolejka zdarzeń istnieją tylko w bieżącej sesji. Jeśli zamkniesz bieżącą sesję, kolejka zdarzeń zostanie usunięta, a subskrypcja zdarzeń anulowana.

Podczas subskrybowania zdarzenia Opuszczanie polecenia cmdlet, które mogą być uruchamiane za pomocą parametru Action, są ograniczone do poleceń cmdlet w modułach Microsoft.PowerShell.Core i Microsoft.PowerShell.Utility. Zdarzenie Exiting jest wyzwalane tylko wtedy, gdy sesja zostanie zakończona pod kontrolą programu PowerShell. Zdarzenie nie jest wyzwalane po zamknięciu aplikacji hosta lub okna terminalu.

Silnik jest uważany za bezczynny, jeśli nie uruchamia procesu. Zdarzenie OnIdle jest uruchamiane, gdy program PowerShell jest bezczynny przez 300 milisekund (ms).

Notatka

Gdy PSReadLine jest używane, zdarzenie OnIdle jest wyzwalane, gdy ReadKey() osiąga limit czasu (brak wpisywania przez 300 ms). Zdarzenie może być zasygnalizowane, gdy użytkownik znajduje się w trakcie edytowania wiersza polecenia, na przykład użytkownik odczytuje pomoc, aby zdecydować, który parametr ma być używany. Począwszy od programu PSReadLine 2.2.0-beta4, zachowanie OnIdle zostało zmienione, aby zasygnalizować zdarzenie tylko wtedy, gdy występuje limit czasu ReadKey(), a bieżący bufor edycji jest pusty.