Создание надстройки Office COM с помощью Visual C# .NET

Аннотация

Microsoft Office XP, Microsoft Office 2003 и Microsoft Office 2007 поддерживают единую архитектуру проектирования для создания надстроек приложений для улучшения и управления приложениями Office. Эти надстройки называются надстройки модели com. В этой пошаговой статье рассматриваются надстройки Office COM и описывается, как создать надстройку Office COM с помощью Microsoft Visual C# .NET.

Интерфейс IDTExensibility2

Надстройка COM — это встроенный COM-сервер или библиотека динамической компоновки ActiveX (DLL), которая реализует интерфейс IDTExensibility2, как описано в библиотеке типов конструктора надстроек Майкрософт (Msaddndr.dll). Все надстройки COM наследуются от этого интерфейса и должны реализовывать каждый из пяти методов.

OnConnection

Событие OnConnection срабатывает при каждом подключении надстройки COM. Надстройка может быть подключена при запуске, конечным пользователем или через службу автоматизации. Если событие OnConnection возвращается успешно, считается, что надстройка загружена. Если возвращается сообщение об ошибке, хост-приложение немедленно освобождает ссылку на надстройку и объект уничтожается.

Событие OnConnection принимает следующие четыре параметра:

• Приложение: ссылка на объект ведущего приложения.

• ConnectMode: константа, указывающее способ подключения надстройки. Надстройку можно подключить следующими способами:

  • ext_cm_AfterStartup: надстройка запускается пользователем из диалогового окна "Надстройки COM".
  • ext_cm_CommandLine: надстройка подключена из командной строки. Обратите внимание, что это не применяется к созданию надстроек COM для приложений Office.
  • ext_cm_External: надстройка подключается внешним приложением через службу автоматизации. Обратите внимание, что это не применяется к созданию надстроек COM для приложений Office.
  • ext_cm_Startup: надстройка запускается узлом при запуске приложения. Это поведение контролируется параметром в реестре.

• AddInInst: ссылка на объект COMAddIn, который ссылается на эту надстройку в коллекции COMAddIns для ведущего приложения.

• Пользовательская: массив значений типа Variant, который может содержать пользовательские данные.

OnDisconnection

Событие OnDisconnection срабатывает, когда надстройка COM отключена и непосредственно перед ее выгрузке из памяти. Надстройка должна выполнить очистку ресурсов в этом событии и восстановить все изменения, внесенные в ведущего приложения.

Событие OnDisconnection принимает следующие два параметра:

• RemoveMode: константа, указывающее способ отключения надстройки. Надстройку можно отключить следующими способами:

  • ext_dm_HostShutdown: при закрытии ведущего приложения надстройка отключается.
  • ext_dm_UserClosed: надстройка отключена конечным пользователем или контроллером службы автоматизации.

• Пользовательская: массив значений типа Variant, который может содержать пользовательские данные.

OnAddInsUpdate

Событие OnAddInsUpdate срабатывает при изменении набора зарегистрированных надстроек COM. Иными словами, при установке или удалении надстройки COM из ведущего приложения это событие срабатывает.

OnStartupComplete и OnBeginShutdown

Метод OnStartupComplete и метод OnBeginShutdown вызываются, когда ведущего приложения слева или переходит в состояние, в котором следует избегать взаимодействия с пользователем, так как приложение занято загрузкой или выгрузкой себя из памяти. Метод OnStartupComplete вызывается, только если надстройка была подключена во время запуска, а метод OnBeginShutdown вызывается, только если хост отключает надстройку во время завершения работы.

Так как пользовательский интерфейс ведущего приложения полностью активен при срабатывании этих событий, они могут быть единственным способом выполнения определенных действий, которые в противном случае были бы недоступны в событии OnConnection и событии OnDisconnection.

Регистрация надстройки COM

Помимо обычной регистрации COM надстройка COM должна регистрироваться в каждом приложении Office, в котором она выполняется. Чтобы зарегистрировать себя в определенном приложении, надстройка должна создать подраздел, используя свой ProgID в качестве имени ключа в следующем расположении:

HKEY_CURRENT_USER\Software\Microsoft\Office\OfficeApp\Addins\ProgID

Надстройка может предоставлять значения в этом расположении ключа как для понятного отображаемого имени, так и для полного описания. Кроме того, надстройка должна указать требуемое поведение загрузки с помощью значения DWORD с именем LoadBehavior. Это значение определяет, как надстройка загружается ведущего приложения и состоит из сочетания следующих значений:

• 0 = Отключить — не загружено.
• 1 = подключено — загружается.
• 2 = загрузка — загрузка при запуске приложения.
• 8 = DemandLoad — загрузка только при запросе пользователем.
• 16 = ConnectFirstTime — загрузить только один раз (при следующем запуске).

Обычно задается значение 0x03 (подключенные | Загрузка).

Надстройки, реализующие IDTExtensibility2, также должны указывать значение DWORD с именем CommandLineSafe , чтобы указать, являются ли надстройки безопасными для операций, не поддерживающих пользовательский интерфейс. Значение параметра 0x00 false, а значение 0x01 значение True.

