Udostępnij za pośrednictwem

Register-ObjectEvent

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

Subskrybuje zdarzenia generowane przez obiekt programu Microsoft .NET Framework.

Składnia

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

Opis

Polecenie Register-ObjectEvent cmdlet subskrybuje zdarzenia generowane przez obiekty platformy .NET na komputerze lokalnym lub na komputerze zdalnym.

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 .

Możesz użyć parametrów , Register-ObjectEvent aby określić wartości właściwości zdarzeń, które mogą pomóc zidentyfikować zdarzenie w kolejce. Można również użyć parametru Akcja , aby określić akcje, które mają być podejmowane, gdy jest zgłaszane subskrybowane zdarzenie, a parametr Prześlij dalej w celu wysyłania zdarzeń zdalnych do kolejki zdarzeń w sesji lokalnej.

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.

Przykłady

Przykład 1. Subskrybowanie zdarzeń po uruchomieniu nowego procesu

W tym przykładzie subskrybuje zdarzenia generowane podczas uruchamiania nowego procesu.

Polecenie używa obiektu ManagementEventWatcher w celu pobrania zdarzeń EventArrived . Obiekt zapytania określa, że zdarzenia są zdarzeniami tworzenia wystąpienia dla klasy Win32_Process .

$queryParameters = '__InstanceCreationEvent', (New-Object TimeSpan 0,0,1),
    "TargetInstance isa 'Win32_Process'"
$Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters
$ProcessWatcher = New-Object System.Management.ManagementEventWatcher $Query
Register-ObjectEvent -InputObject $ProcessWatcher -EventName "EventArrived"

Przykład 2. Określanie akcji, która ma odpowiadać na zdarzenie

Po określeniu akcji zdarzenia, które są wywoływane, nie są dodawane do kolejki zdarzeń. Zamiast tego akcja odpowiada na zdarzenie. W tym przykładzie, gdy zostanie zgłoszone zdarzenie tworzenia wystąpienia wskazujące, że nowy proces zostanie uruchomiony, zostanie zgłoszone nowe zdarzenie ProcessCreated .

$queryParameters = '__InstanceCreationEvent', (New-Object TimeSpan 0,0,1),
    "TargetInstance isa 'Win32_Process'"
$Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters
$ProcessWatcher = New-Object System.Management.ManagementEventWatcher $query
$newEventArgs = @{
    SourceIdentifier = 'PowerShell.ProcessCreated'
    Sender = $Sender
    EventArguments = $EventArgs.NewEvent.TargetInstance
}
$Action = { New-Event @newEventArgs }
Register-ObjectEvent -InputObject $ProcessWatcher -EventName "EventArrived" -Action $Action

Id   Name               PSJobTypeName   State       HasMoreData   Location   Command
--   ----               -------------   -----       -----------   --------   -------
 5   3db2d67a-efff-...                 NotStarted   False                    New-Event @newEventArgs

Akcja używa $Sender zmiennych automatycznych i $EventArgs , które są wypełniane tylko dla akcji zdarzeń.

Polecenie Register-ObjectEvent zwraca obiekt zadania, który reprezentuje akcję, która jest uruchamiana jako zadanie w tle. Polecenia cmdlet zadania, takie jak Get-Job i Receive-Job, umożliwiają zarządzanie zadaniem w tle. Aby uzyskać więcej informacji, zobacz opis polecenia about_Jobs.

Przykład 3. Subskrybowanie zdarzeń obiektów na komputerach zdalnych

W tym przykładzie pokazano, jak subskrybować zdarzenia obiektów na komputerach zdalnych. W tym przykładzie użyto Enable-ProcessCreationEvent funkcji zdefiniowanej w pliku skryptu ProcessCreationEvent.ps1 . Ten skrypt jest dostępny dla wszystkich komputerów w przykładzie.

# ProcessCreationEvent.ps1
function  Enable-ProcessCreationEvent {
    $queryParameters = "__InstanceCreationEvent", (New-Object TimeSpan 0,0,1),
        "TargetInstance isa 'Win32_Process'"
    $Query = New-Object System.Management.WqlEventQuery -ArgumentList $queryParameters

    $objectEventArgs = @{
        Input = New-Object System.Management.ManagementEventWatcher $Query
        EventName = 'EventArrived'
        SourceIdentifier = 'WMI.ProcessCreated'
        MessageData = 'Test'
        Forward = $True
    }
    Register-ObjectEvent @objectEventArgs
}

$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S -FilePath ProcessCreationEvent.ps1
Invoke-Command -Session $S { Enable-ProcessCreationEvent }

Pierwszy tworzymy pssessions na dwóch komputerach zdalnych i zapisujemy je w zmiennej $S . Invoke-Command Następnie polecenie cmdlet uruchom ProcessCreationEvent.ps1 skrypt w każdym z psSessions w pliku $S. Ta akcja powoduje utworzenie Enable-ProcessCreationEvent funkcji w sesjach zdalnych. Na koniec uruchamiamy Enable-ProcessCreationEvent funkcję w sesjach zdalnych.

