Register-ObjectEvent
Prenumererar på de händelser som genereras av ett Microsoft .NET Framework-objekt.
Syntax
Register-ObjectEvent
[-InputObject] <PSObject>
[-EventName] <String>
[[-SourceIdentifier] <String>]
[[-Action] <ScriptBlock>]
[-MessageData <PSObject>]
[-SupportEvent]
[-Forward]
[-MaxTriggerCount <Int32>]
[<CommonParameters>]
Description
Cmdleten Register-ObjectEvent
prenumererar på händelser som genereras av .NET-objekt på den lokala datorn eller på en fjärrdator.
När den prenumererade händelsen aktiveras läggs den till i händelsekön i din session. Om du vill hämta händelser i händelsekön använder du cmdleten Get-Event
.
Du kan använda parametrarna Register-ObjectEvent
för för att ange egenskapsvärden för de händelser som kan hjälpa dig att identifiera händelsen i kön. Du kan också använda parametern Åtgärd för att ange åtgärder som ska vidtas när en prenumerationshändelse aktiveras och parametern Vidarebefordra för att skicka fjärrhändelser till händelsekön i den lokala sessionen.
När du prenumererar på en händelse läggs en händelseprenumerant till i sessionen. Om du vill hämta händelseprenumeranterna i sessionen använder du cmdleten Get-EventSubscriber
. Om du vill avbryta prenumerationen använder du cmdleten Unregister-Event
, som tar bort händelseprenumeranten från sessionen.
Exempel
Exempel 1: Prenumerera på händelser när en ny process startar
Det här exemplet prenumererar på händelser som genereras när en ny process startar.
Kommandot använder objektet ManagementEventWatcher för att hämta EventArrived-händelser . Ett frågeobjekt anger att händelserna är instansskapandehändelser för klassen 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"
Exempel 2: Ange en åtgärd för att svara på en händelse
När du anger en åtgärd läggs händelser som aktiveras inte till i händelsekön. I stället svarar åtgärden på händelsen. I det här exemplet, när en instansskapandehändelse genereras som anger att en ny process startas, utlöses en ny ProcessCreated-händelse .
$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
Åtgärden använder och $Sender
$EventArgs
automatiska variabler som endast fylls i för händelseåtgärder.
Kommandot Register-ObjectEvent
returnerar ett jobbobjekt som representerar åtgärden, som körs som ett bakgrundsjobb. Du kan använda cmdletarna Jobb, till exempel Get-Job
och Receive-Job
, för att hantera bakgrundsjobbet. Mer information finns i artikeln om jobb.
Exempel 3: Prenumerera på objekthändelser på fjärrdatorer
Det här exemplet visar hur du prenumererar på objekthändelser på fjärrdatorer. I det här exemplet används funktionen Enable-ProcessCreationEvent
som definieras i ProcessCreationEvent.ps1
skriptfilen. Det här skriptet är tillgängligt för alla datorer i exemplet.
# 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 }
Den första skapar vi PSSessioner på två fjärrdatorer och sparar dem i variabeln $S
. Invoke-Command
Därefter kör cmdleten skriptet ProcessCreationEvent.ps1
i var och en av PSSessionerna i $S
. Den här åtgärden skapar Enable-ProcessCreationEvent
funktionen i fjärrsessionerna.
Slutligen kör Enable-ProcessCreationEvent
vi funktionen i fjärrsessionerna.
Funktionen innehåller ett Register-ObjectEvent
kommando som prenumererar på instansskapandehändelser på Win32_Process-objektetvia ManagementEventWatcher-objektet och dess EventArrived-händelse.
Exempel 4: Använd den dynamiska modulen i PSEventJob-objektet
Det här exemplet visar hur du använder den dynamiska modulen i PSEventJob-objektet som skapas när du inkluderar en åtgärd i en händelseregistrering. Först skapar och aktiverar vi ett tidsinställt objekt och anger sedan tidsintervallet till 500 (millisekunder). Cmdleten Register-ObjectEvent
registrerar händelsen Elapsed för det tidsinställda objektet. PSEventJob-objektet sparas i variabeln $Job
och är också tillgängligt i händelseprenumerantens åtgärdsegenskap. Mer information finns i Get-EventSubscriber.
När tidsintervallet förflutit ut utlöses en händelse och åtgärden körs. I det här fallet genererar cmdleten Get-Random
ett slumpmässigt tal mellan 0 och 100 och sparar det i variabeln $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
PSEventJob har en modulegenskap som innehåller en modul med dynamiskt skript som implementerar åtgärden. Med hjälp av anropsoperatorn (&
) anropar vi kommandot i modulen för att visa värdet för variabeln $Random
.
Mer information om moduler finns i about_Modules.
Parametrar
-Action
Anger kommandona för att hantera händelsen. Kommandona i åtgärden körs när en händelse aktiveras, i stället för att skicka händelsen till händelsekön. Omslut kommandona i klammerparenteser ( { } ) för att skapa ett skriptblock.
Värdet för parametern Åtgärd kan innehålla variablerna $Event
, $EventSubscriber
, $Sender
, $EventArgs
och $Args
automatisk. Dessa variabler ger information om händelsen till åtgärdsskriptblocket. Mer information finns i about_Automatic_Variables.
När du anger en åtgärd Register-ObjectEvent
returnerar ett händelsejobbobjekt som representerar den åtgärden. Du kan använda cmdletarna Jobb för att hantera händelsejobbet.
Type: | ScriptBlock |
Position: | 101 |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-EventName
Anger den händelse som du prenumererar på.
Värdet för den här parametern måste vara namnet på händelsen som .NET-objektet exponerar. Klassen ManagementEventWatcher har till exempel händelser med namnet EventArrived och Stopped. Om du vill hitta händelsenamnet för en händelse använder du cmdleten Get-Member
.
Type: | String |
Position: | 1 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Forward
Anger att cmdleten skickar händelser för den här prenumerationen till en fjärrsession. Använd den här parametern när du registrerar dig för händelser på en fjärrdator eller i en fjärrsession.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-InputObject
Anger .NET-objektet som genererar händelserna. Ange en variabel som innehåller objektet eller skriv ett kommando eller uttryck som hämtar objektet.
Type: | PSObject |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaxTriggerCount
Anger det maximala antalet gånger en händelse kan utlösas.
Type: | Int32 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MessageData
Anger eventuella ytterligare data som ska associeras med den här händelseprenumerationen. Värdet för den här parametern visas i egenskapen MessageData för alla händelser som är associerade med den här prenumerationen.
Type: | PSObject |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SourceIdentifier
Anger ett namn som du väljer för prenumerationen. Namnet som du väljer måste vara unikt i den aktuella sessionen. Standardvärdet är det GUID som PowerShell tilldelar.
Värdet för den här parametern visas i värdet för egenskapen SourceIdentifier för prenumerantobjektet och alla händelseobjekt som är associerade med den här prenumerationen.
Type: | String |
Position: | 100 |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SupportEvent
Anger att cmdleten döljer händelseprenumerationen. Använd den här parametern när den aktuella prenumerationen ingår i en mer komplex mekanism för händelseregistrering och inte bör identifieras oberoende av varandra.
Om du vill visa eller avbryta en prenumeration som skapades med parametern SupportEvent använder du parametern Get-EventSubscriber
Force för cmdletarna och Unregister-Event
.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Indata
None
Du kan inte skicka objekt till den här cmdleten.
Utdata
None
Som standard returnerar den här cmdleten inga utdata.
När du använder parametern Åtgärd returnerar den här cmdleten ett PSEventJob-objekt .
Kommentarer
Händelser, händelseprenumerationer och händelsekön finns bara i den aktuella sessionen. Om du stänger den aktuella sessionen ignoreras händelsekön och händelseprenumerationen avbryts.
Relaterade länkar
Feedback
https://aka.ms/ContentUserFeedback.
Kommer snart: Under hela 2024 kommer vi att fasa ut GitHub-problem som feedbackmekanism för innehåll och ersätta det med ett nytt feedbacksystem. Mer information finns i:Skicka och visa feedback för