Register-ObjectEvent

  • Referentie
Module:
Microsoft.PowerShell.Utility

Abonneert u op de gebeurtenissen die worden gegenereerd door een Microsoft .NET Framework-object.

Syntax

Register-ObjectEvent
        [-InputObject] <PSObject>
        [-EventName] <String>
        [[-SourceIdentifier] <String>]
        [[-Action] <ScriptBlock>]
        [-MessageData <PSObject>]
        [-SupportEvent]
        [-Forward]
        [-MaxTriggerCount <Int32>]
        [<CommonParameters>]

Description

De Register-ObjectEvent cmdlet abonneert zich op gebeurtenissen die worden gegenereerd door .NET-objecten op de lokale computer of op een externe computer.

Wanneer de geabonneerde gebeurtenis wordt gegenereerd, wordt deze toegevoegd aan de gebeurteniswachtrij in uw sessie. Gebruik de Get-Event cmdlet om gebeurtenissen in de gebeurteniswachtrij op te halen.

U kunt de parameters gebruiken om Register-ObjectEvent eigenschapswaarden op te geven van de gebeurtenissen waarmee u de gebeurtenis in de wachtrij kunt identificeren. U kunt ook de parameter Actie gebruiken om acties op te geven die moeten worden uitgevoerd wanneer een geabonneerde gebeurtenis wordt gegenereerd en de parameter Doorsturen om externe gebeurtenissen naar de gebeurteniswachtrij in de lokale sessie te verzenden.

Wanneer u zich abonneert op een gebeurtenis, wordt er een gebeurtenisabonnee toegevoegd aan uw sessie. Gebruik de Get-EventSubscriber cmdlet om de gebeurtenisabonnees in de sessie op te halen. Als u het abonnement wilt annuleren, gebruikt u de Unregister-Event cmdlet, waarmee de gebeurtenisabonnee uit de sessie wordt verwijderd.

Voorbeelden

Voorbeeld 1: Abonneren op gebeurtenissen wanneer een nieuw proces wordt gestart

In dit voorbeeld worden gebeurtenissen geabonneerd die worden gegenereerd wanneer een nieuw proces wordt gestart.

De opdracht maakt gebruik van het Object ManagementEventWatcher om EventArrived-gebeurtenissen op te halen. Een queryobject geeft aan dat de gebeurtenissen gebeurtenissen voor het maken van exemplaren zijn voor de Win32_Process-klasse .

$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"

Voorbeeld 2: Een actie opgeven om te reageren op een gebeurtenis

Wanneer u een actie opgeeft, worden gebeurtenissen die worden gegenereerd, niet toegevoegd aan de gebeurteniswachtrij. In plaats daarvan reageert de actie op de gebeurtenis. Wanneer in dit voorbeeld een gebeurtenis voor het maken van een exemplaar wordt gegenereerd die aangeeft dat een nieuw proces wordt gestart, wordt er een nieuwe ProcessCreated-gebeurtenis gegenereerd.

$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

De actie maakt gebruik van de $Sender en $EventArgs automatische variabelen die alleen worden ingevuld voor gebeurtenisacties.

De Register-ObjectEvent opdracht retourneert een taakobject dat de actie vertegenwoordigt, die wordt uitgevoerd als een achtergrondtaak. U kunt de taak-cmdlets, zoals Get-Job en Receive-Job, gebruiken om de achtergrondtaak te beheren. Zie About Jobs (Taken) voor meer informatie.

Voorbeeld 3: Abonneren op object gebeurtenissen op externe computers

In dit voorbeeld ziet u hoe u zich abonneert op object gebeurtenissen op externe computers. In dit voorbeeld wordt de Enable-ProcessCreationEvent functie gebruikt die is gedefinieerd in het ProcessCreationEvent.ps1 scriptbestand. Dit script is beschikbaar voor alle computers in het voorbeeld.

# 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 }

De eerste die we PSSessions maken op twee externe computers en deze opslaan in de $S variabele. Vervolgens voert de Invoke-Command cmdlet het ProcessCreationEvent.ps1 script uit in elk van de PSSessions in $S. Met deze actie maakt u de Enable-ProcessCreationEvent functie in de externe sessies. Ten slotte voeren we de Enable-ProcessCreationEvent functie uit in de externe sessies.

De functie bevat een Register-ObjectEvent opdracht die zich abonneert op gebeurtenissen voor het maken van exemplaren op het Win32_Process-object via het object ManagementEventWatcher en de gebeurtenis EventArrived.

Voorbeeld 4: De dynamische module gebruiken in het PSEventJob-object