Funkcja zawiera Register-ObjectEvent polecenie, które subskrybuje zdarzenia tworzenia wystąpienia w obiekcie Win32_Process za pośrednictwem obiektu ManagementEventWatcher i jego zdarzenia EventArrived .

Przykład 4. Użycie modułu dynamicznego w obiekcie PSEventJob

W tym przykładzie pokazano, jak używać modułu dynamicznego w obiekcie PSEventJob utworzonym podczas dołączania akcji do rejestracji zdarzeń. Najpierw utworzymy i włączymy obiekt czasomierza, a następnie ustawimy interwał czasomierza na 500 (milisekund). Polecenie Register-ObjectEvent cmdlet rejestruje zdarzenie, które upłynął dla obiektu czasomierza. Obiekt PSEventJob jest zapisywany w zmiennej $Job i jest również dostępny we właściwości Action subskrybenta zdarzenia. Aby uzyskać więcej informacji, zobacz Get-EventSubscriber.

Za każdym razem, gdy interwał czasomierza upłynie, zdarzenie jest wywoływane i wykonywana jest akcja. W takim przypadku Get-Random polecenie cmdlet generuje losową liczbę z zakresu od 0 do 100 i zapisuje ją w zmiennej $Random .

$Timer = New-Object Timers.Timer
$Timer.Interval = 500
$Timer.Enabled = $True
$objectEventArgs = @{
    InputObject = $Timer
    EventName = 'Elapsed'
    SourceIdentifier = 'Timer.Random'
    Action = {$Random = Get-Random -Min 0 -Max 100}
}
$Job = Register-ObjectEvent @objectEventArgs
$Job | Format-List -Property *
& $Job.module {$Random}
& $Job.module {$Random}

State         : Running
Module        : __DynamicModule_53113769-31f2-42dc-830b-8749325e28d6
StatusMessage :
HasMoreData   : True
Location      :
Command       : $Random = Get-Random -Min 0 -Max 100
JobStateInfo  : Running
Finished      : System.Threading.ManualResetEvent
InstanceId    : 47b5ec9f-bfe3-4605-860a-4674e5d44ca8
Id            : 7
Name          : Timer.Random
ChildJobs     : {}
PSBeginTime   : 6/27/2019 10:19:06 AM
PSEndTime     :
PSJobTypeName :
Output        : {}
Error         : {}
Progress      : {}
Verbose       : {}
Debug         : {}
Warning       : {}
Information   : {}
60
47

Obiekt PSEventJob ma właściwość Module zawierającą dynamiczny moduł skryptu, który implementuje akcję. Za pomocą operatora wywołania (&) wywołujemy polecenie w module, aby wyświetlić wartość zmiennej $Random .

Aby uzyskać więcej informacji na temat modułów, zobacz about_Modules.

Parametry

-Action

Określa polecenia do obsługi zdarzenia. 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. Te zmienne zawierają informacje o zdarzeniu w bloku skryptu akcji . Aby uzyskać więcej informacji, zobacz about_Automatic_Variables.

Po określeniu akcji Register-ObjectEvent 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

-EventName

Określa zdarzenie, do którego subskrybujesz.

Wartość tego parametru musi być nazwą zdarzenia uwidacznianego przez obiekt .NET. Na przykład klasa ManagementEventWatcher ma zdarzenia o nazwach EventArrived i Stopped. Aby znaleźć nazwę zdarzenia, użyj Get-Member polecenia cmdlet .

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

-Forward

Wskazuje, że polecenie cmdlet wysyła zdarzenia dla tej subskrypcji do sesji zdalnej. 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

-InputObject

Określa obiekt .NET, który generuje zdarzenia. Wprowadź zmienną zawierającą obiekt lub wpisz polecenie lub wyrażenie, które pobiera obiekt.

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

-MaxTriggerCount

Określa maksymalną liczbę wyzwalanych zdarzeń.

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

-MessageData

Określa wszelkie dodatkowe dane, które mają być skojarzone z tą subskrypcją zdarzeń. Wartość tego parametru jest wyświetlana we właściwości MessageData wszystkich zdarzeń skojarzonych z tą subskrypcją.

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

-SourceIdentifier

Określa nazwę wybraną dla subskrypcji. Wybrana nazwa musi być unikatowa w bieżącej sesji. Wartość domyślna to identyfikator GUID przypisywany przez program PowerShell.

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ą.

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

-SupportEvent

Wskazuje, że polecenie cmdlet ukrywa subskrypcję zdarzeń. Użyj tego parametru, gdy bieżąca subskrypcja jest częścią bardziej złożonego mechanizmu rejestracji zdarzeń i nie powinna być wykrywana niezależnie.

Aby wyświetlić lub anulować subskrypcję utworzoną za pomocą parametru SupportEvent, użyj parametru Get-EventSubscriber Force poleceń cmdlet i 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 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.