Register-ObjectEvent

  • Referens
Modul:
Microsoft.PowerShell.Utility

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, $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ä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-EventSubscriberForce 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.

PSEventJob

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.