Register-EngineEvent

Modul:: Microsoft.PowerShell.Utility Module

Berlangganan peristiwa yang dihasilkan oleh mesin PowerShell dan oleh cmdlet New-Event.

Sintaks

Default (Default)

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

Deskripsi

Cmdlet Register-EngineEvent berlangganan peristiwa yang dihasilkan oleh mesin PowerShell dan cmdlet New-Event. Gunakan parameter SourceIdentifier untuk menentukan peristiwa.

Anda dapat menggunakan cmdlet ini untuk berlangganan OnIdle atau Keluar dari peristiwa dan peristiwa mesin yang dihasilkan oleh cmdlet . Peristiwa ini secara otomatis ditambahkan ke antrean peristiwa di sesi Anda tanpa berlangganan. Namun, berlangganan memungkinkan Anda meneruskan peristiwa, menentukan tindakan untuk merespons peristiwa, dan membatalkan langganan.

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.

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

Contoh

Contoh 1: Mendaftarkan peristiwa mesin pemrosesan PowerShell di komputer jarak jauh

Contoh ini mendaftarkan event engine PowerShell di dua komputer jarak jauh.

$S = New-PSSession -ComputerName "Server01, Server02"
Invoke-Command -Session $S {
  Register-EngineEvent -SourceIdentifier ([System.Management.Automation.PSEngineEvent]::Exiting) -Forward
}

New-PSSession membuat sesi yang dikelola pengguna (PSSession) di setiap komputer jarak jauh. Cmdlet Invoke-Command menjalankan perintah Register-EngineEvent dalam sesi jarak jauh. menggunakan parameter SourceIdentifier untuk mengidentifikasi peristiwa. Parameter Forward meminta mesin untuk meneruskan peristiwa dari sesi jarak jauh ke sesi lokal.

Contoh 2: Ambil tindakan tertentu saat peristiwa Keluar terjadi

Contoh ini memperlihatkan cara menjalankan Register-EngineEvent untuk mengambil tindakan tertentu saat peristiwa PowerShell.Keluar dari terjadi.

Register-EngineEvent -SourceIdentifier PowerShell.Exiting -SupportEvent -Action {
    Get-History | Export-Clixml $HOME\history.clixml
}

Parameter SupportEvent ditambahkan untuk menyembunyikan langganan event. Saat PowerShell keluar, dalam hal ini, riwayat perintah dari sesi keluar diekspor file XML di direktori $HOME pengguna.

Contoh 3: Membuat dan berlangganan peristiwa yang ditentukan pengguna

Contoh ini membuat langganan untuk acara dari sumber MyEventSource. Ini adalah sumber sewenang-wenang yang akan kita gunakan untuk memantau kemajuan pekerjaan. Register-EngineEvent digunakan untuk membuat langganan. Blokir skrip untuk parameter Tindakan mencatat data peristiwa ke file teks.

Register-EngineEvent -SourceIdentifier MyEventSource -Action {
    "Event: {0}" -f $Event.MessageData | Out-File C:\temp\MyEvents.txt -Append
}

Start-Job -Name TestJob -ScriptBlock {
    while ($true) {
        Register-EngineEvent -SourceIdentifier MyEventSource -Forward
        Start-Sleep -Seconds 2
        "Doing some work..."
        $newEventSplat = @{
            SourceIdentifier = 'MyEventSource'
            MessageData      = ("{0} -  Work done..." -f (Get-Date))
        }
        New-Event @newEventSplat
    }
}
Start-Sleep -Seconds 4
Get-EventSubscriber
Get-Job

SubscriptionId   : 12
SourceObject     :
EventName        :
SourceIdentifier : MyEventSource
Action           : System.Management.Automation.PSEventJob
HandlerDelegate  :
SupportEvent     : False
ForwardEvent     : False

Id     Name            PSJobTypeName   State         HasMoreData     Location             Command
--     ----            -------------   -----         -----------     --------             -------
18     MyEventSource                   Running       True                                 …
19     TestJob         BackgroundJob   Running       True            localhost            …

Register-EngineEvent membuat Id Pekerjaan 18. Start-Job membuat Id Pekerjaan 19. Di Contoh #4, kami menghapus langganan peristiwa dan pekerjaan, lalu memeriksa file log.

Contoh 4: Membatalkan pendaftaran acara dan menyelesaikan pekerjaan

Ini adalah kelanjutan dari Contoh 3. Dalam contoh ini kita menunggu selama 10 detik untuk membiarkan beberapa peristiwa terjadi. Kemudian kami mencabut langganan acara.

PS> Start-Sleep -Seconds 10
PS> Get-EventSubscriber | Unregister-Event
PS> Get-Job

Id     Name            PSJobTypeName   State         HasMoreData     Location             Command
--     ----            -------------   -----         -----------     --------             -------
18     MyEventSource                   Stopped       False                                …
19     TestJob         BackgroundJob   Running       True            localhost            …

