Bagikan melalui

Menggabungkan VBA dan kustomisasi tingkat dokumen

  • Artikel

Anda bisa menggunakan kode Visual Basic for Applications (VBA) dalam dokumen yang merupakan bagian dari kustomisasi tingkat dokumen untuk Microsoft Office Word atau Microsoft Office Excel. Anda dapat memanggil kode VBA dalam dokumen dari rakitan kustomisasi, atau Anda dapat mengonfigurasi proyek Anda untuk mengaktifkan kode VBA dalam dokumen untuk memanggil kode di rakitan kustomisasi.

Berlaku untuk: Informasi dalam topik ini berlaku untuk proyek tingkat dokumen untuk Excel dan Word. Untuk informasi selengkapnya, lihat Fitur yang tersedia berdasarkan aplikasi Office likasi dan jenis proyek.

Perilaku kode VBA dalam kustomisasi tingkat dokumen

Saat Anda membuka proyek di Visual Studio, dokumen dibuka dalam mode desain. Kode VBA tidak berjalan saat dokumen dalam mode desain, sehingga Anda dapat mengerjakan dokumen dan kode tanpa menjalankan kode VBA.

Saat Anda menjalankan solusi, penanganan aktivitas di VBA dan rakitan kustomisasi mengambil peristiwa yang dinaikkan dalam dokumen, dan kedua set kode yang dijalankan. Anda tidak dapat menentukan sebelumnya kode mana yang akan berjalan di hadapan yang lain; Anda harus menentukan ini melalui pengujian dalam setiap kasus individu. Anda bisa mendapatkan hasil yang tidak terduga jika dua set kode tidak dikoordinasikan dan diuji dengan hati-hati.

Memanggil kode VBA dari rakitan kustomisasi

Anda bisa memanggil makro dalam dokumen Word, dan Anda bisa memanggil makro dan fungsi di buku kerja Excel. Untuk melakukan ini, gunakan salah satu metode berikut:

  • Untuk Word, panggil Run metode Application kelas .

  • Untuk Excel, panggil Run metode Application kelas .

    Untuk setiap metode, parameter pertama mengidentifikasi nama makro atau fungsi yang ingin Anda panggil, dan parameter opsional yang tersisa menentukan parameter yang akan diteruskan ke makro atau fungsi. Parameter pertama bisa memiliki format yang berbeda untuk Word dan Excel:

  • Untuk Word, parameter pertama adalah string yang bisa berupa kombinasi templat, modul, dan nama makro apa pun. Jika Anda menentukan nama dokumen, kode Anda hanya dapat menjalankan makro dalam dokumen yang terkait dengan konteks saat ini — bukan makro apa pun dalam dokumen apa pun.

  • Untuk Excel, parameter pertama bisa menjadi string yang menentukan nama makro, Range yang menunjukkan di mana fungsi berada, atau ID register untuk fungsi DLL terdaftar (XLL). Jika Anda meneruskan string, string akan dievaluasi dalam konteks lembar aktif.

    Contoh kode berikut menunjukkan cara memanggil makro bernama MyMacro dari proyek tingkat dokumen untuk Excel. Contoh ini mengasumsikan bahwa MyMacro didefinisikan dalam Sheet1.

Globals.Sheet1.Application.Run("MyMacro", missing, missing, missing,
    missing, missing, missing, missing, missing, missing, missing,
    missing, missing, missing, missing, missing, missing, missing,
    missing, missing, missing, missing, missing, missing, missing,
    missing, missing, missing, missing, missing, missing);

Catatan

Untuk informasi tentang menggunakan variabel global missing sebagai pengganti parameter opsional di Visual C#, lihat Menulis kode di solusi Office.

Kode panggilan dalam kustomisasi tingkat dokumen dari VBA

