CTRPP

Alat CTRPP adalah pra-prosesor yang mengurai dan memvalidasi manifes untuk penyedia V2 Anda. Alat ini menghasilkan .rc sumber daya dengan string yang diperlukan oleh konsumen penyedia Anda, dan menghasilkan .h header dengan kode yang Anda gunakan untuk menyediakan data penghitung Anda. Anda harus menjalankan alat CTRPP selama membangun penyedia Anda. Anda harus menggunakan kode yang dihasilkan sebagai titik awal saat mengembangkan penyedia Anda alih-alih mencoba membuat kode ini sendiri.

ctrpp -o codeFile -rc rcFile [-legacy] [-MemoryRoutines] [-NotificationCallback] [-prefix prefix] [-ch symFile] [-backcompat] inputFile

Argumen

Opsi Deskripsi
inputFile Diperlukan: Menentukan nama .man file (manifes XML) yang menentukan penghitung Anda.
-ocodeFile Diperlukan: Menentukan nama file kode yang .h akan dihasilkan oleh CTRPP. File ini akan berisi fungsi pembantu sebaris C/C++ yang menyederhanakan inisialisasi dan membatalkan inisialisasi penyedia Anda.
-rcrcFile Diperlukan: Menentukan nama (file sumber daya) yang .rc akan dihasilkan oleh CTRPP. File ini akan berisi tabel string penyedia.
-chsymFile Menentukan nama file simbol opsional .h yang akan dihasilkan oleh CTRPP. File ini akan berisi simbol C/C++ untuk nama dan GUID setiap counterset di penyedia.
-awalan awalan Menentukan awalan yang akan digunakan untuk variabel dan fungsi yang ditentukan dalam file header yang dihasilkan.
-NotificationCallback Mengubah tanda tangan default fungsi CounterInitialize untuk menyertakan parameter untuk menentukan nama fungsi panggilan balik ControlCallback, AllocateMemory, dan FreeMemory . Argumen ini memiliki efek yang sama seperti menyertakan callback atribut dalam elemen penyedia .
-migrasioutputFile Alih-alih menghasilkan .h file dan .rc , meningkatkan manifes inputFile ke versi terbaru dan menyimpannya ke outputFile. Sakelar ini tidak dapat digunakan dengan sakelar lain. Penggunaan: CTRPP -migrate NewFile.man OldFile.man
-BackCompat Usang: Dukungan untuk penyedia mode kernel ditambahkan di Windows 7. Secara default, kode yang dihasilkan oleh CTRPP untuk penyedia mode kernel tidak akan kompatibel dengan versi Windows yang lebih lama (driver akan gagal dimuat karena API yang hilang Pcw*** ). Atur -BackCompat untuk mengaktifkan kompatibilitas dengan versi Windows yang lebih lama. Driver akan secara dinamis memuat API yang diperlukan dan kode yang dihasilkan akan menonaktifkan penyedia secara diam-diam jika API tidak tersedia.
-MemoryRoutines Usang: Saat digunakan dengan -Legacy sakelar, sertakan templat untuk rutinitas memori dalam kode yang dihasilkan. Jika tidak, argumen ini memiliki efek yang sama dengan sakelar -NotificationCallback .
-Warisan Usang:*.hMenghasilkan file , *.c, *.rc, dan *_r.h menggunakan templat kode Windows Vista (menghasilkan PerfAutoInitialize dan PerfAutoCleanup alih-alih CounterInitialize dan CounterCleanup). Sakelar ini dapat digunakan dengan -MemoryRoutines dan -NotificationCallback tetapi tidak dapat digunakan dengan sakelar lain. Jangan gunakan sakelar -o atau -rc dengan sakelar ini. File yang dihasilkan akan dinamai berdasarkan nama manifes dan akan ditulis ke direktori yang berisi manifes. Penggunaan: CTRPP -legacy OldFile.man

Keterangan