Создание надстройки COM с помощью Visual C# .NET

Как упоминалось ранее, надстройка COM Office — это встроенный COM-сервер, активируемый приложением Office на уровне среды выполнения COM. Поэтому для разработки надстройки COM в .NET требуется, чтобы компонент надстройки был реализован в .NET, а затем предоставлен клиентам COM (т. е. приложениям Office) через уровень COM-взаимодействия.

Чтобы создать надстройку COM в Visual C# .NET, выполните следующие действия.

1. В Visual C# .NET создайте проект библиотеки классов.
2. Добавьте ссылку на библиотеку типов, которая реализует IDTExtensibility2. Основная сборка взаимодействия для этого уже доступна под именем "Расширяемость".
3. Добавьте ссылку на библиотеку объектов Microsoft Office. Основная сборка взаимодействия для этого уже доступна под именем Office.
4. Создайте открытый класс в библиотеке классов, реализующий IDTExtensibility2.
5. После создания библиотеки классов зарегистрируйте библиотеку для COM-взаимодействия. Для этого создайте сборку со строгим именем для этой библиотеки классов, а затем зарегистрируйте ее в COM-взаимодействии. Вы можете использовать Regasm.exe для регистрации компонента .NET для COM-взаимодействия.
6. Создайте записи реестра, чтобы приложения Office могли распознавать и загружать надстройку.

Вы можете выполнить все эти действия или создать проект .NET типа "Общая надстройка". Откроется мастер расширяемости, который поможет создать надстройку COM в .NET.

Мастер расширяемости создает проект библиотеки классов .NET для Visual C# и класс Connect, реализующий интерфейс IDTExtensibility2. Также создается каркасный код, реализующий пустые элементы IDTExtensibility. Этот проект содержит ссылки на расширяемость и сборки Office. В параметрах сборки проекта выбран параметр Register for COM Interop (Регистрация для COM-взаимодействия). Создается файл ключа сборки (SNK), на который ссылаются в атрибуте AssemblyKeyfile в Assemblyinfo.vb.

Наряду с проектом библиотеки классов мастер создает проект установки, который можно использовать для развертывания надстройки COM на других компьютерах. При необходимости этот проект можно удалить.

Пошаговый пример

1. В меню "Файл" в Microsoft Visual Studio .NET щелкните "Создать" и выберите пункт "Проект".

2. В диалоговом окне "Новый проект" разверните раздел "Другие проекты" в разделе "Типы проектов", выберите "Проекты расширяемости", а затем выберите шаблон общей надстройки.

3. Введите MyCOMAddin в качестве имени надстройки и нажмите кнопку "ОК".

4. Когда появится мастер расширяемости, выполните следующие действия.

   1. На странице 1 выберите "Создать надстройку" с помощью Visual C# и нажмите кнопку "Далее".

   2. На странице 2 выберите следующие ведущего приложения и нажмите кнопку "Далее":

      • Microsoft Word
      • Microsoft PowerPoint
      • Microsoft Outlook
      • Microsoft Excel
      • Microsoft Access

   3. На странице 3 укажите имя и описание надстройки и нажмите кнопку "Далее".

      Примечание Имя и описание надстройки отображаются в диалоговом окне надстройки COM в приложении Office.

   4. На странице 4 выберите все доступные параметры и нажмите кнопку "Далее".

   5. Нажмите кнопку "Готово".

5. On the Project menu, click Add Reference. Щелкните System.Windows.Forms.DLL в списке компонентов, нажмите кнопку "Выбрать" и нажмите кнопку "ОК".

6. Добавьте следующий код в список пространств имен в классе Connect:

   using System.Reflection;
   

7. Добавьте следующий член в класс Connect:

   private CommandBarButton MyButton;
   

8. Реализуйте код для членов IDTExtensibility2 в классе Connect следующим образом:

   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. Выполните сборку и тестирование надстройки COM. Для этого выполните следующие действия:

   1. On the Build menu, click Build Solution. Обратите внимание, что при создании надстройки COM класс .NET регистрируется с помощью COM-взаимодействия.
   2. Запустите одно из приложений Office, выбранных в качестве ведущего приложения для надстройки (например, Microsoft Word или Microsoft Excel).
   3. После запуска надстройки запускается событие OnStartupComplete надстройки, и вы получаете сообщение. Закройте окно сообщения. Обратите внимание, что надстройка добавила новую пользовательскую кнопку с заголовком "My Custom Button" (Моя настраиваемая кнопка) на стандартную панель инструментов.
   4. Нажмите кнопку "Мой пользовательский". Событие Click для кнопки обрабатывается надстройка и вы получаете окно сообщения. Закройте окно сообщения.
   5. Закройте приложение Office.
   6. При выходе из приложения срабатывает событие OnBeginShutDown, и вы получаете сообщение. Закройте окно сообщения, чтобы завершить демонстрацию.