Pembuatan Skrip C++ Model Data Debugger
Topik ini menjelaskan cara menggunakan skrip Debugger Data Model C++ Debugger Data Model C++ untuk mendukung otomatisasi dengan mesin debugger menggunakan pembuatan skrip.
Manajemen Skrip dalam Model Data Debugger
Selain peran Manajer Model Data sebagai otoritas pusat tentang pembuatan dan ekstensibilitas objek, ia juga bertanggung jawab atas pengelolaan konsep abstrak skrip. Dari perspektif bagian Manajer Skrip dari Manajer Model Data, skrip adalah sesuatu yang dapat dimuat, dibongkar, dan berpotensi di-debug secara dinamis oleh penyedia untuk memperluas atau menyediakan fungsionalitas baru ke model data.
Penyedia skrip adalah komponen yang menjenjang bahasa (misalnya: NatVis, JavaScript, dll...) ke model data. Ini mendaftarkan satu atau beberapa ekstensi file (misalnya: ". NatVis", ".js") yang ditangani oleh penyedia yang memungkinkan klien debugger atau antarmuka pengguna untuk memungkinkan pemuatan file skrip dengan ekstensi tertentu tersebut oleh delegasi ke penyedia.
Manajer Skrip Inti: IDataModelScriptManager
Antarmuka manajer skrip inti didefinisikan sebagai berikut.
DECLARE_INTERFACE_(IDataModelScriptManager, IUnknown)
{
STDMETHOD(GetDefaultNameBinder)(_COM_Outptr_ IDataModelNameBinder **ppNameBinder) PURE;
STDMETHOD(RegisterScriptProvider)(_In_ IDataModelScriptProvider *provider) PURE;
STDMETHOD(UnregisterScriptProvider)(_In_ IDataModelScriptProvider *provider) PURE;
STDMETHOD(FindProviderForScriptType)(_In_ PCWSTR scriptType, _COM_Outptr_ IDataModelScriptProvider **provider) PURE;
STDMETHOD(FindProviderForScriptExtension)(_In_ PCWSTR scriptExtension, _COM_Outptr_ IDataModelScriptProvider **provider) PURE;
STDMETHOD(EnumerateScriptProviders)(_COM_Outptr_ IDataModelScriptProviderEnumerator **enumerator) PURE;
}
Metode GetDefaultNameBinder mengembalikan pengikat nama skrip default model data. Pengikat nama adalah komponen yang menyelesaikan nama dalam konteks objek. Misalnya, mengingat ekspresi "foo.bar", pengikat nama dipanggil untuk menyelesaikan bilah nama dalam konteks foo objek. Pengikat yang dikembalikan di sini mengikuti serangkaian aturan default untuk model data. Penyedia skrip dapat menggunakan pengikat ini untuk memberikan konsistensi dalam resolusi nama di seluruh penyedia.
Metode RegisterScriptProvider menginformasikan model data bahwa penyedia skrip baru ada yang mampu menjepit bahasa baru ke model data. Ketika metode ini dipanggil, manajer skrip akan segera memanggil kembali penyedia skrip yang diberikan dan menanyakan properti skrip yang dikelolanya. Jika sudah ada penyedia yang terdaftar dengan nama atau ekstensi file yang ditunjukkan oleh penyedia skrip yang diberikan, metode ini akan gagal. Hanya penyedia skrip tunggal yang dapat didaftarkan sebagai handler untuk nama atau ekstensi file tertentu.
Metode UnregisterScriptProvider membatalkan panggilan ke metode RegisterScriptProvider. Nama dan ekstensi file yang diberikan oleh penyedia skrip yang diinpass tidak akan lagi dikaitkan dengannya. Penting untuk dicatat bahwa mungkin ada sejumlah besar referensi COM yang luar biasa ke penyedia skrip bahkan setelah tidak diregistrasi. Metode ini hanya mencegah pemuatan/pembuatan skrip jenis yang dikelola penyedia skrip tertentu. Jika skrip yang dimuat oleh penyedia tersebut masih dimuat atau telah memanipulasi model objek debugger (atau model data), manipulasi tersebut mungkin masih memiliki referensi kembali ke dalam skrip. Mungkin ada model data, metode, atau objek yang secara langsung mereferensikan konstruksi dalam skrip. Penyedia skrip harus siap untuk menanganinya.
Metode FindProviderForScriptType mencari manajer skrip untuk penyedia yang memiliki string jenis skrip seperti yang ditunjukkan dalam metode ini. Jika tidak dapat ditemukan, metode ini akan gagal; jika tidak, penyedia skrip tersebut akan dikembalikan ke pemanggil.
Metode EnumerateScriptProviders akan mengembalikan enumerator yang akan menghitung setiap penyedia skrip yang telah terdaftar di manajer skrip melalui panggilan sebelumnya ke metode RegisterScriptProvider.
Enumerasi Penyedia Skrip: IDataModelScriptProviderEnumerator
Metode EnumerateScriptProviders akan mengembalikan enumerator formulir berikut:
DECLARE_INTERFACE_(IDataModelScriptProviderEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_COM_Outptr_ IDataModelScriptProvider **provider) PURE;
}
Metode Reset akan memindahkan enumerator ke posisi sebelum mengembalikan elemen pertama.
Metode GetNext akan memindahkan enumerator ke depan satu elemen dan mengembalikan penyedia skrip yang ada di elemen tersebut. Ketika enumerator mencapai akhir enumerasi, E_BOUNDS akan dikembalikan. Memanggil metode GetNext setelah menerima kesalahan ini akan terus mengembalikan E_BOUNDS tanpa batas waktu.
Antarmuka Host C++ Model Data Debugger untuk Pembuatan Skrip
Peran Host dalam Pembuatan Skrip
Host debug mengekspos serangkaian antarmuka tingkat yang sangat rendah untuk memahami sifat sistem jenis target debugnya, mengevaluasi ekspresi dalam bahasa target debugnya, dll... Biasanya, itu tidak peduli dengan konstruksi tingkat yang lebih tinggi seperti pembuatan skrip. Hal tersebut diserahkan ke aplikasi debugger keseluruhan atau ke ekstensi yang menyediakan kemampuan ini. Namun, ada pengecualian untuk ini. Setiap host debug yang ingin berpartisipasi dalam pengalaman pembuatan skrip keseluruhan yang diberikan oleh model data perlu menerapkan beberapa antarmuka sederhana untuk memberikan konteks ke skrip. Akibatnya, host debug memegang kendali di mana ia ingin lingkungan pembuatan skrip menempatkan fungsi dan skrip lain yang disediakan fungsionalitas dalam namespace model data. Terlibat dalam proses ini memungkinkan host untuk mengizinkan (atau tidak) penggunaan fungsi tersebut, misalnya, evaluator ekspresinya. Antarmuka yang terlibat dari perspektif host di sini adalah:
| Antarmuka | Deskripsi |
|---|---|
| IDebugHostScriptHost | Antarmuka yang menunjukkan kemampuan host debug untuk mengambil bagian dalam lingkungan pembuatan skrip. Antarmuka ini memungkinkan pembuatan konteks yang menginformasikan mesin pembuatan skrip tempat menempatkan objek. |
| IDataModelScriptHostContext | Antarmuka host yang digunakan oleh penyedia skrip sebagai kontainer untuk konten skrip. Bagaimana isi permukaan skrip selain manipulasi yang dilakukannya ke model objek aplikasi debugger hingga host debug tertentu. Antarmuka ini memungkinkan penyedia skrip untuk mendapatkan informasi tentang di mana menempatkan isinya. Lihat Model Data Antarmuka Pembuatan Skrip C++ nanti dalam topik ini untuk informasi selengkapnya. |
Host Skrip Host Debug: IDebugHostScriptHost
Antarmuka IDebugHostScriptHost adalah antarmuka yang digunakan oleh penyedia skrip untuk mendapatkan konteks dari host debug untuk skrip yang baru dibuat. Konteks ini mencakup objek (disediakan oleh host debug) di mana penyedia skrip dapat menempatkan jembatan apa pun antara model data dan lingkungan pembuatan skrip. Jembatan seperti itu mungkin, misalnya, menjadi metode model data yang memanggil fungsi skrip. Melakukan ini memungkinkan pemanggil di sisi model data untuk memanggil metode skrip dengan pemanfaatan metode Panggilan pada antarmuka IModelMethod.
Antarmuka IDebugHostScriptHost didefinisikan sebagai berikut.
DECLARE_INTERFACE_(IDebugHostScriptHost, IUnknown)
{
STDMETHOD(CreateContext)(_In_ IDataModelScript* script, _COM_Outptr_ IDataModelScriptHostContext** scriptContext) PURE;
}
Metode CreateContext dipanggil oleh penyedia skrip untuk membuat konteks baru untuk menempatkan konten skrip. Konteks tersebut diwakili oleh antarmuka IDataModelScriptHostContext yang dijelaskan secara rinci pada halaman Antarmuka Pembuatan Skrip C++ Model Data.
Antarmuka Pembuatan Skrip Model Data Debugger C++
Antarmuka Skrip dan Skrip
Arsitektur keseluruhan model data memungkinkan pihak ketiga untuk menentukan jembatan antara beberapa bahasa dan model objek model data. Biasanya, bahasa yang disambungkan adalah bahasa skrip karena lingkungan model data sangat dinamis. Komponen yang menentukan dan mengimplementasikan jembatan ini antara bahasa dan model objek model data disebut penyedia skrip. Ketika diinisialisasi, penyedia skrip mendaftarkan dirinya dengan bagian manajer skrip dari manajer model data dan antarmuka apa pun yang mengelola ekstensibilitas kemudian akan memungkinkan pengeditan, pemuatan, bongkar muat, dan berpotensi men-debug skrip yang ditulis ke bahasa yang dikelola penyedia skrip.
Perhatikan bahwa Alat Debugging untuk Windows saat ini mendefinisikan dua penyedia skrip.
- Penyedia NatVis. Penyedia ini disematkan dalam DbgEng.dll dan jembatan antara XML NatVis dan model data, memungkinkan visualisasi jenis data asli/bahasa.
- Penyedia JavaScript. Penyedia ini terkandung dalam ekstensi debugger warisan: JsProvider.dll. Ini menjembatani antara skrip yang ditulis dalam bahasa JavaScript dan model data, memungkinkan bentuk kontrol debugger dan ekstensibilitas sewenang-wenang.
Penyedia baru dapat ditulis yang menjenuhkan bahasa lain (misalnya: Python, dll...) ke model data. Hal tersebut saat ini akan dienkapsulasi dalam ekstensi debugger warisan untuk tujuan pemuatan. Penyedia skrip itu sendiri harus meminimalkan dependensi dengan antarmuka mesin lama dan hanya boleh menggunakan API model data jika memungkinkan. Ini akan memungkinkan penyedia untuk dibuat portabel ke lingkungan lain dengan kemudahan yang jauh lebih besar.
Ada dua kelas antarmuka yang terkait dengan penyedia skrip. Kelas antarmuka pertama adalah untuk manajemen umum penyedia skrip dan skrip yang mereka kelola. Kelas kedua antarmuka adalah untuk mendukung penelusuran kesalahan skrip. Meskipun dukungan untuk set pertama adalah wajib, dukungan untuk yang kedua bersifat opsional dan mungkin tidak masuk akal untuk setiap penyedia.
Antarmuka manajemen umum adalah:
| Antarmuka | Deskripsi |
|---|---|
| IDataModelScriptProvider | Antarmuka inti yang harus diterapkan penyedia skrip. Ini adalah antarmuka yang terdaftar dengan bagian manajer skrip dari manajer model data untuk mengiklankan dukungan penyedia dari jenis skrip tertentu dan mendaftar terhadap ekstensi file tertentu |
| IDataModelScript | Abstraksi skrip tertentu yang sedang dikelola oleh penyedia. Setiap skrip yang dimuat atau diedit memiliki instans IDataModelScript terpisah |
| IDataModelScriptClient | Antarmuka klien yang digunakan oleh penyedia skrip untuk mengomunikasikan informasi ke antarmuka pengguna. Penyedia skrip tidak mengimplementasikan antarmuka ini. Aplikasi yang menghosting model data yang ingin menggunakan penyedia skrip. Penyedia skrip akan memanggil metode klien skrip untuk melaporkan status, kesalahan, dll... |
| IDataModelScriptHostContext | Antarmuka host yang digunakan oleh penyedia skrip sebagai kontainer untuk konten skrip. Bagaimana konten permukaan skrip selain manipulasi yang dilakukannya ke model objek aplikasi debugger hingga host debug tertentu. Antarmuka ini memungkinkan penyedia skrip untuk mendapatkan informasi tentang tempat menempatkan kontennya. |
| IDataModelScriptTemplate | Penyedia skrip dapat menyediakan satu atau beberapa templat yang berfungsi sebagai titik awal bagi pengguna untuk menulis skrip. Aplikasi debugger yang menyediakan editor bawaan dapat mengisi skrip baru dengan konten templat seperti yang diiklankan oleh penyedia melalui antarmuka ini. |
| IDataModelScriptTemplateEnumerator | Antarmuka enumerator yang diterapkan penyedia skrip untuk mengiklankan semua berbagai templat yang didukungnya. |
| IDataModelNameBinder | Pengikat nama -- objek yang dapat mengaitkan nama dalam konteks dengan nilai. Untuk ekspresi tertentu seperti "foo.bar", pengikat nama dapat mengikat nama "bar" dalam konteks objek "foo" dan menghasilkan nilai atau referensi ke dalamnya. Pengikat nama biasanya tidak diimplementasikan oleh penyedia skrip; sebaliknya, pengikat default dapat diperoleh dari model data dan digunakan oleh penyedia skrip |
Antarmuka debug adalah:
| Antarmuka | Deskripsi |
|---|---|
| IDataModelScriptDebug | Antarmuka inti yang harus disediakan penyedia skrip agar skrip dapat di-debug. Kelas implementasi antarmuka IDataModelScript harus QueryInterface untuk IDataModelScriptDebug jika skrip dapat di-debug. |
| IDataModelScriptDebugClient | Antarmuka pengguna yang ingin menyediakan kemampuan penelusuran kesalahan skrip mengimplementasikan antarmuka IDataModelScriptDebugClient. Penyedia skrip menggunakan antarmuka ini untuk meneruskan informasi debug bolak-balik (misalnya: peristiwa yang terjadi, titik henti, dll...) |
| IDataModelScriptDebugStack | Penyedia skrip mengimplementasikan antarmuka ini untuk mengekspos gagasan tumpukan panggilan ke debugger skrip. |
| IDataModelScriptDebugStackFrame | Penyedia skrip mengimplementasikan antarmuka ini untuk mengekspos gagasan bingkai tumpukan tertentu dalam tumpukan panggilan. |
| IDataModelScriptDebugVariableSetEnumerator | Penyedia skrip mengimplementasikan antarmuka ini untuk mengekspos sekumpulan variabel. Set ini dapat mewakili sekumpulan parameter ke fungsi, set variabel lokal, atau set variabel dalam cakupan tertentu. Arti yang tepat tergantung pada bagaimana antarmuka diperoleh. |
| IDataModelScriptDebugBreakpoint | Penyedia skrip mengimplementasikan antarmuka ini untuk mengekspos gagasan dan kontrol titik henti tertentu dalam skrip. |
| IDataModelScriptDebugBreakpointEnumerator | Penyedia skrip mengimplementasikan ini untuk menghitung semua titik henti yang saat ini ada dalam skrip (baik diaktifkan atau tidak). |
Penyedia Skrip Inti: IDataModelScriptProvider
Ekstensi apa pun yang ingin menjadi penyedia skrip harus menyediakan implementasi antarmuka IDataModelScriptProvider dan mendaftarkannya dengan bagian manajer skrip manajer model data melalui metode RegisterScriptProvider. Antarmuka inti ini yang harus diimplementasikan didefinisikan sebagai berikut.
DECLARE_INTERFACE_(IDataModelScriptProvider, IUnknown)
{
STDMETHOD(GetName)(_Out_ BSTR *name) PURE;
STDMETHOD(GetExtension)(_Out_ BSTR *extension) PURE;
STDMETHOD(CreateScript)(_COM_Outptr_ IDataModelScript **script) PURE;
STDMETHOD(GetDefaultTemplateContent)(_COM_Outptr_ IDataModelScriptTemplate **templateContent) PURE;
STDMETHOD(EnumerateTemplates)(_COM_Outptr_ IDataModelScriptTemplateEnumerator **enumerator) PURE;
}
Metode GetName mengembalikan nama jenis (atau bahasa) skrip yang dikelola penyedia sebagai string yang dialokasikan melalui metode SysAllocString. Pemanggil bertanggung jawab untuk membebaskan string yang dikembalikan melalui SysFreeString. Contoh string yang mungkin dikembalikan dari metode ini adalah "JavaScript" atau "NatVis". String yang dikembalikan kemungkinan akan muncul di antarmuka pengguna aplikasi debugger yang menghosting model data. Tidak ada dua penyedia skrip yang dapat mengembalikan nama yang sama (tidak peka huruf besar/kecil).
Metode GetExtension mengembalikan ekstensi file untuk skrip yang dikelola oleh penyedia ini (tanpa titik) sebagai string yang dialokasikan melalui metode SysAllocString. Aplikasi debugger yang menghosting model data (dengan dukungan skrip) akan mendelegasikan pembukaan file skrip dengan ekstensi ini ke penyedia skrip. Pemanggil bertanggung jawab untuk membebaskan string yang dikembalikan melalui SysFreeString. Contoh string yang mungkin dikembalikan dari metode ini adalah "js" atau "NatVis".
Metode CreateScript dipanggil untuk membuat skrip baru. Penyedia skrip harus mengembalikan skrip baru dan kosong yang diwakili oleh antarmuka IDataModelScript yang dikembalikan setiap kali metode ini dipanggil. Perhatikan bahwa metode ini dipanggil terlepas dari apakah antarmuka pengguna membuat skrip kosong baru untuk diedit oleh pengguna atau apakah aplikasi debugger memuat skrip dari disk. Penyedia tidak terlibat dalam I/O file. Ini hanya menangani permintaan dari aplikasi hosting melalui aliran yang diteruskan ke metode di IDataModelScript.
Metode GetDefaultTemplateContent mengembalikan antarmuka untuk konten templat default penyedia. Ini adalah konten yang ingin diisi sebelumnya oleh penyedia skrip di jendela edit untuk skrip yang baru dibuat. Jika penyedia skrip tidak memiliki templat (atau tidak memiliki konten templat yang ditetapkan sebagai konten default), penyedia skrip dapat mengembalikan E_NOTIMPL dari metode ini.
Metode EnumerateTemplates mengembalikan enumerator yang mampu menghitung berbagai templat yang disediakan oleh penyedia skrip. Konten templat adalah apa yang ingin "diisi sebelumnya" penyedia skrip ke dalam jendela edit saat membuat skrip baru. Jika ada beberapa templat berbeda yang didukung, templat tersebut dapat diberi nama (misalnya: "Skrip Imperatif", "Skrip Ekstensi") dan aplikasi debugger yang menghosting model data dapat memilih cara menyajikan "templat" kepada pengguna.
Antarmuka Skrip Inti: IDataModelScript
Antarmuka utama yang mengelola skrip individual yang diterapkan oleh penyedia adalah antarmuka IDataModelScript. Komponen yang mengimplementasikan antarmuka ini dikembalikan ketika klien ingin membuat skrip kosong baru dan memanggil metode CreateScript di IDataModelScriptProvider.
Setiap skrip yang dibuat oleh penyedia harus berada dalam silo independen. Satu skrip seharusnya tidak dapat memengaruhi skrip lain kecuali melalui interaksi eksplisit dengan objek eksternal melalui model data. Dua skrip, misalnya, keduanya memperluas beberapa jenis atau konsep (misalnya: gagasan debugger tentang apa prosesnya). Salah satu skrip kemudian dapat mengakses bidang satu sama lain melalui objek proses eksternal.
Antarmuka didefinisikan sebagai berikut.
DECLARE_INTERFACE_(IDataModelScript, IUnknown)
{
STDMETHOD(GetName)(_Out_ BSTR *scriptName) PURE;
STDMETHOD(Rename)(_In_ PCWSTR scriptName) PURE;
STDMETHOD(Populate)(_In_ IStream *contentStream) PURE;
STDMETHOD(Execute)(_In_ IDataModelScriptClient *client) PURE;
STDMETHOD(Unlink)() PURE;
STDMETHOD(IsInvocable)(_Out_ bool *isInvocable) PURE;
STDMETHOD(InvokeMain)(_In_ IDataModelScriptClient *client) PURE;
}
Metode GetName mengembalikan nama skrip sebagai string yang dialokasikan melalui fungsi SysAllocString. Jika skrip belum memiliki nama, metode harus mengembalikan BSTR null. Seharusnya tidak gagal dalam keadaan ini. Jika skrip secara eksplisit diganti namanya melalui panggilan ke metode Ganti Nama, metode GetName harus mengembalikan nama yang baru ditetapkan.
Metode Ganti Nama menetapkan nama baru ke skrip. Ini adalah tanggung jawab implementasi skrip untuk menyimpan nama ini dan mengembalikannya setelah panggilan apa pun ke metode GetName. Ini sering dipanggil ketika antarmuka pengguna memilih untuk Menyimpan Sebagai skrip ke nama baru. Perhatikan bahwa mengganti nama skrip dapat memengaruhi di mana aplikasi hosting memilih untuk memproyeksikan konten skrip.
Metode Isi dipanggil oleh klien untuk mengubah atau menyinkronkan "konten" skrip. Ini adalah pemberitahuan yang dibuat ke penyedia skrip bahwa kode skrip telah berubah. Penting untuk dicatat bahwa metode ini tidak menyebabkan eksekusi skrip atau perubahan pada salah satu objek yang dimanipulasi skrip. Ini hanya pemberitahuan kepada penyedia skrip bahwa konten skrip telah berubah sehingga dapat menyinkronkan status internalnya sendiri.
Metode Jalankan menjalankan konten skrip seperti yang ditentukan oleh panggilan Isi terakhir yang berhasil dan memodifikasi model objek debugger sesuai dengan konten tersebut. Jika bahasa (atau penyedia skrip) mendefinisikan "fungsi utama" -- salah satu yang ingin dipanggil penulis setelah mengklik tombol "Jalankan Skrip" imajiner di antarmuka pengguna -- "fungsi utama" seperti itu tidak dipanggil selama operasi Jalankan. Operasi Jalankan dapat dianggap untuk melakukan manipulasi model inisialisasi dan objek saja (misalnya: mengeksekusi kode akar dan menyiapkan titik ekstensibilitas).
Metode Batalkan tautan membatalkan operasi Jalankan. Setiap manipulasi model objek atau titik ekstensibilitas yang ditetapkan selama eksekusi skrip dibatalkan. Setelah operasi Batalkan tautan, skrip dapat dijalankan kembali melalui panggilan ke Jalankan atau mungkin dirilis.
Metode IsInvocable mengembalikan apakah skrip dapat dipanggil atau tidak -- yaitu, apakah skrip memiliki "fungsi utama" seperti yang didefinisikan oleh bahasa atau penyedianya. "Fungsi utama" seperti itu secara konseptual adalah sesuatu yang ingin dipanggil oleh penulis skrip jika tombol "Jalankan Skrip" imajiner ditekan di antarmuka pengguna.
Jika skrip memiliki "fungsi utama" yang dimaksudkan untuk dijalankan dari pemanggilan UI, skrip menunjukkan seperti itu melalui pengembalian sejati dari metode IsInvocable. Antarmuka pengguna kemudian dapat memanggil metode InvokeMain untuk benar-benar "memanggil" skrip. Perhatikan bahwa ini berbeda dari Execute yang menjalankan semua kode akar dan menjelang skrip ke namespace host yang mendasarinya.
**Klien Skrip: IDataModelScriptClient **
Aplikasi yang menghosting model data yang ingin mengelola skrip dan memiliki antarmuka pengguna (baik grafis atau konsol) di sekitar gagasan ini mengimplementasikan antarmuka IDataModelScriptClient. Antarmuka ini diteruskan ke penyedia skrip apa pun selama eksekusi atau pemanggilan atau skrip untuk meneruskan informasi kesalahan dan peristiwa kembali ke antarmuka pengguna.
Antarmuka IDataModelScriptClient didefinisikan sebagai berikut.
DECLARE_INTERFACE_(IDataModelScriptClient, IUnknown)
{
STDMETHOD(ReportError)(_In_ ErrorClass errClass, _In_ HRESULT hrFail, _In_opt_ PCWSTR message, _In_ ULONG line, _In_ ULONG position) PURE;
}
Jika terjadi kesalahan selama eksekusi atau pemanggilan skrip, penyedia skrip memanggil metode ReportError untuk memberi tahu antarmuka pengguna tentang kesalahan tersebut.
Konteks Host untuk Skrip: IDataModelScriptHostContext
Host debug memiliki pengaruh terhadap bagaimana dan di mana ia memproyeksikan konten skrip model data. Diharapkan bahwa setiap skrip meminta host untuk konteks di mana menempatkan jembatan ke skrip (misalnya: objek fungsi yang dapat dipanggil, dll...). Konteks ini diambil melalui memanggil metode CreateContext di IDebugHostScriptHost dan mendapatkan IDataModelScriptHostContext.
Antarmuka IDataModelScriptHostContext didefinisikan sebagai berikut.
DECLARE_INTERFACE_(IDataModelScriptHostContext, IUnknown)
{
STDMETHOD(NotifyScriptChange)(_In_ IDataModelScript* script, _In_ ScriptChangeKind changeKind) PURE;
STDMETHOD(GetNamespaceObject)(_COM_Outptr_ IModelObject** namespaceObject) PURE;
}
Diperlukan bahwa penyedia skrip memberi tahu host debug pada operasi tertentu yang terjadi dengan panggilan metode ke metode NotifyScriptChange pada konteks terkait. Operasi tersebut didefinisikan sebagai anggota enumerasi ScriptChangeKind
Metode GetNamespaceObject mengembalikan objek tempat penyedia skrip dapat menempatkan jembatan apa pun antara model data dan skrip. Di sini, misalnya, bahwa penyedia skrip mungkin menempatkan objek metode model data (antarmuka IModelMethod yang dikotak ke dalam IModelObject) yang implementasinya memanggil ke fungsi bernama yang sesuai dalam skrip.
Templat untuk Skrip yang Baru Dibuat: IDataModelScriptTemplate
Penyedia skrip yang ingin menyajikan konten yang telah diisi sebelumnya untuk skrip baru (misalnya: untuk membantu pengguna menulis skrip di antarmuka pengguna debugger) dapat melakukannya dengan menyediakan satu atau beberapa templat skrip. Templat tersebut adalah komponen yang mengimplementasikan antarmuka IDataModelScriptTemplate dan dikembalikan melalui metode GetDefaultTemplate atau metode EnumerateTemplates pada penyedia skrip.
Antarmuka IDataModelScriptTemplate didefinisikan sebagai berikut.
DECLARE_INTERFACE_(IDataModelScriptTemplate, IUnknown)
{
STDMETHOD(GetName)(_Out_ BSTR *templateName) PURE;
STDMETHOD(GetDescription)(_Out_ BSTR *templateDescription) PURE;
STDMETHOD(GetContent)(_COM_Outptr_ IStream **contentStream) PURE;
}
Metode GetName mengembalikan nama templat. Ini mungkin gagal dengan E_NOTIMPL jika templat tidak memiliki nama. Templat default tunggal (jika ada) tidak diperlukan untuk memiliki nama. Semua templat lainnya adalah. Nama-nama ini dapat disajikan di antarmuka pengguna sebagai bagian dari menu untuk memilih templat mana yang akan dibuat.
Metode GetDescription mengembalikan deskripsi templat. Deskripsi tersebut akan disajikan kepada pengguna di antarmuka yang lebih deskriptif untuk membantu pengguna memahami apa yang dirancang untuk dilakukan oleh templat. Templat dapat mengembalikan E_NOTIMPL dari metode ini jika tidak memiliki deskripsi.
Metode GetContent mengembalikan konten (atau kode) templat. Inilah yang akan diisi sebelumnya ke dalam jendela edit jika pengguna memilih untuk membuat skrip baru dari templat ini. Templat bertanggung jawab untuk membuat (dan mengembalikan) aliran standar atas konten yang dapat ditarik klien.
Enumerasi Konten Templat Penyedia: IDataModelScriptTemplateEnumerator
Penyedia skrip dapat menyediakan satu atau beberapa templat yang mengisi konten sebelumnya ke dalam skrip yang baru dibuat di beberapa antarmuka pengguna. Jika salah satu templat ini disediakan, penyedia skrip harus menerapkan enumerator di atasnya yang dikembalikan setelah panggilan ke metode EnumerateTemplates.
Enumerator tersebut adalah implementasi antarmuka IDataModelScriptTemplateEnumerator dan didefinisikan sebagai berikut.
DECLARE_INTERFACE_(IDataModelScriptTemplateEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_COM_Outptr_ IDataModelScriptTemplate **templateContent) PURE;
}
Metode Reset mengatur ulang enumerator ke posisi saat pertama kali dibuat -- sebelum templat pertama diproduksi.
Metode GetNext memindahkan enumerator ke templat berikutnya dan mengembalikannya. Pada akhir enumerasi, enumerator mengembalikan E_BOUNDS. Setelah penanda E_BOUNDS terpukul, enumerator akan terus menghasilkan kesalahan E_BOUNDS tanpa batas waktu hingga panggilan Reset dilakukan.
Mengatasi Arti Nama: IDataModelNameBinder
Model data menyediakan cara standar bagi penyedia skrip untuk menentukan arti nama tertentu dalam konteks tertentu (misalnya: menentukan bilah apa artinya untuk foo.bar) yang akan beroperasi di berbagai penyedia skrip. Mekanisme ini dikenal sebagai pengikat nama dan diwakili oleh antarmuka IDataModelNameBinder. Pengikat seperti itu merangkum sekumpulan aturan tentang bagaimana nama diselesaikan dan cara menangani resolusi konflik di mana nama didefinisikan beberapa kali pada objek. Bagian dari aturan ini mencakup hal-hal seperti bagaimana nama yang diproyeksikan (satu ditambahkan oleh model data) diselesaikan terhadap nama asli (satu dalam sistem jenis bahasa yang sedang di-debug).
Untuk memberikan tingkat konsistensi di seluruh penyedia skrip, manajer skrip model data menyediakan pengikat nama default'. Pengikat nama default ini dapat diperoleh melalui panggilan ke metode GetDefaultNameBinder pada antarmuka IDataModelScriptManager. Antarmuka pengikat nama didefinisikan sebagai berikut.
DECLARE_INTERFACE_(IDataModelNameBinder, IUnknown)
{
STDMETHOD(BindValue)(_In_ IModelObject* contextObject, _In_ PCWSTR name, _COM_Errorptr_ IModelObject** value, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(BindReference)(_In_ IModelObject* contextObject, _In_ PCWSTR name, _COM_Errorptr_ IModelObject** reference, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(EnumerateValues)(_In_ IModelObject* contextObject, _COM_Outptr_ IKeyEnumerator** enumerator) PURE;
STDMETHOD(EnumerateReferences)(_In_ IModelObject* contextObject, _COM_Outptr_ IKeyEnumerator** enumerator) PURE;
}
Metode BindValue melakukan setara dengan contextObject.name pada objek yang diberikan sesuai dengan sekumpulan aturan pengikatan. Hasil pengikatan ini adalah nilai. Sebagai nilai, penyedia skrip yang mendasar tidak dapat menggunakan nilai untuk melakukan penugasan kembali ke nama.
Metode BindReference mirip dengan BindValue karena juga melakukan contextObject.name yang setara pada objek yang diberikan sesuai dengan sekumpulan aturan pengikatan. Namun, hasil pengikatan dari metode ini adalah referensi alih-alih nilai. Sebagai referensi, penyedia skrip dapat menggunakan referensi untuk melakukan penugasan kembali ke nama.
Metode EnumerateValues menghitung kumpulan nama dan nilai yang akan mengikat terhadap objek sesuai dengan aturan metode BindValue. Tidak seperti EnumerateKeys, EnumerateValues, dan metode serupa pada IModelObject yang dapat mengembalikan beberapa nama dengan nilai yang sama (untuk kelas dasar, model induk, dan sejenisnya), enumerator ini hanya akan mengembalikan kumpulan nama tertentu yang akan mengikat dengan BindValue dan BindReference. Nama tidak akan pernah diduplikasi. Perhatikan bahwa ada biaya yang jauh lebih tinggi untuk menghitung objek melalui pengikat nama daripada memanggil metode IModelObject.
Metode EnumerateReferences menghitung sekumpulan nama dan referensi untuk mereka yang akan mengikat terhadap objek sesuai dengan aturan metode BindReference. Tidak seperti EnumerateKeys, EnumerateValues, dan metode serupa pada IModelObject yang dapat mengembalikan beberapa nama dengan nilai yang sama (untuk kelas dasar, model induk, dan sejenisnya), enumerator ini hanya akan mengembalikan kumpulan nama tertentu yang akan mengikat dengan BindValue dan BindReference. Nama tidak akan pernah diduplikasi. Perhatikan bahwa ada biaya yang jauh lebih tinggi untuk menghitung objek melalui pengikat nama daripada memanggil metode IModelObject.
Antarmuka Debugging Skrip Model Data Debugger C++
Infrastruktur untuk penyedia skrip dalam model data juga menyediakan konsep sekeliling skrip penelusuran kesalahan. Setiap skrip yang ingin mengekspos kemampuan penelusuran kesalahan ke host debug dan aplikasi debugger yang menghosting model data dapat melakukannya dengan memiliki skrip yang dapat di-debug mengimplementasikan antarmuka IDataModelScriptDebug selain antarmuka IDataModelScript. Kehadiran antarmuka ini pada skrip menunjukkan kepada infrastruktur bahwa antarmuka ini dapat di-debug.
Meskipun antarmuka IDataModelScriptDebug adalah titik awal untuk mendapatkan akses ke kemampuan debug penyedia skrip, antarmuka ini digabungkan dengan serangkaian antarmuka lain dalam menyediakan kemampuan debug secara keseluruhan.
Antarmuka debug adalah:
| Antarmuka | Deskripsi |
|---|---|
| IDataModelScriptDebug | Antarmuka inti yang harus disediakan penyedia skrip untuk membuat skrip dapat di-debug. Kelas implementasi antarmuka IDataModelScript harus QueryInterface untuk IDataModelScriptDebug jika skrip dapat di-debug. |
| IDataModelScriptDebugClient | Antarmuka pengguna yang ingin memberikan kemampuan penelusuran kesalahan skrip mengimplementasikan antarmuka IDataModelScriptDebugClient. Penyedia skrip menggunakan antarmuka ini untuk meneruskan informasi debug bolak-balik (misalnya: peristiwa yang terjadi, titik henti, dll...) |
| IDataModelScriptDebugStack | Penyedia skrip mengimplementasikan antarmuka ini untuk mengekspos gagasan tumpukan panggilan ke debugger skrip. |
| IDataModelScriptDebugStackFrame | Penyedia skrip mengimplementasikan antarmuka ini untuk mengekspos gagasan bingkai tumpukan tertentu dalam tumpukan panggilan. |
| IDataModelScriptDebugVariableSetEnumerator | Penyedia skrip mengimplementasikan antarmuka ini untuk mengekspos sekumpulan variabel. Set ini dapat mewakili sekumpulan parameter ke fungsi, set variabel lokal, atau kumpulan variabel dalam cakupan tertentu. Arti yang tepat tergantung pada bagaimana antarmuka diperoleh. |
| IDataModelScriptDebugBreakpoint | Penyedia skrip mengimplementasikan antarmuka ini untuk mengekspos gagasan dan kontrol titik henti tertentu dalam skrip. |
| IDataModelScriptDebugBreakpointEnumerator | Penyedia skrip mengimplementasikan ini untuk menghitung semua titik henti yang saat ini ada dalam skrip (baik diaktifkan atau tidak). |
Antarmuka manajemen umum adalah:
| Antarmuka | Deskripsi |
|---|---|
| IDataModelScriptProvider | Antarmuka inti yang harus diterapkan penyedia skrip. Ini adalah antarmuka yang terdaftar dengan bagian manajer skrip dari manajer model data untuk mengiklankan dukungan penyedia dari jenis skrip tertentu dan mendaftar terhadap ekstensi file tertentu |
| IDataModelScript | Abstraksi skrip tertentu yang sedang dikelola oleh penyedia. Setiap skrip yang dimuat atau diedit memiliki instans IDataModelScript terpisah |
| IDataModelScriptClient | Antarmuka klien yang digunakan oleh penyedia skrip untuk mengomunikasikan informasi ke antarmuka pengguna. Penyedia skrip tidak mengimplementasikan antarmuka ini. Aplikasi yang menghosting model data yang ingin menggunakan penyedia skrip. Penyedia skrip akan memanggil metode klien skrip untuk melaporkan status, kesalahan, dll... |
| IDataModelScriptHostContext | Antarmuka host yang digunakan oleh penyedia skrip sebagai kontainer untuk konten skrip. Bagaimana konten permukaan skrip selain manipulasi yang dilakukannya ke model objek aplikasi debugger hingga host debug tertentu. Antarmuka ini memungkinkan penyedia skrip untuk mendapatkan informasi tentang tempat menempatkan kontennya. |
| IDataModelScriptTemplate | Penyedia skrip dapat menyediakan satu atau beberapa templat yang berfungsi sebagai titik awal bagi pengguna untuk menulis skrip. Aplikasi debugger yang menyediakan editor bawaan dapat mengisi skrip baru dengan konten templat seperti yang diiklankan oleh penyedia melalui antarmuka ini. |
| IDataModelScriptTemplateEnumerator | Antarmuka enumerator yang diterapkan penyedia skrip untuk mengiklankan semua berbagai templat yang didukungnya. |
| IDataModelNameBinder | Pengikat nama -- objek yang dapat mengaitkan nama dalam konteks dengan nilai. Untuk ekspresi tertentu seperti "foo.bar", pengikat nama dapat mengikat nama "bar" dalam konteks objek "foo" dan menghasilkan nilai atau referensi ke dalamnya. Pengikat nama biasanya tidak diimplementasikan oleh penyedia skrip; sebaliknya, pengikat default dapat diperoleh dari model data dan digunakan oleh penyedia skrip. |
Membuat Skrip Dapat Di-debug: IDataModelScriptDebug
Setiap skrip yang dapat di-debug menunjukkan kemampuan ini melalui keberadaan antarmuka IDataModelScriptDebug pada komponen yang sama yang mengimplementasikan IDataModelScript. Kueri untuk antarmuka ini oleh host debug atau aplikasi debugger yang menghosting model data adalah apa yang menunjukkan adanya kemampuan debug.
Antarmuka IDataModelScriptDebug didefinisikan sebagai berikut.
DECLARE_INTERFACE_(IDataModelScriptDebug, IUnknown)
{
STDMETHOD_(ScriptDebugState, GetDebugState)() PURE;
STDMETHOD(GetCurrentPosition)(_Out_ ScriptDebugPosition *currentPosition, _Out_opt_ ScriptDebugPosition *positionSpanEnd, _Out_opt_ BSTR *lineText) PURE;
STDMETHOD(GetStack)(_COM_Outptr_ IDataModelScriptDebugStack **stack) PURE;
STDMETHOD(SetBreakpoint)(_In_ ULONG linePosition, _In_ ULONG columnPosition, _COM_Outptr_ IDataModelScriptDebugBreakpoint **breakpoint) PURE;
STDMETHOD(FindBreakpointById)(_In_ ULONG64 breakpointId, _COM_Outptr_ IDataModelScriptDebugBreakpoint **breakpoint) PURE;
STDMETHOD(EnumerateBreakpoints)(_COM_Outptr_ IDataModelScriptDebugBreakpointEnumerator **breakpointEnum) PURE;
STDMETHOD(GetEventFilter)(_In_ ScriptDebugEventFilter eventFilter, _Out_ bool *isBreakEnabled) PURE;
STDMETHOD(SetEventFilter)(_In_ ScriptDebugEventFilter eventFilter, _In_ bool isBreakEnabled) PURE;
STDMETHOD(StartDebugging)(_In_ IDataModelScriptDebugClient *debugClient) PURE;
STDMETHOD(StopDebugging)(_In_ IDataModelScriptDebugClient *debugClient) PURE;
}
Metode GetDebugState mengembalikan status skrip saat ini (misalnya: apakah itu dijalankan atau tidak). Status ditentukan oleh nilai dalam enumerasi ScriptDebugState.
Metode GetCurrentPosition mengembalikan posisi saat ini dalam skrip. Ini mungkin hanya dipanggil ketika skrip dipecah menjadi debugger di mana panggilan ke GetScriptState akan mengembalikan ScriptDebugBreak. Panggilan lain ke metode ini tidak valid dan akan gagal.
Metode GetStack mendapatkan tumpukan panggilan saat ini pada posisi jeda. Metode ini hanya dapat dipanggil ketika skrip dipecah menjadi debugger.
Metode SetBreakpoint menetapkan titik henti dalam skrip. Perhatikan bahwa implementasi bebas untuk menyesuaikan posisi baris dan kolom yang dilewati untuk maju ke posisi kode yang sesuai. Nomor baris dan kolom aktual tempat titik henti ditempatkan dapat diambil oleh panggilan metode pada antarmuka IDataModelScriptDebugBreakpoint yang dikembalikan.
Setiap titik henti yang dibuat dalam skrip melalui metode SetBreakpoint diberi pengidentifikasi unik (bilangan bulat yang tidak ditandatangani 64-bit) oleh implementasi. Metode FindBreakpointById digunakan untuk mendapatkan antarmuka ke titik henti dari pengidentifikasi tertentu.
Metode EnumerateBreakpoints mengembalikan enumerator yang mampu menghitung setiap titik henti yang diatur dalam skrip tertentu.
Metode GetEventFilter mengembalikan apakah "break on event" diaktifkan untuk peristiwa tertentu. Peristiwa yang dapat menyebabkan "istirahat pada peristiwa" dijelaskan oleh anggota enumerasi ScriptDebugEventFilter.
Metode SetEventFilter mengubah perilaku "break on event" untuk peristiwa tertentu seperti yang didefinisikan oleh anggota enumerasi ScriptDebugEventFilter. Daftar lengkap peristiwa yang tersedia (dan deskripsi enumerasi ini) dapat ditemukan dalam dokumentasi untuk metode GetEventFilter.
Metode StartDebugging "menyalakan" debugger untuk skrip tertentu. Tindakan memulai penelusuran kesalahan tidak secara aktif menyebabkan eksekusi rusak atau melangkah. Ini hanya membuat skrip dapat di-debug dan menyediakan serangkaian antarmuka bagi klien untuk berkomunikasi dengan antarmuka debugging.
Metode StopDebugging dipanggil oleh klien yang ingin menghentikan penelusuran kesalahan. Panggilan metode ini dapat dilakukan kapan saja setelah StartDebugging berhasil dilakukan (misalnya: selama jeda, saat skrip dijalankan, dll...). Panggilan segera menghentikan semua aktivitas penelusuran kesalahan dan mengatur ulang status kembali ke sebelum StartDebugging dipanggil.
Antarmuka Debugging: IDataModelScriptDebugClient
Host debug atau aplikasi debugger yang ingin menyediakan antarmuka di sekitar penelusuran kesalahan skrip harus menyediakan implementasi antarmuka IDataModelScriptDebugClient ke debugger skrip melalui metode StartDebugging pada antarmuka debug untuk skrip.
IDataModelScriptDebugClient adalah saluran komunikasi di mana peristiwa debug diteruskan dan kontrol berubah dari mesin eksekusi skrip ke antarmuka debugger. Ini didefinisikan sebagai berikut.
DECLARE_INTERFACE_(IDataModelScriptDebugClient, IUnknown)
{
STDMETHOD(NotifyDebugEvent)(_In_ ScriptDebugEventInformation *pEventInfo, _In_ IDataModelScript *pScript, _In_opt_ IModelObject *pEventDataObject, _Inout_ ScriptExecutionKind *resumeEventKind) PURE;
}
Setiap kali terjadi peristiwa yang memecah ke debugger skrip, kode debug itu sendiri melakukan panggilan ke antarmuka melalui metode NotifyDebugEvent. Metode ini sinkron. Tidak ada eksekusi skrip yang akan dilanjutkan hingga antarmuka kembali dari peristiwa. Definisi debugger skrip dimaksudkan untuk sederhana: sama sekali tidak ada peristiwa berlapis yang memerlukan pemrosesan. Peristiwa debug didefinisikan oleh rekaman varian yang dikenal sebagai ScriptDebugEventInformation. Bidang mana dalam informasi peristiwa yang valid sebagian besar ditentukan oleh anggota DebugEvent. Ini mendefinisikan jenis peristiwa yang terjadi seperti yang dijelaskan oleh anggota enumerasi ScriptDebugEvent.
Tumpukan Panggilan: IDataModelScriptDebugStack
Ketika terjadi peristiwa yang memecah ke debugger skrip, antarmuka penelusuran kesalahan akan ingin mengambil tumpukan panggilan untuk lokasi pemisahan. Ini dilakukan melalui metode GetStack. Tumpukan tersebut dinyatakan melalui IDataModelScriptDebugStack yang didefinisikan seperti yang ditunjukkan di bawah ini.
Perhatikan bahwa tumpukan keseluruhan dapat mencakup beberapa skrip dan/atau beberapa penyedia skrip. Tumpukan panggilan yang dikembalikan dari satu panggilan ke metode GetStack pada antarmuka debug skrip tertentu hanya boleh mengembalikan segmen tumpukan panggilan dalam batas skrip tersebut. Sangat mungkin bahwa mesin debug skrip dapat mengambil tumpukan panggilan karena mencakup beberapa konteks skrip jika dua skrip penyedia yang sama berinteraksi. Metode GetStack tidak boleh mengembalikan bagian tumpukan yang ada di skrip lain. Sebaliknya, jika situasi ini dapat dideteksi, bingkai tumpukan yang merupakan bingkai batas ke dalam skrip harus menandai dirinya sebagai bingkai transisi melalui implementasi metode IsTransitionPoint dan GetTransition pada bingkai tumpukan tersebut. Diharapkan bahwa antarmuka debugger akan menyatukan tumpukan keseluruhan dari beberapa segmen tumpukan yang ada.
Sangat penting bahwa transisi diimplementasikan dengan cara ini atau antarmuka debug dapat mengarahkan pertanyaan tentang variabel lokal, parameter, titik henti, dan konstruksi spesifik skrip lainnya ke konteks skrip yang salah! Ini akan mengakibatkan perilaku yang tidak ditentukan di antarmuka debugger.
DECLARE_INTERFACE_(IDataModelScriptDebugStack, IUnknown)
{
STDMETHOD_(ULONG64, GetFrameCount)() PURE;
STDMETHOD(GetStackFrame)(_In_ ULONG64 frameNumber, _COM_Outptr_ IDataModelScriptDebugStackFrame **stackFrame) PURE;
}
Metode GetFrameCount mengembalikan jumlah bingkai tumpukan di segmen tumpukan panggilan ini. Jika penyedia dapat mendeteksi bingkai dalam konteks skrip yang berbeda atau penyedia yang berbeda, itu harus menunjukkan ini kepada pemanggil dengan implementasi metode IsTransitionPoint dan GetTransition pada bingkai entri ke segmen tumpukan ini.
GetStackFrame mendapatkan bingkai tumpukan tertentu dari segmen tumpukan. Tumpukan panggilan memiliki sistem pengindeksan berbasis nol: bingkai tumpukan saat ini di mana peristiwa pemutusan yang terjadi adalah bingkai 0. Pemanggil metode saat ini adalah bingkai 1 (dan sebagainya).
Memeriksa Status Saat Rusak: IDataModelScriptDebugStackFrame
Bingkai tertentu dari tumpukan panggilan ketika dipecah ke dalam debugger skrip dapat diambil melalui panggilan ke metode GetStackFrame pada antarmuka IDataModelScriptDebugStack yang mewakili segmen tumpukan tempat pemutusan terjadi. Antarmuka IDataModelScriptDebugStackFrame yang dikembalikan untuk mewakili bingkai ini didefinisikan sebagai berikut.
DECLARE_INTERFACE_(IDataModelScriptDebugStackFrame, IUnknown)
{
STDMETHOD(GetName)(_Out_ BSTR *name) PURE;
STDMETHOD(GetPosition)(_Out_ ScriptDebugPosition *position, _Out_opt_ ScriptDebugPosition *positionSpanEnd, _Out_opt_ BSTR *lineText) PURE;
STDMETHOD(IsTransitionPoint)(_Out_ bool *isTransitionPoint) PURE;
STDMETHOD(GetTransition)(_COM_Outptr_ IDataModelScript **transitionScript, _Out_ bool *isTransitionContiguous) PURE;
STDMETHOD(Evaluate)(_In_ PCWSTR pwszExpression, _COM_Outptr_ IModelObject **ppResult) PURE;
STDMETHOD(EnumerateLocals)(_COM_Outptr_ IDataModelScriptDebugVariableSetEnumerator **variablesEnum) PURE;
STDMETHOD(EnumerateArguments)(_COM_Outptr_ IDataModelScriptDebugVariableSetEnumerator **variablesEnum) PURE;
}
Metode GetName mengembalikan nama tampilan (misalnya: nama fungsi) dari bingkai ini. Nama tersebut akan ditampilkan dalam backtrace tumpukan yang disajikan kepada pengguna di antarmuka debugger.
Metode GetPosition mengembalikan posisi dalam skrip yang diwakili oleh bingkai tumpukan. Metode ini hanya dapat dipanggil ketika skrip berada dalam jeda yang diwakili oleh tumpukan tempat bingkai ini berada. Posisi baris dan kolom dalam bingkai ini selalu dikembalikan. Jika debugger mampu mengembalikan rentang "posisi eksekusi" dalam skrip, posisi akhir dapat dikembalikan dalam argumen positionSpanEnd. Jika debugger tidak mampu melakukan ini, nilai baris dan kolom dalam rentang akhir (jika diminta) harus diatur ke nol.
Antarmuka IDataModelScriptDebugStack mewakili segmen tumpukan panggilan -- bagian tumpukan panggilan yang terkandung dalam konteks satu skrip. Jika debugger mampu mendeteksi transisi dari satu skrip ke skrip lain (atau satu penyedia skrip ke yang lain), debugger dapat menunjukkan ini dengan menerapkan metode IsTransitionPoint dan mengembalikan true atau false sebagaimana mestinya. Bingkai tumpukan panggilan yang memasukkan skrip tempat segmen berlaku harus dianggap sebagai titik transisi. Semua bingkai lainnya tidak.
Jika bingkai tumpukan tertentu adalah titik transisi seperti yang ditentukan oleh metode IsTransition (lihat dokumentasi di sana untuk definisi titik transisi), metode GetTransition mengembalikan informasi tentang transisi. Secara khusus, metode ini mengembalikan skrip sebelumnya -- yang melakukan panggilan ke dalam skrip yang diwakili oleh segmen tumpukan yang berisi IDataModelScriptDebugStackFrame ini.
Metode Evaluasi mengevaluasi ekspresi (bahasa penyedia skrip) dalam konteks bingkai tumpukan yang diwakili oleh antarmuka IDataModelScriptDebugStackFrame tempat metode ini dipanggil. Hasil evaluasi ekspresi harus dirusak dari penyedia skrip sebagai IModelObject. Properti dan konstruksi lain pada IModelObject yang dihasilkan semuanya harus dapat diperoleh saat debugger dalam keadaan berhenti.
Metode EnumerateLocals mengembalikan set variabel (diwakili oleh antarmuka IDataModelScriptDebugVariableSetEnumerator) untuk semua variabel lokal yang berada dalam cakupan dalam konteks bingkai tumpukan yang diwakili oleh antarmuka IDataModelScriptDebugStackFrame tempat metode ini dipanggil.
Metode EnumerateArguments mengembalikan set variabel (diwakili oleh antarmuka IDataModelScriptDebugVariableSetEnumerator) untuk semua argumen fungsi yang disebut dalam bingkai tumpukan yang diwakili oleh antarmuka IDataModelScriptDebugStackFrame tempat metode ini dipanggil.
Melihat Variabel: IDataModelScriptDebugVariableSetEnumerator
Sekumpulan variabel dalam skrip yang di-debug (baik dalam cakupan tertentu, lokal fungsi, argumen fungsi, dll...) diwakili oleh kumpulan variabel yang ditentukan melalui antarmuka IDataModelScriptDebugVariableSetEnumerator:
DECLARE_INTERFACE_(IDataModelScriptDebugVariableSetEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_Out_ BSTR *variableName, _COM_Outptr_opt_ IModelObject **variableValue, _COM_Outptr_opt_result_maybenull_ IKeyStore **variableMetadata) PURE;
}
Metode Reset mengatur ulang posisi enumerator ke tempatnya segera setelah pembuatan -- yaitu, sebelum elemen pertama dari set.
Metode GetNext memindahkan enumerator ke variabel berikutnya dalam set dan mengembalikan nama variabel, nilai, dan metadata apa pun yang terkait dengannya. Jika enumerator telah mencapai akhir set, kesalahan E_BOUNDS dikembalikan. Setelah penanda E_BOUNDS dikembalikan dari metode GetNext, penanda akan terus menghasilkan E_BOUNDS ketika dipanggil lagi kecuali panggilan Reset intervensi dilakukan.
Titik Henti: IDataModelScriptDebugBreakpoint
Titik henti skrip diatur melalui metode SetBreakpoint pada antarmuka debug skrip tertentu. Titik henti tersebut diwakili oleh id unik dan implementasi antarmuka IDataModelScriptDebugBreakpoint yang didefinisikan sebagai berikut.
DECLARE_INTERFACE_(IDataModelScriptDebugBreakpoint, IUnknown)
{
STDMETHOD_(ULONG64, GetId)() PURE;
STDMETHOD_(bool, IsEnabled)() PURE;
STDMETHOD_(void, Enable)() PURE;
STDMETHOD_(void, Disable)() PURE;
STDMETHOD_(void, Remove)() PURE;
STDMETHOD(GetPosition)(_Out_ ScriptDebugPosition *position, _Out_opt_ ScriptDebugPosition *positionSpanEnd, _Out_opt_ BSTR *lineText) PURE;
}
Metode GetId mengembalikan pengidentifikasi unik yang ditetapkan oleh mesin debug penyedia skrip ke titik henti. Pengidentifikasi ini harus unik dalam konteks skrip yang berisi. Pengidentifikasi titik henti mungkin unik bagi penyedia; namun, itu tidak diperlukan.
Metode IsEnabled mengembalikan apakah titik henti diaktifkan atau tidak. Titik henti yang dinonaktifkan masih ada dan masih dalam daftar titik henti untuk skrip, itu hanya "dimatikan" untuk sementara. Semua titik henti harus dibuat dalam status diaktifkan.
Metode Aktifkan memungkinkan titik henti. Jika titik henti dinonaktifkan, "menekan titik henti" setelah memanggil metode ini akan menyebabkan kerusakan pada debugger.
Metode Nonaktifkan menonaktifkan titik henti. Setelah panggilan ini, "menekan titik henti" setelah memanggil metode ini tidak akan masuk ke debugger. Titik henti, saat masih ada, dianggap "dimatikan".
Metode Hapus menghapus titik henti dari daftar yang berisi. Titik henti tidak lagi ada secara semantik setelah metode ini kembali. Antarmuka IDataModelScriptDebugBreakpoint yang mewakili titik henti dianggap tanpa sumber setelah panggilan. Tidak ada yang lain (secara hukum) dapat dilakukan dengannya setelah panggilan ini selain merilisnya.
Metode GetPosition mengembalikan posisi titik henti dalam skrip. Debugger skrip harus mengembalikan baris dan kolom dalam kode sumber tempat titik henti berada. Jika mampu melakukannya, itu juga dapat mengembalikan rentang sumber yang diwakili oleh titik henti dengan mengisi posisi akhir seperti yang didefinisikan oleh argumen positionSpanEnd. Jika debugger tidak mampu menghasilkan rentang ini dan pemanggil memintanya, bidang Baris dan Kolom dari posisi akhir rentang harus diisi sebagai nol yang menunjukkan bahwa nilai tidak dapat disediakan.
Enumerasi Titik Henti: IDataModelScriptDebugBreakpointEnumerator
Jika penyedia skrip mendukung penelusuran kesalahan, penyedia skrip juga harus melacak semua titik henti yang terkait dengan masing-masing dan setiap skrip dan mampu menghitung titik henti tersebut ke antarmuka debug. Enumerator untuk titik henti diperoleh melalui metode EnumerateBreakpoints pada antarmuka debug untuk skrip tertentu dan didefinisikan sebagai berikut.
DECLARE_INTERFACE_(IDataModelScriptDebugBreakpointEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_COM_Outptr_ IDataModelScriptDebugBreakpoint **breakpoint) PURE;
}
Metode Reset mengatur ulang posisi enumerator ke tempatnya tepat setelah enumerator dibuat -- yaitu, sebelum titik henti enumerasi pertama.
Metode GetNext memindahkan enumerator ke depan ke titik henti berikutnya untuk dijumlahkan dan mengembalikan antarmuka IDataModelScriptDebugBreakpoint untuk titik henti tersebut. Jika enumerator telah mencapai akhir enumerasi, enumerasi akan mengembalikan E_BOUNDS. Setelah kesalahan E_BOUNDS dihasilkan, panggilan berikutnya ke metode GetNext akan terus menghasilkan E_BOUNDS kecuali panggilan intervensi ke metode Reset telah dilakukan.
Lihat juga
Topik ini adalah bagian dari seri yang menjelaskan antarmuka yang dapat diakses dari C++, cara menggunakannya untuk membangun ekstensi debugger berbasis C++, dan cara menggunakan konstruksi model data lainnya (misalnya: JavaScript atau NatVis) dari ekstensi model data C++.
Gambaran Umum Model Data Debugger C++
Antarmuka C++ Model Data Debugger
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk