Bagaimana membangun kantor COM add-in dengan menggunakan Visual C#.NET

Microsoft Office XP, Microsoft Office 2003 dan Microsoft Office 2007 mendukung arsitektur desain seragam untuk membangun aplikasi tambahan untuk meningkatkan dan mengontrol aplikasi Office. Ini add-in yang disebut Microsoft Component Object Model (COM) Add-in. Artikel ini selangkah demi selangkah membahas peralatan tambahan COM kantor dan menjelaskan bagaimana membangun kantor COM add-in dengan menggunakan Microsoft Visual C#.NET.

Antarmuka IDTExensibility2

COM add-in ini dalam proses COM server, atau link dinamis ActiveX Library (DLL), yang mengimplementasikan IDTExensibility2 antarmuka seperti yang dijelaskan dalam jenis Microsoft Tambah-in Designer perpustakaan (Msaddndr.dll). Semua peralatan tambahan com. mewarisi dari antarmuka ini dan harus menerapkan masing-masing metode lima.

OnConnection

The OnConnection peristiwa kebakaran ketika COM add-in terhubung. Tambahan dapat dihubungkan pada startup, oleh pengguna akhir, atau melalui Otomatisasi. Jika OnConnection acara kembali berhasil, tambahan dikatakan dimuat. Jika pesan kesalahan kembali, aplikasi host segera rilis referensi untuk tambahan, dan objek dihancurkan.

The OnConnection acara berlangsung empat parameter berikut:

• Aplikasi: Referensi ke objek aplikasi host.
• ConnectMode: Konstan yang menentukan bagaimana tambahan terhubung. The Add-in dapat dihubungkan dengan cara berikut:
  • ext_cm_AfterStartup: Add-in yang dimulai oleh pengguna akhir dari Peralatan tambahan COM kotak dialog.
  • ext_cm_CommandLine: Tambah-in terhubung dari baris perintah. Catatan bahwa ini tidak berlaku untuk membangun peralatan tambahan COM untuk aplikasi kantor.
  • ext_cm_External: Tambah-in terhubung oleh aplikasi eksternal melalui Otomatisasi. Catatan bahwa ini tidak berlaku untuk membangun COM add-in untuk Office aplikasi.
  • ext_cm_Startup: Tambah-in dimulai oleh host pada aplikasi startup. Ini perilaku ini dikendalikan oleh pengaturan registri.
• AddInInst: Referensi COMAddIn objek yang merujuk kepada add-in ini di COMAddIns Koleksi untuk aplikasi host.
• Custom: Sebuah array Varian tipe nilai-nilai yang dapat menyimpan data yang ditetapkan pengguna.

OnDisconnection

The OnDisconnection peristiwa kebakaran ketika COM add-in terputus dan sebelum membongkar dari memori. Tambahan harus melakukan pembersihan setiap sumber daya dalam acara ini, dan memulihkan perubahan yang dibuat untuk host aplikasi.

The OnDisconnection acara membawa dua berikut parameter:

• RemoveMode: Konstan yang menentukan bagaimana tambahan diputus. The Add-in dapat diputuskan dengan cara berikut:
  • ext_dm_HostShutdown: Tambah-in terputus ketika aplikasi host menutup.
  • ext_dm_UserClosed: Tambah-in terputus oleh pengguna akhir atau otomatisasi controller.
• Custom: Sebuah array Varian tipe nilai-nilai yang dapat menyimpan data yang ditetapkan pengguna.

OnAddInsUpdate

The OnAddInsUpdate peristiwa kebakaran ketika himpunan terdaftar COM Add-in perubahan. Dengan kata lain, setiap kali COM tambahan diinstal atau dihapus dari aplikasi tuan rumah, ini peristiwa kebakaran.

OnStartupComplete dan OnBeginShutdown

