Register-ObjectEvent
Subskrybuje zdarzenia generowane przez obiekt programu Microsoft .NET Framework.
Składnia
Default (Domyślna)
Register-ObjectEvent
[-InputObject] <PSObject>
[-EventName] <String>
[[-SourceIdentifier] <String>]
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>]
Opis
Polecenie cmdlet Register-ObjectEvent subskrybuje zdarzenia generowane przez obiekty platformy .NET na komputerze lokalnym lub na komputerze zdalnym.
Po wystąpieniu subskrybowanego zdarzenia jest ono dodawane do kolejki zdarzeń w sesji. Aby uzyskać zdarzenia w kolejce zdarzeń, użyj cmdletu Get-Event.
Możesz użyć parametrów Register-ObjectEvent, aby określić wartości właściwości zdarzeń, które mogą ułatwić zidentyfikowanie zdarzenia w kolejce. Można również użyć parametru Action w celu określenia akcji do wykonania po wystąpieniu zdarzenia subskrybowanego, a parametr Forward do wysyłania zdarzeń do kolejki zdarzeń w sesji lokalnej.
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.
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, aby uzyskać zdarzenia 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 po wystąpieniu zdarzenia tworzenia wystąpienia wskazującego, ż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 i $EventArgs zmiennych automatycznych, 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. Do zarządzania zadaniem w tle można użyć poleceń cmdlet zadań, takich jak Get-Job i Receive-Job. Aby uzyskać więcej informacji, zobacz 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 funkcji Enable-ProcessCreationEvent 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 }
Najpierw tworzymy PSSessions na dwóch komputerach zdalnych i zapisujemy je w zmiennej $S. Następnie polecenie cmdlet Invoke-Command uruchom skrypt ProcessCreationEvent.ps1 w każdym z serwerów PSSessions w $S. Ta akcja powoduje utworzenie funkcji Enable-ProcessCreationEvent w sesjach zdalnych.
Na koniec uruchamiamy funkcję Enable-ProcessCreationEvent w sesjach zdalnych.
Funkcja zawiera polecenie Register-ObjectEvent, 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 $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 tym przypadku polecenie cmdlet Get-Random generuje liczbę losową 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 &) 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 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 Action
Po określeniu akcji Register-ObjectEvent zwraca obiekt zadania zdarzenia, który reprezentuje akcję. Cmdlety do zadań umożliwiają zarządzanie zadaniami dotyczącymi zdarzeń.
Właściwości parametru
| Typ: | ScriptBlock |
| Domyślna wartość: | None |
| Obsługuje symbole wieloznaczne: | False |
| DontShow: | False |
Zestawy parametrów
(All)
| Position: | 101 |
| Obowiązkowy: | False |
| Wartość z potoku: | False |
| Wartość z potoku według nazwy właściwości: | False |
| Wartość z pozostałych argumentów: | 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 nazwie EventArrived i Stopped. Aby znaleźć nazwę zdarzenia, użyj polecenia cmdlet Get-Member.
Właściwości parametru
| Typ: | String |
| Domyślna wartość: | None |
| Obsługuje symbole wieloznaczne: | False |
| DontShow: | False |
Zestawy parametrów
(All)
| Position: | 1 |
| Obowiązkowy: | True |
| Wartość z potoku: | False |
| Wartość z potoku według nazwy właściwości: | False |
| Wartość z pozostałych argumentów: | 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.
Właściwości parametru
| Typ: | SwitchParameter |
| Domyślna wartość: | None |
| Obsługuje symbole wieloznaczne: | False |
| DontShow: | False |
Zestawy parametrów
(All)
| Position: | Named |
| Obowiązkowy: | False |
| Wartość z potoku: | False |
| Wartość z potoku według nazwy właściwości: | False |
| Wartość z pozostałych argumentów: | 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.
Właściwości parametru
| Typ: | PSObject |
| Domyślna wartość: | None |
| Obsługuje symbole wieloznaczne: | False |
| DontShow: | False |
Zestawy parametrów
(All)
| Position: | 0 |
| Obowiązkowy: | True |
| Wartość z potoku: | False |
| Wartość z potoku według nazwy właściwości: | False |
| Wartość z pozostałych argumentów: | False |
-MaxTriggerCount
Określa maksymalną liczbę wyzwalanych zdarzeń.
Właściwości parametru
| Typ: | Int32 |
| Domyślna wartość: | None |
| Obsługuje symbole wieloznaczne: | False |
| DontShow: | False |
Zestawy parametrów
(All)
| Position: | Named |
| Obowiązkowy: | False |
| Wartość z potoku: | False |
| Wartość z potoku według nazwy właściwości: | False |
| Wartość z pozostałych argumentów: | 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ą.
Właściwości parametru
| Typ: | PSObject |
| Domyślna wartość: | None |
| Obsługuje symbole wieloznaczne: | False |
| DontShow: | False |
Zestawy parametrów
(All)
| Position: | Named |
| Obowiązkowy: | False |
| Wartość z potoku: | False |
| Wartość z potoku według nazwy właściwości: | False |
| Wartość z pozostałych argumentów: | 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ą.
Właściwości parametru
| Typ: | String |
| Domyślna wartość: | None |
| Obsługuje symbole wieloznaczne: | False |
| DontShow: | False |
Zestawy parametrów
(All)
| Position: | 100 |
| Obowiązkowy: | False |
| Wartość z potoku: | False |
| Wartość z potoku według nazwy właściwości: | False |
| Wartość z pozostałych argumentów: | False |
-SupportEvent
Wskazuje, że cmdlet ukrywa subskrypcję zdarzenia. 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 Force poleceń cmdlet Get-EventSubscriber i Unregister-Event.
Właściwości parametru
| Typ: | SwitchParameter |
| Domyślna wartość: | None |
| Obsługuje symbole wieloznaczne: | False |
| DontShow: | False |
Zestawy parametrów
(All)
| Position: | Named |
| Obowiązkowy: | False |
| Wartość z potoku: | False |
| Wartość z potoku według nazwy właściwości: | False |
| Wartość z pozostałych argumentów: | False |
CommonParameters
To polecenie cmdlet obsługuje typowe parametry: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction i -WarningVariable. Aby uzyskać więcej informacji, zobacz about_CommonParameters.
Dane wejściowe
None
Nie można przekazywać obiektów do tego cmdletu.
Dane wyjściowe
None
Domyślnie to polecenie cmdlet nie zwraca żadnych danych wyjściowych.
PSEventJob
Jeśli używasz parametru action
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 zostanie anulowana.