Anda bisa mengonfigurasi proyek tingkat dokumen untuk Word atau Excel sehingga kode Visual Basic for Applications (VBA) dalam dokumen bisa memanggil kode dalam rakitan kustomisasi. Ini berguna dalam skenario berikut:

  • Anda ingin memperluas kode VBA yang ada dalam dokumen dengan menggunakan fitur dalam kustomisasi tingkat dokumen yang terkait dengan dokumen yang sama.

  • Anda ingin membuat layanan yang Anda kembangkan dalam penyesuaian tingkat dokumen tersedia untuk pengguna akhir yang dapat mengakses layanan dengan menulis kode VBA dalam dokumen.

    Alat pengembangan Office di Visual Studio menyediakan fitur serupa untuk Add-in VSTO. Jika Anda mengembangkan Add-in VSTO, Anda dapat memanggil kode di Add-in VSTO dari solusi Microsoft Office lainnya. Untuk informasi selengkapnya, lihat Kode panggilan di Add-in VSTO dari solusi Office lainnya.

Catatan

Fitur ini tidak dapat digunakan dalam proyek templat Word. Ini hanya dapat digunakan dalam dokumen Word, buku kerja Excel, atau proyek templat Excel.

Persyaratan

Sebelum Anda dapat mengaktifkan kode VBA untuk memanggil ke perakitan kustomisasi, proyek Anda harus memenuhi persyaratan berikut:

  • Dokumen harus memiliki salah satu ekstensi nama file berikut:

    • Untuk Word: .docm atau .doc

    • Untuk Excel: .xlsm, .xltm, .xls, atau .xlt

  • Dokumen harus sudah berisi proyek VBA yang memiliki kode VBA di dalamnya.

  • Kode VBA dalam dokumen harus diizinkan untuk dijalankan tanpa meminta pengguna untuk mengaktifkan makro. Anda bisa mempercayai kode VBA untuk dijalankan dengan menambahkan lokasi proyek Office ke daftar lokasi tepercaya di pengaturan Pusat Kepercayaan untuk Word atau Excel.

  • Proyek Office harus berisi setidaknya satu kelas publik yang berisi satu atau beberapa anggota publik yang Anda ekspos ke VBA.

    Anda dapat mengekspos metode, properti, dan peristiwa ke VBA. Kelas yang Anda ekspos bisa menjadi kelas item host (seperti ThisDocument untuk Word, atau ThisWorkbook dan Sheet1 untuk Excel) atau kelas lain yang Anda tentukan dalam proyek Anda. Untuk informasi selengkapnya tentang item host, lihat Gambaran umum item host dan kontrol host.

Aktifkan kode VBA untuk memanggil ke dalam rakitan kustomisasi

Ada dua cara berbeda untuk mengekspos anggota dalam rakitan kustomisasi ke kode VBA dalam dokumen:

  • Anda dapat mengekspos anggota kelas item host dalam proyek Visual Basic ke VBA. Untuk melakukan ini, atur properti EnableVbaCallers dari item host ke True di jendela Properti saat item host (yaitu, dokumen, lembar kerja, atau buku kerja) terbuka di perancang. Visual Studio secara otomatis melakukan semua pekerjaan yang diperlukan untuk mengaktifkan kode VBA untuk memanggil anggota kelas.

  • Anda dapat mengekspos anggota di kelas publik apa pun dalam proyek Visual C#, atau anggota di kelas item non-host dalam proyek Visual Basic, ke VBA. Opsi ini memberi Anda lebih banyak kebebasan untuk memilih kelas mana yang Anda ekspos ke VBA, tetapi juga memerlukan langkah-langkah yang lebih manual.

    Untuk melakukan ini, Anda harus melakukan langkah-langkah utama berikut:

    1. Mengekspos kelas ke COM.

    2. Ambil alih metode GetAutomationObject dari kelas item host di proyek Anda untuk mengembalikan instans kelas yang Anda ekspos ke VBA.

    3. Atur properti ReferenceAssemblyFromVbaProject dari kelas item host apa pun dalam proyek ke True. Ini menyematkan pustaka jenis rakitan kustomisasi ke dalam rakitan dan menambahkan referensi ke pustaka jenis ke proyek VBA dalam dokumen.

    Untuk instruksi terperinci, lihat Cara: Mengekspos kode ke VBA dalam proyek Visual Basic dan Cara: Mengekspos kode ke VBA dalam proyek Visual C#.

    Properti EnableVbaCallers dan ReferenceAssemblyFromVbaProject hanya tersedia di jendela Properti pada waktu desain; tidak dapat digunakan pada waktu proses. Untuk melihat properti, buka perancang untuk item host di Visual Studio. Untuk informasi selengkapnya tentang tugas tertentu yang dilakukan Visual Studio saat Anda mengatur properti ini, lihat Tugas yang dilakukan oleh properti item host.

