Register-ObjectEvent
Prenumererar på 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 sessionen. 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 vilka å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 ManagementEventWatcher-objektet 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 inte händelser som aktiveras till i händelsekön. I stället svarar åtgärden på händelsen. I det här exemplet, när en händelse för att skapa en instans 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 jobbets cmdletar, 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 }
Det första vi skapar 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å händelser för att skapa instanser på Win32_Process-objektet via 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 timerns intervall till 500 (millisekunder). Cmdleten Register-ObjectEvent
registrerar händelsen Förflutit för timerobjektet. 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
automatiska. 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 jobb-cmdletar 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. Använd cmdleten för att hitta händelsenamnet för Get-Member
en händelse.
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 det .NET-objekt 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 som 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 har skapats 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 Register-ObjectEvent
.
Utdata
None or System.Management.Automation.PSEventJob
När du använder parameternRegister-ObjectEvent
Åtgärd returnerar ett System.Management.Automation.PSEventJob-objekt . Annars genererar den inga utdata.
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.