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 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 åtgärdsparametern 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 utlöses 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 de $Sender automatiska variablerna och $EventArgs 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 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å 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 timerobjekt och anger sedan timerns intervall till 500 (millisekunder). Cmdleten Register-ObjectEvent registrerar händelsen Elapsed 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 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 för 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 Action kan innehålla variablerna $Event, $EventSubscriber, $Sender, $EventArgsoch $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ändelsejobbsobjekt som representerar den åtgärden. Du kan använda jobb-cmdletar för att hantera händelsejobbet.

Type:ScriptBlock
Position:101
Default value:None
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å den händelse som .NET-objektet exponerar. Klassen ManagementEventWatcher har till exempel händelser med namnet EventArrived och Stopped. Använd cmdleten Get-Member för att hitta händelsenamnet för en händelse.

Type:String
Position:1
Default value:None
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
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
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
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
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
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-EventSubscriberForce för cmdletarna och Unregister-Event .

Type:SwitchParameter
Position:Named
Default value:None
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 parametern Register-ObjectEventAction 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.