Catatan

Jika buku kerja atau dokumen belum berisi kode VBA atau jika kode VBA dalam dokumen tidak dipercaya untuk dijalankan, Anda akan menerima pesan kesalahan saat Anda mengatur properti EnableVbaCallers atau ReferenceAssemblyFromVbaProject ke True. Ini karena Visual Studio tidak dapat mengubah proyek VBA dalam dokumen dalam situasi ini.

Gunakan anggota dalam kode VBA untuk memanggil ke rakitan kustomisasi

Setelah Anda mengonfigurasi proyek untuk mengaktifkan kode VBA untuk dipanggil ke perakitan kustomisasi, Visual Studio menambahkan anggota berikut ke proyek VBA dalam dokumen:

  • Untuk semua proyek, Visual Studio menambahkan metode global bernama GetManagedClass.

  • Untuk proyek Visual Basic tempat Anda mengekspos anggota kelas item host dengan menggunakan properti EnableVbaCallers, Visual Studio juga menambahkan properti bernama CallVSTOAssembly ke ThisDocumentmodul , , Sheet1ThisWorkbook, Sheet2, atau Sheet3 dalam proyek VBA.

    Anda dapat menggunakan CallVSTOAssembly properti atau GetManagedClass metode untuk mengakses anggota publik kelas yang Anda ekspos ke kode VBA dalam proyek.

Catatan

Saat Anda mengembangkan dan menyebarkan solusi Anda, ada beberapa salinan dokumen yang berbeda di mana Anda dapat menambahkan kode VBA. Untuk informasi selengkapnya, lihat Panduan untuk menambahkan kode VBA ke dokumen.

Menggunakan properti CallVSTOAssembly dalam proyek Visual Basic

CallVSTOAssembly Gunakan properti untuk mengakses anggota publik yang Anda tambahkan ke kelas item host. Misalnya, makro VBA berikut memanggil metode bernama MyVSTOMethod yang ditentukan di Sheet1 kelas dalam proyek buku kerja Excel.

Sub MyMacro()
    Sheet1.CallVSTOAssembly.MyVSTOMethod()
End Sub

Properti ini adalah cara yang lebih nyaman untuk memanggil perakitan kustomisasi daripada menggunakan metode secara GetManagedClass langsung. CallVSTOAssembly mengembalikan objek yang mewakili kelas item host yang Anda ekspos ke VBA. Parameter anggota dan metode objek yang dikembalikan muncul di IntelliSense.

Properti CallVSTOAssembly memiliki deklarasi yang mirip dengan kode berikut. Kode ini mengasumsikan bahwa Anda telah mengekspos Sheet1 kelas item host dalam proyek buku kerja Excel bernama ExcelWorkbook1 ke VBA.

Property Get CallVSTOAssembly() As ExcelWorkbook1.Sheet1
    Set CallVSTOAssembly = GetManagedClass(Me)
End Property

Menggunakan metode GetManagedClass

Untuk menggunakan metode global GetManagedClass , teruskan objek VBA yang sesuai dengan kelas item host yang berisi penimpaan metode GetAutomationObject Anda. Kemudian, gunakan objek yang dikembalikan untuk mengakses kelas yang Anda ekspos ke VBA.

Misalnya, makro VBA berikut memanggil metode bernama MyVSTOMethod yang ditentukan dalam Sheet1 kelas item host dalam proyek buku kerja Excel bernama ExcelWorkbook1.

Sub CallVSTOMethod
    Dim VSTOSheet1 As ExcelWorkbook1.Sheet1
    Set VSTOSheet1 = GetManagedClass(Sheet1)
    VSTOSheet1.MyVSTOMethod
End Sub

Metode ini GetManagedClass memiliki deklarasi berikut.

GetManagedClass(pdispInteropObject Object) As Object

