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.

Type:	ScriptBlock
Position:	101
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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 .

Type:	String
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	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.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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.

Type:	PSObject
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-MaxTriggerCount

Określa maksymalną liczbę wyzwalanych zdarzeń.

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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ą.

Type:	PSObject
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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ą.

Type:	String
Position:	100
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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 .

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.

Register-ObjectEvent

Składnia

Opis

Przykłady

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

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

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

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

Parametry

-Action

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

Dane wejściowe

Dane wyjściowe

Uwagi

Opinia

Dodatkowe zasoby

Register-ObjectEvent

Składnia

Opis

Przykłady

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

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

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

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

Parametry

-Action

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

Dane wejściowe

Dane wyjściowe

Uwagi

Linki powiązane

Opinia

Dodatkowe zasoby