Register-ObjectEvent

Berlangganan peristiwa yang dihasilkan oleh objek Microsoft .NET Framework.

Sintaks

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

Deskripsi

Register-ObjectEvent Cmdlet berlangganan peristiwa yang dihasilkan oleh objek .NET di komputer lokal atau di komputer jarak jauh.

Saat acara berlangganan dinaikkan, peristiwa ditambahkan ke antrean peristiwa di sesi Anda. Untuk mendapatkan peristiwa dalam antrean peristiwa, gunakan Get-Event cmdlet .

Anda dapat menggunakan parameter Register-ObjectEvent untuk menentukan nilai properti peristiwa yang dapat membantu Anda mengidentifikasi peristiwa dalam antrean. Anda juga dapat menggunakan parameter Tindakan untuk menentukan tindakan yang harus diambil saat peristiwa berlangganan dinaikkan dan parameter Teruskan untuk mengirim peristiwa jarak jauh ke antrean peristiwa di sesi lokal.

Saat Anda berlangganan acara, pelanggan peristiwa ditambahkan ke sesi Anda. Untuk mendapatkan pelanggan peristiwa dalam sesi, gunakan Get-EventSubscriber cmdlet . Untuk membatalkan langganan, gunakan Unregister-Event cmdlet , yang menghapus pelanggan peristiwa dari sesi.

Contoh

Contoh 1: Berlangganan peristiwa saat proses baru dimulai

Contoh ini berlangganan peristiwa yang dihasilkan saat proses baru dimulai.

Perintah menggunakan objek ManagementEventWatcher untuk mendapatkan peristiwa EventArrived . Objek kueri menentukan bahwa peristiwa adalah peristiwa pembuatan instans untuk kelas 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"

Contoh 2: Tentukan tindakan untuk merespons peristiwa

Saat Anda menentukan tindakan, peristiwa yang dinaikkan tidak ditambahkan ke antrean peristiwa. Sebaliknya, tindakan merespons peristiwa. Dalam contoh ini, ketika peristiwa pembuatan instans dinaikkan yang menunjukkan bahwa proses baru dimulai, peristiwa ProcessCreated baru dinaikkan.

$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

Tindakan ini menggunakan $Sender variabel dan $EventArgs otomatis yang hanya diisi untuk tindakan peristiwa.

Perintah Register-ObjectEvent mengembalikan objek pekerjaan yang mewakili tindakan, yang berjalan sebagai pekerjaan latar belakang. Anda dapat menggunakan cmdlet Pekerjaan, seperti Get-Job dan Receive-Job, untuk mengelola pekerjaan latar belakang. Untuk informasi selengkapnya, lihat about_Jobs.

Contoh 3: Berlangganan peristiwa objek di komputer jarak jauh

Contoh ini menunjukkan cara berlangganan peristiwa objek di komputer jarak jauh. Contoh ini menggunakan Enable-ProcessCreationEvent fungsi yang ditentukan dalam ProcessCreationEvent.ps1 file skrip. Skrip ini tersedia untuk semua komputer dalam contoh.

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

Yang pertama kita membuat PSSessions pada dua komputer jarak jauh dan menyimpannya dalam $S variabel . Selanjutnya, Invoke-Command cmdlet menjalankan ProcessCreationEvent.ps1 skrip di masing-masing PSSessions di $S. Tindakan ini membuat Enable-ProcessCreationEvent fungsi dalam sesi jarak jauh. Terakhir, kita menjalankan Enable-ProcessCreationEvent fungsi dalam sesi jarak jauh.

Fungsi ini mencakup Register-ObjectEvent perintah yang berlangganan peristiwa pembuatan instans pada objek Win32_Process melalui objek ManagementEventWatcher dan peristiwa EventArrived-nya .

Contoh 4: Gunakan modul dinamis di objek PSEventJob

Contoh ini menunjukkan cara menggunakan modul dinamis di objek PSEventJob yang dibuat saat Anda menyertakan Tindakan dalam pendaftaran peristiwa. Pertama kita membuatdan dan mengaktifkan objek timer, lalu mengatur interval timer ke 500 (milidetik). Cmdlet Register-ObjectEventmendaftarkan peristiwa Yang Berlalu dari objek timer. Objek PSEventJob disimpan dalam $Job variabel dan juga tersedia di properti Tindakan pelanggan peristiwa. Untuk informasi selengkapnya, lihat Get-EventSubscriber.