Metode ini mengembalikan objek yang mewakili kelas yang Anda ekspos ke VBA. Parameter anggota dan metode objek yang dikembalikan muncul di IntelliSense.

Panduan untuk menambahkan kode VBA ke dokumen

Ada beberapa salinan dokumen yang berbeda di mana Anda dapat menambahkan kode VBA yang memanggil ke dalam kustomisasi tingkat dokumen.

Saat mengembangkan dan menguji solusi, Anda dapat menulis kode VBA dalam dokumen yang terbuka saat men-debug atau menjalankan proyek di Visual Studio (yaitu, dokumen di folder output build). Namun, kode VBA apa pun yang Anda tambahkan ke dokumen ini akan ditimpa saat Anda membuat proyek berikutnya, karena Visual Studio mengganti dokumen di folder output build dengan salinan dokumen dari folder proyek utama.

Jika Anda ingin menyimpan kode VBA yang Anda tambahkan ke dokumen saat menelusuri kesalahan atau menjalankan solusi, salin kode VBA ke dalam dokumen di folder proyek. Untuk informasi selengkapnya tentang proses build, lihat Membangun solusi office.

Ketika Anda siap untuk menyebarkan solusi Anda, ada tiga lokasi dokumen utama di mana Anda dapat menambahkan kode VBA.

Di folder proyek pada komputer pengembangan

Lokasi ini nyaman jika Anda memiliki kontrol penuh atas kode VBA dalam dokumen dan kode kustomisasi. Karena dokumen berada di komputer pengembangan, Anda dapat dengan mudah memodifikasi kode VBA jika Anda mengubah kode kustomisasi. Kode VBA yang Anda tambahkan ke salinan dokumen ini tetap berada dalam dokumen saat Anda membuat, men-debug, dan menerbitkan solusi Anda.

Anda tidak dapat menambahkan kode VBA ke dokumen saat dibuka di perancang. Anda harus terlebih dahulu menutup dokumen dalam perancang, lalu membuka dokumen langsung di Word atau Excel.

Perhatian

Jika Anda menambahkan kode VBA yang berjalan saat dokumen dibuka, dalam kasus yang jarang terjadi kode ini mungkin merusak dokumen atau mencegahnya dibuka di perancang.

Di folder terbitkan atau penginstalan

Dalam beberapa kasus, mungkin cocok untuk menambahkan kode VBA ke dokumen di folder penerbitan atau penginstalan. Misalnya, Anda dapat memilih opsi ini jika kode VBA ditulis dan diuji oleh pengembang lain di komputer yang tidak menginstal Visual Studio.

Jika pengguna menginstal solusi langsung dari folder terbitkan, Anda harus menambahkan kode VBA ke dokumen setiap kali Anda menerbitkan solusi. Visual Studio menimpa dokumen di lokasi penerbitan saat Anda menerbitkan solusi.

Jika pengguna menginstal solusi dari folder penginstalan yang berbeda dari folder terbitkan, Anda dapat menghindari penambahan kode VBA dalam dokumen setiap kali Anda menerbitkan solusi. Ketika pembaruan penerbitan siap dipindahkan dari folder terbitkan ke folder penginstalan, salin semua file ke folder penginstalan kecuali untuk dokumen.

Pada komputer pengguna akhir

Jika pengguna akhir adalah pengembang VBA yang memanggil layanan yang Anda sediakan dalam penyesuaian tingkat dokumen, Anda dapat memberi tahu mereka cara memanggil kode Anda dengan menggunakan CallVSTOAssembly properti atau GetManagedClass metode dalam salinan dokumen mereka. Ketika Anda menerbitkan pembaruan untuk solusi, kode VBA dalam dokumen pada komputer pengguna akhir tidak akan ditimpa, karena dokumen tidak dimodifikasi dengan menerbitkan pembaruan.

Tugas yang dilakukan oleh properti item host

Saat Anda menggunakan properti EnableVbaCallers dan ReferenceAssemblyFromVbaProject , Visual Studio melakukan serangkaian tugas yang berbeda.

AktifkanVbaCallers

