Register-EngineEvent

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

Subskrybuje 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 wygenerowanych przez New-Event polecenie cmdlet OnIdle lub Exiting Engine. 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 wystąpieniu zdarzenia subskrybowanego jest ono dodawane 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 do identyfikowania zdarzenia. Parametr Forward informuje aparat o przesłaniu dalej 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 polecenie , 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
}

Dodano parametr SupportEvent w celu ukrycia subskrypcji zdarzeń. Gdy program PowerShell zakończy działanie, w tym przypadku historia poleceń z sesji zakończenia jest eksportowany plik XML w katalogu użytkownika $HOME .

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

W tym przykładzie tworzona jest 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 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 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 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, $EventArgsi $Args automatyczne, które zawierają informacje o zdarzeniu 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ł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 New-Event cmdlet . Aparat programu PowerShell obsługuje wartości PSEngineEvent 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 potokować obiektów do tego polecenia cmdlet.

Dane wyjściowe

None

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

PSEventJob

Jeśli używasz parametru Akcja , 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 odrzucona i subskrypcja zdarzeń zostanie anulowana.

Podczas subskrybowania zdarzenia Exiting polecenia cmdlet, które mogą być wykonywane przez parametr Action , 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 po zamknięciu aplikacji hosta lub okna terminalu.

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

Uwaga

Gdy funkcja PSReadLine jest używana, zdarzenie OnIdle jest wyzwalane, gdy ReadKey() limit czasu jest wyświetlany (bez wpisywania w ciągu 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 zmieniło się w taki sposób, aby sygnalizować zdarzenie tylko wtedy, gdy występuje ReadKey() limit czasu, a bieżący bufor edycji jest pusty.