Bagikan melalui

Register-ObjectEvent

Modul:
Microsoft.PowerShell.Utility Module

Berlangganan ke peristiwa yang dihasilkan oleh objek Microsoft .NET Framework.

Sintaks

Default (Default) 

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

Deskripsi

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

Ketika acara langganan diaktifkan, itu ditambahkan ke antrean acara di sesi Anda. Untuk mendapatkan acara dalam antrian acara, gunakan cmdlet Get-Event.

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 Penerusan untuk mengirim peristiwa jarak jauh ke antrean peristiwa di sesi lokal.

Saat Anda berlangganan acara, pendaftar acara ditambahkan ke dalam sesi Anda. Untuk mendapatkan pendaftar acara dalam sesi, gunakan cmdlet Get-EventSubscriber. Untuk membatalkan langganan, gunakan cmdlet Unregister-Event, yang menghapus subskriptor acara 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 tersebut 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. Sebagai gantinya, tindakan merespons peristiwa tersebut. Dalam contoh ini, ketika peristiwa pembuatan instans dinaikkan yang menunjukkan bahwa proses baru dimulai, peristiwa ProcessCreated baru akan 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 variabel otomatis $Sender dan $EventArgs 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 tentang_Pekerjaan.

Contoh 3: Berlangganan peristiwa objek di komputer jarak jauh

Contoh ini menunjukkan cara berlangganan peristiwa objek di komputer jarak jauh. Contoh ini menggunakan fungsi Enable-ProcessCreationEvent yang ditentukan dalam file skrip ProcessCreationEvent.ps1. 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 variabel $S. Selanjutnya, cmdlet Invoke-Command menjalankan skrip ProcessCreationEvent.ps1 di masing-masing PSSessions di $S. Tindakan ini membuat fungsi Enable-ProcessCreationEvent dalam sesi jarak jauh. Terakhir, kita menjalankan fungsi Enable-ProcessCreationEvent dalam sesi jarak jauh.

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

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 buatdan aktifkan objek timer, lalu atur interval timer ke 500 (milidetik). Cmdlet mendaftarkan peristiwa Berlalu dari objek timer. Objek PSEventJob disimpan dalam variabel dan juga tersedia di properti Tindakan pelanggan peristiwa. Untuk informasi selengkapnya, lihatGet-EventSubscriber .

Setiap kali interval timer berlalu, peristiwa dinaikkan dan tindakan dijalankan. Dalam hal ini, cmdlet Get-Random menghasilkan angka acak antara 0 dan 100 dan menyimpannya dalam variabel $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 memiliki properti Modul yang berisi modul skrip dinamis yang mengimplementasikan tindakan. Menggunakan operator panggilan (&), kami memanggil perintah dalam modul untuk menampilkan nilai variabel $Random.

Untuk informasi selengkapnya tentang modul, lihat about_Modules.

Parameter

-Action

Menentukan perintah untuk menangani peristiwa. Perintah dalam Tindakan dijalankan saat peristiwa diaktifkan, alih-alih mengirim peristiwa tersebut ke antrean peristiwa. Sertakan perintah dalam kurung kurawal ({}) untuk membuat blokir skrip.

Nilai parameter Tindakan dapat menyertakan variabel otomatis , , , , dan otomatis. Variabel ini memberikan informasi tentang peristiwa ke blokir skrip Tindakan . Untuk informasi selengkapnya, lihat tentang_Variabel_Automatis.

Ketika Anda menentukan suatu tindakan, Register-ObjectEvent akan mengembalikan objek tugas acara yang mewakili tindakan tersebut. Anda dapat menggunakan Job cmdlets untuk mengelola job acara.

Properti parameter

Jenis:ScriptBlock
Nilai default:None
Mendukung wildcard:False
DontShow:False

Kumpulan parameter

(All)
Position:101
Wajib:False
Nilai dari alur:False
Nilai dari alur berdasarkan nama properti:False
Nilai dari argumen yang tersisa:False

-EventName

Menentukan peristiwa yang Anda berlangganan.

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

Properti parameter

Jenis:String
Nilai default:None
Mendukung wildcard:False
DontShow:False

Kumpulan parameter

(All)
Position:1
Wajib:True
Nilai dari alur:False
Nilai dari alur berdasarkan nama properti:False
Nilai dari argumen yang tersisa: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.

Properti parameter

Jenis:SwitchParameter
Nilai default:None
Mendukung wildcard:False
DontShow:False

Kumpulan parameter

(All)
Position:Named
Wajib:False
Nilai dari alur:False
Nilai dari alur berdasarkan nama properti:False
Nilai dari argumen yang tersisa:False

-InputObject

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

Properti parameter

Jenis:PSObject
Nilai default:None
Mendukung wildcard:False
DontShow:False

Kumpulan parameter

(All)
Position:0
Wajib:True
Nilai dari alur:False
Nilai dari alur berdasarkan nama properti:False
Nilai dari argumen yang tersisa:False

-MaxTriggerCount

Menentukan berapa kali peristiwa dapat dipicu.

Properti parameter

Jenis:Int32
Nilai default:None
Mendukung wildcard:False
DontShow:False

Kumpulan parameter

(All)
Position:Named
Wajib:False
Nilai dari alur:False
Nilai dari alur berdasarkan nama properti:False
Nilai dari argumen yang tersisa:False

-MessageData

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

Properti parameter

Jenis:PSObject
Nilai default:None
Mendukung wildcard:False
DontShow:False

Kumpulan parameter

(All)
Position:Named
Wajib:False
Nilai dari alur:False
Nilai dari alur berdasarkan nama properti:False
Nilai dari argumen yang tersisa: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 objek pelanggan dan semua objek peristiwa yang terkait dengan langganan ini.

Properti parameter

Jenis:String
Nilai default:None
Mendukung wildcard:False
DontShow:False

Kumpulan parameter

(All)
Position:100
Wajib:False
Nilai dari alur:False
Nilai dari alur berdasarkan nama properti:False
Nilai dari argumen yang tersisa:False

-SupportEvent

Menunjukkan bahwa cmdlet menyembunyikan langganan acara. 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 Force dari cmdlet dan .

Properti parameter

Jenis:SwitchParameter
Nilai default:None
Mendukung wildcard:False
DontShow:False

Kumpulan parameter

(All)
Position:Named
Wajib:False
Nilai dari alur:False
Nilai dari alur berdasarkan nama properti:False
Nilai dari argumen yang tersisa:False

CommonParameters

Cmdlet ini mendukung parameter umum: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, dan -WarningVariable. Untuk informasi selengkapnya, lihat about_CommonParameters.

Input

None

Anda tidak dapat menyalurkan objek ke cmdlet ini.

Output

None

Secara default, cmdlet ini tidak mengembalikan output.

PSEventJob

Saat Anda menggunakan parameter Tindakan , cmdlet ini mengembalikan objek PSEventJob.

Catatan

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