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 för Register-ObjectEvent
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 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 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 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 $Sender
och $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 jobb-cmdletar, till exempel Get-Job
och Receive-Job
, för att hantera bakgrundsjobbet. Mer information finns i about_Jobs.
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 PSSessions på två fjärrdatorer och sparar dem i variabeln $S
. Därefter kör Invoke-Command
-cmdleten ProcessCreationEvent.ps1
skriptet i var och en av PSSessionerna i $S
. Den här åtgärden skapar funktionen Enable-ProcessCreationEvent
i fjärrsessionerna.
Slutligen kör vi funktionen Enable-ProcessCreationEvent
i fjärrsessionerna.
Funktionen innehåller ett Register-ObjectEvent
-kommando som prenumererar på instansskapandehändelser på det Win32_Process objektet via ManagementEventWatcher--objektet och dess händelsehändelse EventArrived.
Exempel 4: Använd den dynamiska modulen i PSEventJob-objektet
Det här exemplet visar hur du använder den dynamiska modulen i PSEventJob- objekt 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 den förflutna händelsen för timerobjektet.
PSEventJob--objektet sparas i variabeln $Job
och är också tillgängligt i egenskapen Action för händelseprenumeranten. 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 egenskap Module 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öras 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 Action kan innehålla $Event
, $EventSubscriber
, $Sender
, $EventArgs
och $Args
automatiska variabler. Dessa variabler ger information om händelsen till Åtgärd skriptblock. Mer information finns i about_Automatic_Variables.
När du anger en åtgärd returnerar Register-ObjectEvent
ett händelsejobbobjekt som representerar den åtgärden. Du kan använda cmdletarna Jobb för att hantera händelsejobbet.
Typ: | ScriptBlock |
Position: | 101 |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | 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 Stoppad. Om du vill hitta händelsenamnet för en händelse använder du cmdleten Get-Member
.
Typ: | String |
Position: | 1 |
Standardvärde: | None |
Obligatorisk: | True |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | 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.
Typ: | SwitchParameter |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | 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.
Typ: | PSObject |
Position: | 0 |
Standardvärde: | None |
Obligatorisk: | True |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | False |
-MaxTriggerCount
Anger det maximala antalet gånger en händelse kan utlösas.
Typ: | Int32 |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | 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.
Typ: | PSObject |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | 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.
Typ: | String |
Position: | 100 |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | 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 Force för cmdletarna Get-EventSubscriber
och Unregister-Event
.
Typ: | SwitchParameter |
Position: | Named |
Standardvärde: | None |
Obligatorisk: | False |
Godkänn pipeline-indata: | False |
Godkänn jokertecken: | 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.