Register-ObjectEvent

Reference

Modul:: Microsoft.PowerShell.Utility

Přihlásí se k odběru událostí generovaných objektem rozhraní Microsoft .NET Framework.

Syntax

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

Description

Rutina Register-ObjectEvent se přihlásí k odběru událostí generovaných objekty .NET v místním počítači nebo ve vzdáleném počítači.

Při vyvolání odebírané události se přidá do fronty událostí ve vaší relaci. K získání událostí ve frontě událostí použijte rutinu Get-Event .

Parametry můžete použít Register-ObjectEvent k určení hodnot vlastností událostí, které vám pomůžou identifikovat událost ve frontě. Pomocí parametru Akce můžete také určit akce, které se mají provést při vyvolání odebírané události, a předat parametr pro odesílání vzdálených událostí do fronty událostí v místní relaci.

Když se přihlásíte k odběru události, přidá se do vaší relace odběratel události. Pokud chcete získat odběratele událostí v relaci, použijte tuto rutinu Get-EventSubscriber . Pokud chcete předplatné zrušit, použijte rutinu Unregister-Event , která odstraní odběratele události z relace.

Příklady

Příklad 1: Přihlášení k odběru událostí při spuštění nového procesu

Tento příklad se přihlásí k odběru událostí vygenerovaných při spuštění nového procesu.

Příkaz používá Objekt ManagementEventWatcher k získání událostí EventArrived . Objekt dotazu určuje, že události jsou události vytváření instance pro Win32_Process třídy.

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

Příklad 2: Určení akce, která má reagovat na událost

Když zadáte akci, události, které jsou vyvolány, nejsou přidány do fronty událostí. Místo toho akce reaguje na událost. V tomto příkladu je vyvolána událost vytvoření instance označující, že je spuštěn nový proces, je vyvolána nová událost ProcessCreated .

$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

Akce používá $Sender automatické $EventArgs proměnné, které jsou naplněny pouze pro akce událostí.

Příkaz Register-ObjectEvent vrátí objekt úlohy, který představuje akci, která běží jako úloha na pozadí. Ke správě úlohy na pozadí můžete použít rutiny Úlohy, například Get-Job a Receive-Job. Další informace najdete v tématu Informace o úlohách.

Příklad 3: Přihlášení k odběru událostí objektů na vzdálených počítačích

Tento příklad ukazuje, jak se přihlásit k odběru událostí objektů ve vzdálených počítačích. Tento příklad používá Enable-ProcessCreationEvent funkci definovanou ProcessCreationEvent.ps1 v souboru skriptu. Tento skript je k dispozici pro všechny počítače v příkladu.

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

První vytvoříme psSessions na dvou vzdálených počítačích a uložíme je do $S proměnné. Dále rutina Invoke-Command spustí ProcessCreationEvent.ps1 skript v každé psSessions in $S. Tato akce vytvoří Enable-ProcessCreationEvent funkci ve vzdálených relacích. Nakonec funkci spustíme Enable-ProcessCreationEvent ve vzdálených relacích.

Funkce obsahuje Register-ObjectEvent příkaz, který se přihlásí k odběru událostí vytváření instancí na objektu Win32_Process prostřednictvím objektu ManagementEventWatcher a události EventArrived .

Příklad 4: Použití dynamického modulu v objektu PSEventJob

Tento příklad ukazuje, jak používat dynamický modul v objektu PSEventJob , který je vytvořen při zahrnutí akce do registrace události. Nejprve vytvoříme a povolíme objekt časovače a pak nastavíme interval časovače na 500 (milisekund). Rutina Register-ObjectEvent zaregistruje událost Uplynulé události objektu časovače. Objekt PSEventJob je uložen v $Job proměnné a je také k dispozici ve vlastnosti Action odběratel události. Další informace najdete v tématu Get-EventSubscriber.

Při každém uplynutí intervalu časovače se vyvolá událost a provede se akce. V tomto případě Get-Random rutina vygeneruje náhodné číslo od 0 do 100 a uloží ho $Random do proměnné.

$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 má vlastnost Modulu, která obsahuje modul dynamického skriptu, který implementuje akci. Pomocí operátoru volání (&) vyvoláme příkaz v modulu, který zobrazí hodnotu $Random proměnné.

