Register-EngineEvent

  • Referensi
Modul:
Microsoft.PowerShell.Utility

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

Sintaks

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

Deskripsi

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

Anda dapat menggunakan cmdlet ini untuk berlangganan peristiwa dan peristiwa mesin OnIdle atau Keluar yang dihasilkan oleh New-Event 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, 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.

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

Contoh

Contoh 1: Mendaftarkan peristiwa mesin PowerShell di komputer jarak jauh

Contoh ini mendaftar untuk peristiwa mesin 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) pada setiap komputer jarak jauh. Invoke-Command Cmdlet menjalankan Register-EngineEvent perintah dalam sesi jarak jauh. Register-EngineEventmenggunakan 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.Exiting terjadi.

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

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

Contoh 3: Membuat dan berlangganan peristiwa yang ditentukan pengguna

Contoh ini membuat langganan untuk peristiwa 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..."
        New-Event -SourceIdentifier MyEventSource -Message ("{0} -  Work done..." -f (Get-Date))
    }
}
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 Id Pekerjaan yang dibuat 18. Start-Job Id Pekerjaan yang dibuat 19. Di Contoh #4, kami menghapus langganan peristiwa dan pekerjaan, lalu memeriksa file log.

Contoh 4: Membatalkan pendaftaran peristiwa dan membersihkan pekerjaan

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

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...

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

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 , , $Sender$EventSubscriber, $EventArgs, dan $Args otomatis, yang memberikan informasi tentang peristiwa ke blok Skrip tindakan. Untuk informasi selengkapnya, lihat about_Automatic_Variables.

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

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

-Forward

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

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

-MaxTriggerCount

Menentukan berapa kali tindakan dijalankan untuk langganan peristiwa.

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

-MessageData

Menentukan data tambahan yang terkait dengan peristiwa. Nilai parameter ini muncul di properti MessageData objek peristiwa.

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

-SourceIdentifier

Menentukan pengidentifikasi sumber peristiwa tempat Anda berlangganan. Pengidentifikasi sumber harus unik dalam sesi saat ini. Parameter ini diperlukan.

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

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

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

-SupportEvent

Menunjukkan bahwa cmdlet menyembunyikan langganan peristiwa. 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 Paksa ke Get-EventSubscriber cmdlet atau Unregister-Event .

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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 saat ini, antrean peristiwa akan dibuang dan langganan acara dibatalkan.

Saat berlangganan peristiwa Keluar , cmdlet yang dapat dijalankan oleh parameter Tindakan dibatasi 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 alur. Peristiwa OnIdle diaktifkan ketika PowerShell telah menganggur selama 300 milidetik (ms).

Catatan

Ketika PSReadLine digunakan, peristiwa OnIdle diaktifkan ketika ReadKey() 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 ReadKey() batas waktu dan buffer pengeditan saat ini kosong.