Saat Anda mengatur properti EnableVbaCallers dari item host ke True dalam proyek Visual Basic, Visual Studio melakukan tugas berikut:

  1. Ini menambahkan ComClassAttribute atribut dan ComVisibleAttribute ke kelas item host.

  2. Ini mengambil alih metode GetAutomationObject dari kelas item host.

  3. Ini mengatur properti ReferenceAssemblyFromVbaProject dari item host ke True.

    Saat Anda mengatur properti EnableVbaCallers kembali ke False, Visual Studio melakukan tugas berikut:

  4. Ini menghapus ComClassAttribute atribut dan ComVisibleAttribute dari ThisDocument kelas .

  5. Ini menghapus metode GetAutomationObject dari kelas item host.

    Catatan

    Visual Studio tidak secara otomatis mengatur properti ReferenceAssemblyFromVbaProject kembali ke False. Anda dapat mengatur properti ini ke False secara manual dengan menggunakan jendela Properti .

ReferenceAssemblyFromVbaProject

Saat properti ReferenceAssemblyFromVbaProject dari item host apa pun dalam proyek Visual Basic atau Visual C# diatur ke True, Visual Studio melakukan tugas berikut:

  1. Ini menghasilkan pustaka jenis untuk rakitan kustomisasi dan menyematkan pustaka jenis di rakitan.

  2. Ini menambahkan referensi ke pustaka jenis berikut dalam proyek VBA dalam dokumen:

    • Pustaka jenis untuk rakitan kustomisasi Anda.

    • Pustaka Jenis Microsoft Visual Studio Tools for Office Execution Engine 9.0. Pustaka jenis ini disertakan dalam runtime Visual Studio Tools for Office .

    Saat properti ReferenceAssemblyFromVbaProject diatur kembali ke False, Visual Studio melakukan tugas berikut:

  3. Ini menghapus referensi pustaka jenis dari proyek VBA dalam dokumen.

  4. Ini menghapus pustaka jenis yang disematkan dari rakitan.

Pemecahan masalah

Tabel berikut ini mencantumkan beberapa kesalahan dan saran umum untuk memperbaiki kesalahan.

Error Saran
Setelah Anda mengatur properti EnableVbaCallers atau ReferenceAssemblyFromVbaProject , pesan kesalahan menyatakan bahwa dokumen tidak berisi proyek VBA, atau Anda tidak memiliki izin untuk mengakses proyek VBA dalam dokumen. Pastikan bahwa dokumen dalam proyek berisi setidaknya satu makro VBA, proyek VBA memiliki kepercayaan yang cukup untuk dijalankan, dan proyek VBA tidak dilindungi oleh kata sandi.
Setelah Anda mengatur properti EnableVbaCallers atau ReferenceAssemblyFromVbaProject , pesan kesalahan menyatakan bahwa GuidAttribute deklarasi hilang atau rusak. Pastikan bahwa GuidAttribute deklarasi terletak di file AssemblyInfo.cs atau AssemblyInfo.vb dalam proyek Anda, dan bahwa atribut ini diatur ke GUID yang valid.
Setelah Anda mengatur properti EnableVbaCallers atau ReferenceAssemblyFromVbaProject , pesan kesalahan menyatakan bahwa nomor versi yang ditentukan oleh AssemblyVersionAttribute tidak valid. Pastikan bahwa AssemblyVersionAttribute deklarasi dalam file AssemblyInfo.cs atau AssemblyInfo.vb dalam proyek Anda diatur ke nomor versi rakitan yang valid. Untuk informasi tentang nomor versi rakitan yang valid, lihat AssemblyVersionAttribute kelas .
Setelah Anda mengganti nama rakitan kustomisasi, kode VBA yang memanggil ke dalam rakitan kustomisasi berhenti berfungsi. Jika Anda mengubah nama rakitan kustomisasi setelah Anda mengeksposnya ke kode VBA, tautan antara proyek VBA dalam dokumen dan rakitan kustomisasi Anda rusak. Untuk memperbaiki masalah ini, ubah properti ReferenceFromVbaAssembly di proyek Anda menjadi False lalu kembali ke True, lalu ganti referensi apa pun ke nama rakitan lama dalam kode VBA dengan nama rakitan baru.

Konten terkait