In dit voorbeeld ziet u hoe u de dynamische module gebruikt in het PSEventJob-object dat wordt gemaakt wanneer u een actie opneemt in een gebeurtenisregistratie. Eerst maken en inschakelen we een timerobject en stellen we vervolgens het interval van de timer in op 500 (milliseconden). De Register-ObjectEvent cmdlet registreert de verstreken gebeurtenis van het timerobject. Het PSEventJob-object wordt opgeslagen in de $Job variabele en is ook beschikbaar in de eigenschap Actie van de gebeurtenisabonnee. Zie Get-EventSubscriber voor meer informatie.

Wanneer het timerinterval is verstreken, wordt er een gebeurtenis gegenereerd en wordt de actie uitgevoerd. In dit geval genereert de Get-Random cmdlet een willekeurig getal tussen 0 en 100 en slaat deze op in de $Random variabele.

$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

De PSEventJob heeft een moduleeigenschap die een dynamische scriptmodule bevat waarmee de actie wordt geïmplementeerd. Met behulp van de aanroepoperator (&) roepen we de opdracht in de module aan om de waarde van de $Random variabele weer te geven.

Zie about_Modules voor meer informatie over modules.

Parameters

-Action

Hiermee geeft u de opdrachten voor het afhandelen van de gebeurtenis. De opdrachten in de actie worden uitgevoerd wanneer een gebeurtenis wordt gegenereerd, in plaats van de gebeurtenis naar de gebeurteniswachtrij te verzenden. Plaats de opdrachten tussen accolades ({ }) om een scriptblok te maken.

De waarde van de parameter Actie kan de $Eventvariabelen , $EventSubscriber, $Senderen $EventArgs$Args automatische variabelen bevatten. Deze variabelen bevatten informatie over de gebeurtenis in het scriptblok Actie . Zie about_Automatic_Variables voor meer informatie.

Wanneer u een actie opgeeft, Register-ObjectEvent wordt een gebeurtenistaakobject geretourneerd dat die actie vertegenwoordigt. U kunt de taak-cmdlets gebruiken om de gebeurtenistaak te beheren.

Type:ScriptBlock
Position:101
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-EventName

Hiermee geeft u de gebeurtenis op waarop u zich abonneert.

De waarde van deze parameter moet de naam zijn van de gebeurtenis die het .NET-object beschikbaar maakt. De klasse ManagementEventWatcher bevat bijvoorbeeld gebeurtenissen met de naam EventArrived en Stopped. Gebruik de Get-Member cmdlet om de gebeurtenisnaam van een gebeurtenis te vinden.

Type:String
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Forward

Geeft aan dat de cmdlet gebeurtenissen voor dit abonnement naar een externe sessie verzendt. Gebruik deze parameter wanneer u zich registreert voor gebeurtenissen op een externe computer of in een externe sessie.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-InputObject

Hiermee geeft u het .NET-object op waarmee de gebeurtenissen worden gegenereerd. Voer een variabele in die het object bevat of typ een opdracht of expressie waarmee het object wordt opgehaald.

Type:PSObject
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-MaxTriggerCount

Hiermee geeft u het maximum aantal keren dat een gebeurtenis kan worden geactiveerd.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MessageData

Hiermee geeft u eventuele aanvullende gegevens op die aan dit gebeurtenisabonnement moeten worden gekoppeld. De waarde van deze parameter wordt weergegeven in de eigenschap MessageData van alle gebeurtenissen die aan dit abonnement zijn gekoppeld.

Type:PSObject
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SourceIdentifier

Hiermee geeft u een naam op die u selecteert voor het abonnement. De naam die u selecteert, moet uniek zijn in de huidige sessie. De standaardwaarde is de GUID die door PowerShell wordt toegewezen.

De waarde van deze parameter wordt weergegeven in de waarde van de eigenschap SourceIdentifier van het abonneeobject en alle gebeurtenisobjecten die aan dit abonnement zijn gekoppeld.

Type:String
Position:100
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SupportEvent

Geeft aan dat de cmdlet het gebeurtenisabonnement verbergt. Gebruik deze parameter wanneer het huidige abonnement deel uitmaakt van een complexer mechanisme voor gebeurtenisregistratie en niet onafhankelijk mag worden gedetecteerd.

Als u een abonnement wilt weergeven of annuleren dat is gemaakt met de parameter SupportEvent , gebruikt u de parameter Force van de Get-EventSubscriber en Unregister-Event cmdlets.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Invoerwaarden

None

U kunt geen objecten doorsluisen naar deze cmdlet.

Uitvoerwaarden

None

Deze cmdlet retourneert standaard geen uitvoer.

PSEventJob

Wanneer u de actieparameter gebruikt, retourneert deze cmdlet een PSEventJob-object .

Notities

Gebeurtenissen, gebeurtenisabonnementen en de gebeurteniswachtrij bestaan alleen in de huidige sessie. Als u de huidige sessie sluit, wordt de gebeurteniswachtrij verwijderd en wordt het gebeurtenisabonnement geannuleerd.