Alat CTRPP menghasilkan .h file kode, .rc file sumber daya, dan secara opsional menghasilkan .h file simbol.

Menggunakan file sumber daya yang dihasilkan

Alat CTRPP akan menghasilkan .rc file sumber daya yang berisi string yang dapat dilokalkan yang diperlukan oleh konsumen dari penghitung penyedia.

Penting

Sumber daya dari file ini harus dimasukkan ke dalam biner penyedia Anda dan jalur lengkap ke biner penyedia harus didaftarkan selama penginstalan manifes penyedia Anda. Konsumen yang tidak dapat menemukan dan memuat sumber daya tidak akan dapat menggunakan penghitung penyedia Anda.

Sumber daya string harus ditangani sebagai berikut:

  • Pengembang mengedit file manifes penyedia (.man) untuk mengatur applicationIdentity atribut penyedia ke nama biner penyedia (.DLL, .SYS, atau .EXE) yang akan berisi sumber daya string untuk penyedia dan akan diinstal sebagai bagian dari komponen penyedia.
  • Alat CTRPP membaca manifes penyedia dan menghasilkan .rc file.
  • Alat RC (pengkompilasi sumber daya) mengkompilasi data dari file yang dihasilkan .rc CTRPP untuk menghasilkan file yang .res berisi sumber daya biner. Ini dapat dilakukan baik dengan langsung mengkompilasi file yang dihasilkan .rc CTRPP ATAU dengan mengkompilasi file lain .rc yang menyertakan file yang dihasilkan .rc CTRPP melalui #include arahan.
  • Linker menyematkan data dari file yang dihasilkan .res RC ke dalam biner penyedia.
  • Selama penginstalan, biner penyedia disalin ke sistem pengguna dan manifes penyedia terdaftar menggunakan alat lodctr. Alat lodctr mengonversi applicationIdentity atribut manifes penyedia menjadi jalur lengkap dan merekam jalur lengkap ke biner penyedia di registri.
    • Jika biner penyedia berada dalam direktori yang sama dengan manifes, gunakan: lodctr.exe /m:"C:\full\manifest\path\manifest.man". lodctr akan menggabungkan jalur manifes yang ditentukan dengan atribut manifes applicationIdentity untuk membentuk jalur lengkap.
    • Jika tidak, gunakan lodctr.exe /m:"C:\full\manifest\path\manifest.man" "c:\full\binary\path". lodctr akan menggabungkan jalur biner yang ditentukan dengan atribut manifes applicationIdentity untuk membentuk jalur lengkap.
    • Untuk tujuan diagnostik, Anda dapat memeriksa jalur lengkap yang direkam dengan memeriksa ApplicationIdentity nilai kunci HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\_V2Providers\{<ProviderGuid>}registri .
    • Jika biner menggunakan MUI untuk pelokalan, pastikan untuk menyalin file MUI bersama dengan biner.
  • Selama pengumpulan counterset, konsumen menggunakan jalur lengkap yang direkam ke biner penyedia untuk menemukan dan memuat string yang diperlukan dari sumber daya biner penyedia.

Menggunakan file kode yang dihasilkan di penyedia mode pengguna