Kedua OnStartupComplete metode dan OnBeginShutdown metode yang disebut Ketika aplikasi host telah meninggalkan atau memasuki keadaan di mana pengguna interaksi harus dihindari karena aplikasi sibuk loading atau pembongkaran sendiri dari memori. The OnStartupComplete metode ini disebut hanya jika tambahan terhubung selama Persiapan, dan OnBeginShutdown metode ini disebut hanya jika tuan rumah terputus tambahan selama pematian.

Karena antarmuka pengguna untuk aplikasi host sepenuhnya aktif ketika peristiwa kebakaran, mereka mungkin satu-satunya cara untuk melakukan tindakan tertentu yang kalau tidak akan menjadi tidak tersedia dari OnConnection acara dan OnDisconnection acara.

COM tambahan pendaftaran

Selain untuk normal COM pendaftaran, COM add-in perlu mendaftar sendiri dengan setiap aplikasi Office yang membentang. Untuk mendaftar itu sendiri dengan aplikasi tertentu, tambahan harus membuat subkunci, menggunakan ProgID sebagai nama untuk kunci, di bawah lokasi berikut: Tambahan dapat memberikan nilai-nilai di lokasi ini kunci untuk nama tampilan ramah dan keterangan lengkap. Selain itu, Add-in harus menentukan perilaku beban yang dikehendaki dengan menggunakan nilai DWORD yang bernama LoadBehavior. Nilai ini menentukan bagaimana tambahan dimuat oleh host aplikasi, dan terdiri dari kombinasi nilai-nilai berikut:

• 0 = Putuskan - tidak dimuat.
• 1 = Connected - load.
• 2 = Bootload - beban pada aplikasi startup.
• 8 = DemandLoad - beban hanya ketika diminta oleh pengguna.
• 16 = ConnectFirstTime - beban hanya sekali (berikutnya Startup).

Nilai khas yang ditentukan adalah 0x03 (Connected | Bootload).

Add-in yang menerapkan IDTExtensibility2 juga harus menentukan nilai DWORD yang disebut untuk menunjukkan apakah add-in aman untuk operasi yang tidak mendukung pengguna antarmuka. Nilai 0x00 menunjukkan palsu, dan nilai 0x01 menunjukkan benar.

Bagaimana membangun COM add-in dengan menggunakan Visual C#.NET

Seperti disebutkan sebelumnya, kantor COM add-in ini dalam proses COM server yang diaktifkan oleh aplikasi Office melalui COM run-time lapisan. Oleh karena itu, mengembangkan COM add-in di.NET mensyaratkan bahwa tambahan komponen diimplementasikan di.NET dan kemudian terkena klien COM (itu adalah, aplikasi Office) melalui lapisan interop COM.

Untuk membuat COM add-in di Visual C#.NET, ikuti langkah berikut:

1. Dalam Visual C#.NET, menciptakan perpustakaan kelas proyek.
2. Menambahkan referensi ke perpustakaan jenis yang menerapkan IDTExtensibility2. Majelis interop utama untuk ini sudah tersedia di bawah nama Ekstensibilitas.
3. Menambahkan referensi ke perpustakaan objek Microsoft Office. The Majelis interop utama untuk ini sudah tersedia di bawah nama Office.
4. Membuat kelas publik di perpustakaan kelas yang mengimplementasikan IDTExtensibility2.
5. Setelah kelas perpustakaan dibangun, mendaftar perpustakaan untuk COM interop. Untuk melakukannya, menghasilkan kuat bernama perakitan untuk kelas ini Perpustakaan dan kemudian mendaftar dengan COM interop. Anda dapat menggunakan Regasm.exe untuk mendaftar.NET komponen untuk COM interop.
6. Membuat entri registri sehingga aplikasi Office dapat mengenali dan beban tambahan.

Anda dapat memilih untuk menyelesaikan semua langkah ini, atau Anda dapat membuat.NET proyek jenis Addin bersama. Ini mulai Extensibility Wizard, yang akan membantu Anda untuk membuat COM add-in di.NET.