Setiap kali interval timer berlalu, peristiwa dinaikkan dan tindakan dijalankan. Dalam hal ini, Get-Random cmdlet menghasilkan angka acak antara 0 dan 100 dan menyimpannya dalam $Random variabel.

$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 memiliki properti Modul yang berisi modul skrip dinamis yang mengimplementasikan tindakan. Menggunakan operator panggilan (&), kami memanggil perintah dalam modul untuk menampilkan nilai $Random variabel.

Untuk informasi selengkapnya tentang modul, lihat about_Modules.

Parameter

-Action

Menentukan perintah untuk menangani peristiwa. Perintah dalam Tindakan berjalan saat peristiwa dinaikkan, alih-alih mengirim peristiwa ke antrean peristiwa. Sertakan perintah dalam kurung kurawal ( { } ) untuk membuat blok skrip.

Nilai parameter Tindakan dapat mencakup $Eventvariabel otomatis , , $EventSubscriber$Sender, $EventArgs, dan $Args . Variabel ini memberikan informasi tentang peristiwa ke blok skrip Tindakan . Untuk informasi selengkapnya, lihat about_Automatic_Variables.

Saat Anda menentukan tindakan, Register-ObjectEvent mengembalikan objek pekerjaan peristiwa yang mewakili tindakan tersebut. Anda dapat menggunakan cmdlet Pekerjaan untuk mengelola pekerjaan peristiwa.

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

-EventName

Menentukan peristiwa yang Anda berlangganan.

Nilai parameter ini harus menjadi nama peristiwa yang diekspos objek .NET. Misalnya, kelas ManagementEventWatcher memiliki peristiwa bernama EventArrived dan Stop. Untuk menemukan nama peristiwa suatu peristiwa, gunakan Get-Member cmdlet .

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

-Forward

Menunjukkan bahwa cmdlet mengirim peristiwa untuk langganan ini ke sesi jarak jauh. Gunakan parameter ini saat Anda mendaftar untuk peristiwa di komputer jarak jauh atau dalam sesi jarak jauh.

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

-InputObject

Menentukan objek .NET yang menghasilkan peristiwa. Masukkan variabel yang berisi objek , atau ketik perintah atau ekspresi yang mendapatkan objek .

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

-MaxTriggerCount

Menentukan berapa kali peristiwa dapat dipicu.

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

-MessageData

Menentukan data tambahan yang akan dikaitkan dengan langganan kejadian ini. Nilai parameter ini muncul di properti MessageData dari semua peristiwa yang terkait dengan langganan ini.

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

-SourceIdentifier

Menentukan nama yang Anda pilih untuk langganan. Nama yang Anda pilih harus unik dalam sesi saat ini. Nilai default adalah GUID yang ditetapkan PowerShell.

Nilai parameter ini muncul dalam nilai properti SourceIdentifier dari objek pelanggan dan semua objek peristiwa yang terkait dengan langganan ini.

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

-SupportEvent

Menunjukkan bahwa cmdlet menyembunyikan langganan peristiwa. Gunakan parameter ini ketika langganan saat ini adalah bagian dari mekanisme pendaftaran peristiwa yang lebih kompleks dan tidak boleh ditemukan secara independen.

Untuk melihat atau membatalkan langganan yang dibuat dengan parameter SupportEvent, gunakan parameter Get-EventSubscriberPaksa cmdlet dan Unregister-Event .

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

Input

None

Anda tidak dapat menyalurkan objek ke Register-ObjectEvent.

Output

None or System.Management.Automation.PSEventJob

Saat Anda menggunakan parameter Tindakan , Register-ObjectEvent mengembalikan objek System.Management.Automation.PSEventJob . Jika tidak, itu tidak menghasilkan output apa pun.

Catatan

Peristiwa, langganan peristiwa, dan antrean peristiwa hanya ada di sesi saat ini. Jika Anda menutup sesi saat ini, antrean peristiwa akan dibuang dan langganan peristiwa dibatalkan.