PS> Stop-Job -Id 19
PS> Get-Job | Remove-Job
PS> Get-Content C:\temp\MyEvents.txt
Event: 2/18/2020 2:36:19 PM -  Work done...
Event: 2/18/2020 2:36:21 PM -  Work done...
Event: 2/18/2020 2:36:23 PM -  Work done...
Event: 2/18/2020 2:36:25 PM -  Work done...
Event: 2/18/2020 2:36:27 PM -  Work done...
Event: 2/18/2020 2:36:29 PM -  Work done...
Event: 2/18/2020 2:36:31 PM -  Work done...

cmdlet Unregister-Event menghentikan tugas yang terkait dengan langganan acara (Id Tugas 18). Job Id 19 masih berjalan dan membuat peristiwa baru. Kami menggunakan cmdlet untuk menghentikan pekerjaan dan menghapus objek pekerjaan yang tidak diperlukan. Get-Content menampilkan isi file log.

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 mencakup $Eventvariabel , , $EventSubscriber$Sender, $EventArgs, dan $args otomatis, yang memberikan informasi tentang peristiwa ke blok skrip Tindakan. Untuk informasi selengkapnya, lihat tentang_Variabel_Automatis.

Ketika Anda menentukan suatu tindakan, Register-EngineEvent 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

-Forward

Menunjukkan bahwa cmdlet mengirim event untuk langganan ini ke sesi pada komputer lokal. 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

-MaxTriggerCount

Menentukan jumlah maksimum berapa kali tindakan dijalankan untuk langganan peristiwa.

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

Parameter ini adalah bagian dari kelas dasar untuk semua event cmdlet. Register-EngineEvent tidak menggunakan parameter ini. Setiap data yang diteruskan ke parameter ini diabaikan.

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 pengidentifikasi sumber peristiwa tempat Anda berlangganan. Pengidentifikasi sumber harus unik dalam sesi saat ini. Parameter ini diperlukan.

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

Nilai ini spesifik pada sumber peristiwa. Ini bisa menjadi nilai arbitrer yang Anda buat untuk digunakan dengan cmdlet New-Event. Mesin PowerShell mendukung PSEngineEvent dengan nilai-nilai PowerShell.Exiting dan PowerShell.OnIdle.

Properti parameter

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

Kumpulan parameter

(All)

Position:	100
Wajib:	True
Nilai dari alur:	False
Nilai dari alur berdasarkan nama properti:	False
Nilai dari argumen yang tersisa:	False

-SupportEvent

Menunjukkan bahwa cmdlet menyembunyikan langganan acara. Tambahkan 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, tambahkan parameter Force ke cmdlet Get-EventSubscriber atau Unregister-Event.

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.

Saat berlangganan pada acara Exiting, cmdlet yang dapat dieksekusi oleh parameter Action terbatas pada cmdlet dalam modul Microsoft.PowerShell.Core dan Microsoft.PowerShell.Utility. Peristiwa Exiting hanya dijalankan ketika sesi dihentikan di bawah kendali PowerShell. Peristiwa tidak dipicu ketika aplikasi host atau jendela terminal ditutup.

Mesin dianggap diam jika tidak menjalankan saluran pipa. Peristiwa OnIdle diaktifkan ketika PowerShell menjadi tidak aktif selama 300 milidetik (ms).

Nota

Saat PSReadLine digunakan, peristiwa OnIdle diaktifkan ketika ReadKey() mengalami waktu habis (tidak ada pengetikan dalam 300ms). Peristiwa dapat disinyalir saat pengguna berada di tengah-tengah pengeditan baris perintah, misalnya, pengguna membaca bantuan untuk memutuskan parameter mana yang akan digunakan. Dimulai di PSReadLine 2.2.0-beta4, perilaku OnIdle berubah untuk memberi sinyal peristiwa hanya jika ada batas waktu ReadKey() dan buffer pengeditan saat ini kosong.

Saran dan Komentar

Apakah halaman ini membantu?

Bagikan melalui

Register-EngineEvent

Sintaks

Default (Default)

Deskripsi

Contoh

Contoh 1: Mendaftarkan peristiwa mesin pemrosesan PowerShell di komputer jarak jauh

Contoh 2: Ambil tindakan tertentu saat peristiwa Keluar terjadi

Contoh 3: Membuat dan berlangganan peristiwa yang ditentukan pengguna

Contoh 4: Membatalkan pendaftaran acara dan menyelesaikan pekerjaan

Parameter

-Action

Properti parameter

Kumpulan parameter

-Forward

Properti parameter

Kumpulan parameter

-MaxTriggerCount

Properti parameter

Kumpulan parameter

-MessageData

Properti parameter

Kumpulan parameter

-SourceIdentifier

Properti parameter

Kumpulan parameter

-SupportEvent

Properti parameter

Kumpulan parameter

CommonParameters

Input

None

Output

None

PSEventJob

Catatan

Link Terkait

Saran dan Komentar