Wisaya Extensibility menciptakan Visual C# .Proyek perpustakaan kelas NET bersama Menghubungkan kelas yang mengimplementasikan IDTExtensibility2 antarmuka. Kerangka kode sumber yang mengimplementasikan anggota kosong IDTExtensibility juga dihasilkan. Proyek ini memiliki referensi ke Extensibility dan kantor Majelis. Pengaturan membangun proyek telah Mendaftar untuk COM Interop dipilih. Majelis kunci (.snk) file yang dihasilkan dan dalam AssemblyKeyfile atribut dalam Assemblyinfo.vb.

Bersama dengan kelas Proyek Perpustakaan, Wisaya penataan proyek yang dapat Anda gunakan untuk menghasilkan menyebarkan COM add-in pada komputer lain. Anda dapat menghapus proyek ini jika dikehendaki.

Contoh langkah demi langkah

1. Pada Berkas menu di Microsoft Visual Studio.NET, klik Baru, lalu klik Project.
2. Dalam Proyek baru kotak dialog, memperluas Proyek-proyek lain di bawah Jenis proyek, pilih Proyek-proyek diperpanjang, kemudian pilih Bersama Add-in template.
3. Jenis MyCOMAddin sebagai nama Add-in dan kemudian klik Oke.
4. Ketika Wisaya Extensibility muncul, ikuti langkah berikut:
   1. Pada halaman 1, pilih Membuat Add-in menggunakan Visual C#, lalu klik Berikutnya.
   2. Pada halaman 2, pilih aplikasi host berikut, dan kemudian klik Berikutnya:
      • Microsoft Word
      • Microsoft PowerPoint
      • Microsoft Outlook
      • Microsoft Excel
      • Microsoft Access
   3. Pada halaman 3, memberikan nama dan deskripsi untuk Add-in, dan kemudian klik Berikutnya.
      
      Catatan Nama dan deskripsi tambahan muncul di COM Add-in kotak dialog di aplikasi Office.
      
      
   4. Pada halaman 4, pilih semua pilihan yang tersedia, dan kemudian Klik Berikutnya.
   5. Klik Menyelesaikan.
5. Pada Project menu, klik Menambahkan referensi. Klik System.Windows.Forms.dll dalam daftar komponen, klik Pilih, lalu klik Oke.
6. Tambahkan baris berikut ke daftar namespaces di Menghubungkan kelas:

   using System.Reflection;

7. Menambahkan anggota berikut untuk Menghubungkan kelas:

   private CommandBarButton MyButton; 

