Register-EngineEvent

Referensi

Modul:: Microsoft.PowerShell.Utility

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

Sintaks

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 peristiwa (event) dalam antrean peristiwa (event queue), gunakan cmdlet Get-Event.

Contoh

Contoh 1: Mendaftarkan kejadian mesin 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 Teruskan memberi tahu 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. Blok 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 membersihkan tugas

Ini adalah kelanjutan dari Contoh 3. Dalam contoh ini kita menunggu selama 10 detik untuk membiarkan beberapa peristiwa terjadi. Kemudian kami membatalkan pendaftaran event.

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 pekerjaan yang terkait dengan langganan acara (ID Pekerjaan 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 Aksi dijalankan ketika suatu kejadian terjadi, alih-alih mengirim kejadian tersebut ke antrean kejadian. Sertakan perintah dalam kurung kurawal ({}) untuk membuat blok skrip.

Nilai parameter Tindakan dapat mencakup , , , , dan variabel otomatis , yang memberikan informasi tentang peristiwa ke blok skrip Tindakan . Untuk informasi lebih lanjut, lihat about_Automatic_Variables.

Ketika Anda menentukan suatu tindakan, Register-EngineEvent akan mengembalikan objek tugas acara yang mewakili tindakan tersebut. Anda dapat menggunakan cmdlet Pekerjaan untuk mengelola pekerjaan acara.

Jenis:	ScriptBlock
Position:	101
Nilai default:	None
Diperlukan:	False
Terima input alur:	False
Terima karakter wildcard:	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.

Jenis:	SwitchParameter
Position:	Named
Nilai default:	None
Diperlukan:	False
Terima input alur:	False
Terima karakter wildcard:	False

-MaxTriggerCount

Menentukan jumlah maksimum berapa kali tindakan dijalankan untuk langganan peristiwa.

Jenis:	Int32
Position:	Named
Nilai default:	None
Diperlukan:	False
Terima input alur:	False
Terima karakter wildcard:	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.

Jenis:	PSObject
Position:	Named
Nilai default:	None
Diperlukan:	False
Terima input alur:	False
Terima karakter wildcard:	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 terkait dengan sumber peristiwa tersebut. 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.

Jenis:	String
Position:	100
Nilai default:	None
Diperlukan:	True
Terima input alur:	False
Terima karakter wildcard:	False

-SupportEvent

Menunjukkan bahwa cmdlet menyembunyikan pemesanan event. 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.

Jenis:	SwitchParameter
Position:	Named
Nilai default:	None
Diperlukan:	False
Terima input alur:	False
Terima karakter wildcard:	False

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, antrian peristiwa akan dibuang dan langganan acara dibatalkan.

Ketika berlangganan acara Keluar, cmdlet yang dapat dijalankan oleh parameter Tindakan terbatas pada cmdlet dalam modul Microsoft.PowerShell.Core dan Microsoft.PowerShell.Utility. Peristiwa Keluar hanya diaktifkan ketika sesi keluar di bawah kendali PowerShell. Peristiwa tidak diaktifkan ketika aplikasi host atau jendela terminal ditutup.

Mesin dianggap menganggur jika tidak menjalankan pipeline. Peristiwa OnIdle terjadi ketika PowerShell tidak aktif selama 300 milidetik (md).

Nota

Saat PSReadLine digunakan, peristiwa OnIdle diaktifkan ketika ReadKey() mengalami waktu habis (kurang dari 300ms tanpa pengetikan). 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.

Bagikan melalui