Register-ObjectEvent
Abonneert u op de gebeurtenissen die worden gegenereerd door een Microsoft .NET Framework-object.
Syntax
Default (Standaard)
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 cmdlet Get-Event om gebeurtenissen in de gebeurteniswachtrij op te halen.
U kunt de parameters van Register-ObjectEvent gebruiken om eigenschapswaarden op te geven van de gebeurtenissen waarmee u de gebeurtenis in de wachtrij kunt identificeren. U kunt ook de parameter Action gebruiken om acties op te geven die moeten worden uitgevoerd wanneer een geabonneerde gebeurtenis wordt gegenereerd en de parameter Doorsturen om externe gebeurtenissen te verzenden naar de gebeurteniswachtrij in de lokale sessie.
Wanneer u zich abonneert op een gebeurtenis, wordt er een gebeurtenisabonnee toegevoegd aan uw sessie. Gebruik de cmdlet Get-EventSubscriber om de abonnees van het evenement in de sessie te verkrijgen. Als u het abonnement wilt annuleren, gebruikt u de Unregister-Event cmdlet, waarmee de abonnee van de gebeurtenis 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 er 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 opdracht Register-ObjectEvent 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_Jobsvoor 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 maken PSSessions 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 waarmee u zich abonneert op gebeurtenissen voor het maken van exemplaren op het Win32_Process-object via het object ManagementEventWatcher en de bijbehorende gebeurtenis EventArrived.
Voorbeeld 4: De dynamische module gebruiken in het PSEventJob-object
In dit voorbeeld ziet u hoe u de dynamische module gebruikt in de PSEventJob-object dat wordt gemaakt wanneer u een Action 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 cmdlet Register-ObjectEvent registreert de verstreken gebeurtenis van het timerobject. Het object PSEventJob wordt opgeslagen in de variabele $Job en is ook beschikbaar in de eigenschap Action van de gebeurtenisabonnee. Zie Get-EventSubscribervoor 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 eigenschap Module 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_Modulesvoor 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 Action kan de $Event, $EventSubscriber, $Sender, $EventArgsen automatische variabelen $args bevatten. Deze variabelen bieden informatie over de gebeurtenis aan het scriptblok Action. Voor meer informatie, zie about_Automatic_Variables.
Wanneer u een actie opgeeft, retourneert Register-ObjectEvent een gebeurtenistaakobject dat die actie vertegenwoordigt. U kunt de taak-cmdlets gebruiken om de gebeurtenistaak te beheren.
Parametereigenschappen
| Type: | ScriptBlock |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | 101 |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | 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 Gestopt. Gebruik de cmdlet Get-Member om de gebeurtenisnaam van een gebeurtenis te vinden.
Parametereigenschappen
| Type: | String |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | 1 |
| Verplicht: | True |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | 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.
Parametereigenschappen
| Type: | SwitchParameter |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | 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.
Parametereigenschappen
| Type: | PSObject |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | 0 |
| Verplicht: | True |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
-MaxTriggerCount
Hiermee geeft u het maximum aantal keren dat een gebeurtenis kan worden geactiveerd.
Parametereigenschappen
| Type: | Int32 |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | 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.
Parametereigenschappen
| Type: | PSObject |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | 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.
Parametereigenschappen
| Type: | String |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | 100 |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | 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.
Parametereigenschappen
| Type: | SwitchParameter |
| Default value: | None |
| Ondersteunt jokertekens: | False |
| DontShow: | False |
Parametersets
(All)
| Position: | Named |
| Verplicht: | False |
| Waarde uit pijplijn: | False |
| Waarde uit pijplijn op eigenschapsnaam: | False |
| Waarde van resterende argumenten: | False |
CommonParameters
Deze cmdlet ondersteunt de algemene parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction en -WarningVariable. Zie about_CommonParametersvoor meer informatie.
Invoerwaarden
None
U kunt geen objecten doorsluisen naar deze cmdlet.
Uitvoerwaarden
None
Deze cmdlet retourneert standaard geen uitvoer.
PSEventJob
Wanneer u de parameter Action 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.