Alat CTRPP akan menghasilkan .h file kode C/C++. Jika atribut manifes providerType penyedia diatur ke userMode, file kode yang dihasilkan akan berisi definisi berikut yang berguna dalam pengkodean penyedia mode pengguna:

  • Fungsi inisialisasi penyedia bernama awalanCounterInitialize.
  • Fungsi pembersihan penyedia bernama awalanCounterCleanup.
  • Variabel penyedia global yang menyimpan handel penyedia yang dibuka oleh fungsi AwalanCounterInitialize . Nama variabel adalah nilai symbol atribut provider elemen dalam manifes. Variabel ini harus digunakan dalam panggilan ke PerfCreateInstance, PerfDeleteInstance, dan API lainnya untuk mengontrol data penyedia Anda.
  • Untuk setiap counterset, variabel GUID counterset global dengan GUID counterset. Nama variabel adalah nilai counterSet atribut elemen symbol ditambah akhiran "GUID", misalnya MyCounterSetGUID. Variabel ini harus digunakan dalam panggilan ke PerfCreateInstance, PerfDeleteInstance, dan API lainnya untuk mengontrol data penyedia Anda.
  • Untuk setiap penghitung, makro penghitung dengan nilai penghitung id . Nama makro adalah nilai counter atribut elemen symbol . Makro ini harus digunakan dalam panggilan ke PerfSetCounterRefValue, PerfSetULongLongCounterValue, dan API lainnya untuk mengatur data penyedia Anda.

Dalam nama fungsi, awalan mengacu pada nilai -prefix parameter baris perintah. -prefix Jika parameter tidak digunakan, fungsi akan diberi nama CounterInitialize dan CounterCleanup.

Menggunakan file kode yang dihasilkan di penyedia mode kernel

Alat CTRPP akan menghasilkan .h file kode C/C++. Jika atribut manifes providerType penyedia diatur ke kernelMode, file kode yang dihasilkan akan berisi definisi berikut yang berguna dalam pengkodean penghitung penyedia mode kernel:

  • Fungsi inisialisasi counterset bernama awalanRegisterCounterset. Fungsi ini mengisi struktur RegInfo kemudian memanggil PcwRegister, menempatkan handel pendaftaran counterset yang dihasilkan ke dalam variabel Counterset global.
  • Fungsi pembersihan counterset bernama awalanUnregisterCounterset. Fungsi ini memanggil PcwUnregister pada handel pendaftaran counterset dalam variabel Counterset global.
  • Fungsi pembuatan instans bernama prefiksCreateCounterset. Fungsi ini mengisi array struktur PcwData lalu memanggil PcwCreateInstance menggunakan handel pendaftaran counterset dalam variabel Counterset global.
  • Fungsi pembersihan instans bernama prefiksCloseCounterset. Fungsi ini memanggil PcwCloseInstance.
  • Fungsi pelaporan instans bernama awalanTambahkanCounterset yang akan digunakan dari fungsi panggilan balik counterset. Fungsi ini mengisi array struktur PcwData lalu memanggil PcwAddInstance.
  • Windows SDK 20H1 dan yang lebih baru: Fungsi inisialisasi RegInfo bernama awalanInitRegistrationInformationCounterset untuk digunakan dalam skenario tingkat lanjut. Fungsi ini mengisi struktur RegInfo . Fungsi ini dapat digunakan dalam kasus di mana awalanyang dihasilkan RegisterCounterset tidak memenuhi kebutuhan Anda, misalnya ketika Anda ingin menyesuaikan nilai dalam struktur RegInfo atau ketika Anda ingin menyimpan handel yang dikembalikan dalam variabel lain.

Dalam nama fungsi, awalan mengacu pada nilai -prefix parameter baris perintah. -prefix Jika parameter tidak digunakan, fungsi tidak akan memiliki awalan.

Catatan

Fungsi TambahkanCountersetprefiks yang dihasilkan digunakan saat Anda memiliki panggilan balik counterset. Prefiksyang dihasilkan MembuatCounterset dan awalanFungsi CloseCounterset digunakan ketika Anda tidak memiliki panggilan balik counterset.

Menggunakan file simbol yang dihasilkan

Jika parameter -ch ditentukan pada baris perintah, alat CTRPP akan menghasilkan .h file simbol. File ini berisi simbol C/C++ untuk nama dan GUID dari setiap counterset di penyedia. Simbol dapat digunakan saat menulis program yang dikodekan secara permanen untuk mengonsumsi data dari counterset ini menggunakan fungsi Konsumen PerfLib V2.

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung Windows Server 2008 [hanya aplikasi desktop]