Další informace o modulech najdete v tématu about_Modules.

Parametry

-Action

Určuje příkazy pro zpracování události. Příkazy v akci se spustí při vyvolání události místo odeslání události do fronty událostí. Uzavřete příkazy do složených závorek ({ } ) a vytvořte blok skriptu.

Hodnota parametru Action může zahrnovat $Eventproměnné , $EventSubscriber, $Sender, $EventArgsa $Args automatické proměnné. Tyto proměnné poskytují informace o události do bloku skriptu akce . Další informace najdete v tématu about_Automatic_Variables.

Když zadáte akci, Register-ObjectEvent vrátí objekt úlohy události, který tuto akci představuje. Ke správě úlohy události můžete použít rutiny Úlohy.

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

-EventName

Určuje událost, ke které se přihlašujete k odběru.

Hodnota tohoto parametru musí být název události, kterou objekt .NET zveřejňuje. Například ManagementEventWatcher třída obsahuje události s názvem EventArrived a Zastaveno. K vyhledání názvu události použijte rutinu Get-Member .

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

-Forward

Označuje, že rutina odesílá události pro toto předplatné do vzdálené relace. Tento parametr použijte při registraci událostí na vzdáleném počítači nebo ve vzdálené relaci.

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

-InputObject

Určuje objekt .NET, který generuje události. Zadejte proměnnou, která obsahuje objekt, nebo zadejte příkaz nebo výraz, který objekt získá.

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

-MaxTriggerCount

Určuje maximální počet aktivací události.

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

-MessageData

Určuje všechna další data, která se mají přidružit k tomuto odběru událostí. Hodnota tohoto parametru se zobrazí ve vlastnosti MessageData všech událostí přidružených k tomuto odběru.

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

-SourceIdentifier

Určuje název, který vyberete pro předplatné. Název, který vyberete, musí být v aktuální relaci jedinečný. Výchozí hodnota je identifikátor GUID, který PowerShell přiřadí.

Hodnota tohoto parametru se zobrazí v hodnotě SourceIdentifier vlastnost odběratel objektu a všechny objekty událostí přidružené k tomuto odběru.

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

-SupportEvent

Označuje, že rutina skryje odběr událostí. Tento parametr použijte, pokud je aktuální odběr součástí složitějšího mechanismu registrace událostí a neměl by být zjištěn nezávisle.

Pokud chcete zobrazit nebo zrušit předplatné vytvořené pomocí parametru SupportEvent , použijte parametr Force pro rutiny Get-EventSubscriber a Unregister-Event rutiny.

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

Vstupy

None

Do této rutiny nemůžete roušit objekty.

Výstupy

None

Ve výchozím nastavení tato rutina nevrací žádný výstup.

PSEventJob

Pokud použijete parametr Action , tato rutina vrátí objekt PSEventJob .

Poznámky

Události, odběry událostí a fronta událostí existují pouze v aktuální relaci. Pokud zavřete aktuální relaci, fronta událostí se zahodí a odběr události se zruší.

Register-ObjectEvent

Syntax

Description

Příklady

Příklad 1: Přihlášení k odběru událostí při spuštění nového procesu

Příklad 2: Určení akce, která má reagovat na událost

Příklad 3: Přihlášení k odběru událostí objektů na vzdálených počítačích

Příklad 4: Použití dynamického modulu v objektu PSEventJob

Parametry

-Action

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

Vstupy

Výstupy

Poznámky

Váš názor

Další materiály

Register-ObjectEvent

Syntax

Description

Příklady

Příklad 1: Přihlášení k odběru událostí při spuštění nového procesu

Příklad 2: Určení akce, která má reagovat na událost

Příklad 3: Přihlášení k odběru událostí objektů na vzdálených počítačích

Příklad 4: Použití dynamického modulu v objektu PSEventJob

Parametry

-Action

-EventName

-Forward

-InputObject

-MaxTriggerCount

-MessageData

-SourceIdentifier

-SupportEvent

Vstupy

Výstupy

Poznámky

Související odkazy

Váš názor

Další materiály