8. Menerapkan kode untuk anggota IDTExtensibility2 dalam Menghubungkan kelas, sebagai berikut:

   public void OnConnection(object application, Extensibility.ext_ConnectMode connectMode, object addInInst, ref System.Array custom) {
      applicationObject = application;
      addInInstance = addInInst;
   
      if(connectMode != Extensibility.ext_ConnectMode.ext_cm_Startup)
      {
         OnStartupComplete(ref custom);
      }
   
   }
   
   public void OnDisconnection(Extensibility.ext_DisconnectMode disconnectMode, ref System.Array custom) {
      if(disconnectMode != Extensibility.ext_DisconnectMode.ext_dm_HostShutdown)
      {
         OnBeginShutdown(ref custom);
      }
      applicationObject = null;
   }
   
   
   public void OnAddInsUpdate(ref System.Array custom)
   {
   }
   
   public void OnStartupComplete(ref System.Array custom)
   {
      CommandBars oCommandBars;
      CommandBar oStandardBar;
   
      try
      {
      oCommandBars = (CommandBars)applicationObject.GetType().InvokeMember("CommandBars", BindingFlags.GetProperty , null, applicationObject ,null);
      }
      catch(Exception)
      {
      // Outlook has the CommandBars collection on the Explorer object.
      object oActiveExplorer;
      oActiveExplorer= applicationObject.GetType().InvokeMember("ActiveExplorer",BindingFlags.GetProperty,null,applicationObject,null);
      oCommandBars= (CommandBars)oActiveExplorer.GetType().InvokeMember("CommandBars",BindingFlags.GetProperty,null,oActiveExplorer,null);
      }
   
      // Set up a custom button on the "Standard" commandbar.
      try
      {
      oStandardBar = oCommandBars["Standard"];        
      }
      catch(Exception)
      {
      // Access names its main toolbar Database.
      oStandardBar = oCommandBars["Database"];      
      }
   
      // In case the button was not deleted, use the exiting one.
      try
      {
      MyButton = (CommandBarButton)oStandardBar.Controls["My Custom Button"];
      }
      catch(Exception)
      {
         object omissing = System.Reflection.Missing.Value ;
         MyButton = (CommandBarButton) oStandardBar.Controls.Add(1, omissing , omissing , omissing , omissing);
         MyButton.Caption = "My Custom Button";
         MyButton.Style = MsoButtonStyle.msoButtonCaption;
      }
   
      // The following items are optional, but recommended. 
      //The Tag property lets you quickly find the control 
      //and helps MSO keep track of it when more than
      //one application window is visible. The property is required
      //by some Office applications and should be provided.
      MyButton.Tag = "My Custom Button";
   
      // The OnAction property is optional but recommended. 
      //It should be set to the ProgID of the add-in, so that if
      //the add-in is not loaded when a user presses the button,
      //MSO loads the add-in automatically and then raises
      //the Click event for the add-in to handle. 
      MyButton.OnAction = "!<MyCOMAddin.Connect>";
   
      MyButton.Visible = true;
      MyButton.Click += new Microsoft.Office.Core._CommandBarButtonEvents_ClickEventHandler(this.MyButton_Click);
   
   
      object oName = applicationObject.GetType().InvokeMember("Name",BindingFlags.GetProperty,null,applicationObject,null);
   
      // Display a simple message to show which application you started in.
      System.Windows.Forms.MessageBox.Show("This Addin is loaded by " + oName.ToString()   , "MyCOMAddin");
      oStandardBar = null;
      oCommandBars = null;
   }
   
   public void OnBeginShutdown(ref System.Array custom)
   {
      object omissing = System.Reflection.Missing.Value ;
      System.Windows.Forms.MessageBox.Show("MyCOMAddin Add-in is unloading.");
      MyButton.Delete(omissing);
      MyButton = null;
   }
   
   private void MyButton_Click(CommandBarButton cmdBarbutton,ref bool cancel) {
      System.Windows.Forms.MessageBox.Show("MyButton was Clicked","MyCOMAddin"); }
   					

9. Membangun dan menguji COM add-in. Untuk melakukannya, ikuti langkah-langkah:
   1. Pada Bangun menu, klik Membangun solusi. Perhatikan bahwa bangunan COM tambahan register.NET kelas dengan COM interop.
   2. Memulai salah satu aplikasi Office yang Anda pilih sebagai aplikasi untuk Anda add-in (misalnya, Microsoft Word atau Microsoft Excel).
   3. Setelah tambahan telah dimulai, OnStartupCompleteacara tambahan dipecat, dan Anda menerima pesan. Mengabaikan pesan kotak. Perhatikan bahwa tambahan menambahkan tombol kustom baru dengan Keterangan "My Custom tombol" untuk toolbar standar.
   4. Klik Tombol kustom. The Klik acara untuk tombol ditangani oleh tambahan dan Anda menerima kotak pesan. Mengabaikan kotak pesan.
   5. Berhenti aplikasi Office.
   6. Ketika Anda keluar dari aplikasi, OnBeginShutDownperistiwa kebakaran, dan Anda menerima pesan. Mengabaikan kotak pesan untuk mengakhiri demonstrasi.

Untuk informasi tambahan tentang menulis peralatan tambahan COM, klik nomor artikel di bawah ini untuk melihat artikel di dalam Basis Pengetahuan Microsoft: