Как создать надстройку COM для Microsoft Office с помощью Visual C# .NET

Переводы статьи Переводы статьи
Код статьи: 302901 - Vizualiza?i produsele pentru care se aplic? acest articol.
Развернуть все | Свернуть все

В этой статье

Аннотация

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

Интерфейс IDTExensibility2

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

OnConnection

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

Событие OnConnection имеет следующие четыре параметра.
  • Application — ссылка на объект главного приложения.
  • ConnectMode — константа, указывающая способ подключения надстройки. Надстройка может подключаться следующими способами.
    • ext_cm_AfterStartup — надстройка запускается конечным пользователем из диалогового окна Надстройки COM.
    • ext_cm_CommandLine — надстройка подключается из командной строки. Следует помнить, что это не относится к созданию надстроек COM для приложений Office.
    • ext_cm_External — надстройка подключается внешним приложением через интерфейс Automation. Следует помнить, что это не относится к созданию надстроек COM для приложений Office.
    • ext_cm_Startup — надстройка запускается при запуске главного приложения. Это поведение управляется параметром системного реестра.
  • AddInInst — ссылка на объект COMAddIn, который ссылается на эту надстройку в коллекции COMAddIns для главного приложения.
  • Custom — массив значений типа Variant, который может содержать определенные пользователем данные.

OnDisconnection

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

Событие OnDisconnection имеет следующие два параметра.
  • RemoveMode — константа, указывающая, как была отключена надстройка. Надстройка может быть отключена следующими способами.
    • ext_dm_HostShutdown — надстройка отключается при закрытии главного приложения.
    • ext_dm_UserClosed — надстройка отключается конечным пользователем или контроллером Automation.
  • Custom — массив значений типа 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 = Disconnect — не загружено.
  • 1 = Connected — загружено.
  • 2 = Bootload — загрузка при запуске приложения.
  • 8 = DemandLoad — загрузка только по требованию пользователя.
  • 16 = ConnectFirstTime — однократная загрузка (при следующем запуске).
Стандартное значение — 0x03 (загружено | загрузка при запуске приложения).

Надстройка, использующая интерфейс IDTExtensibility2, также должна указать параметр типа DWORD с именем
CommandLineSafe
, указывающий, является ли надстройка безопасной для выполнения операций, которые не поддерживают интерфейс пользователя. Значение 0x01 («Истина») указывается, если надстройка является таковой, а значение 0x00 («Ложь») — если нет.

Инструкции по созданию надстройки с помощью Visual С# .NET

Как упоминалось выше, надстройка COM для Microsoft Office представляет собой внутрипроцессный сервер COM, который активируется приложением Microsoft Office через подключаемый при выполнении уровень COM. Таким образом, разработка надстройки COM в .NET требует, чтобы компонент надстройки был разработан в .NET, а затем сделан доступным клиентам COM (то есть приложениям Microsoft Office) через уровень взаимодействия COM.

Чтобы создать надстройку COM в Visual C# .NET, выполните следующие действия.
  1. В Visual C# .NET создайте проект библиотеки классов.
  2. Добавьте ссылку в библиотеку типов, которая реализует IDTExtensibility2. Исходная сборка взаимодействия для этого интерфейса доступна под именем Extensibility.
  3. Добавьте ссылку на библиотеку объектов Microsoft Office. Исходная сборка взаимодействия для нее доступна под именем Office.
  4. Создайте открытый класс в библиотеке классов, которая реализует интерфейс IDTExtensibility2.
  5. После построения библиотеки классов зарегистрируйте библиотеку для взаимодействия с COM. С этой целью создайте для данной библиотеки классов сборку со строгим именем и зарегистрируйте ее, используя взаимодействие с COM. Регистрацию компонента .NET для взаимодействия с COM можно выполнить с помощью программы Regasm.exe.
  6. Чтобы приложения Microsoft Office могли обнаружить и загрузить надстройку, создайте соответствующие записи в реестре.
Можно выполнить все эти действия или же создать проект .NET типа Shared Addin (совместно используемая надстройка). Это приведет к запуску мастера расширяемости, который поможет создать надстройку COM в .NET.

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

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

Пример по действиям

  1. В меню Файл приложения Microsoft Visual Studio .NET выберите команду Создать, а затем — Проект.
  2. В диалоговом окне New Project (Создать проект) разверните список Other Projects (Другие проекты) в группе Project Types (Типы проектов), выберите пункт Extensibility Projects (Проекты расширяемости), а затем — шаблон Shared Add-in (Совместно используемая надстройка).
  3. Введите MyCOMAddin в качестве имени надстройки и нажмите кнопку ОК.
  4. После запуска мастера расширяемости выполните следующие действия.
    1. В первом окне выберите параметр Create an Add-in using Visual C# (Создать надстройку с помощью Visual C#) и нажмите кнопку Далее.
    2. Во втором окне выберите следующие главные приложения и нажмите кнопку Далее:
      • Microsoft Word
      • Microsoft PowerPoint
      • Microsoft Outlook
      • Microsoft Excel
      • Microsoft Access
    3. В третьем окне введите имя и описание надстройки, а затем нажмите кнопку Далее.

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

    4. В четвертом окне выберите доступные параметры и нажмите кнопку Далее.
    5. Нажмите кнопку Готово.
  5. В меню Project (Проект) выберите команду Add Reference (Добавить ссылку). В списке компонентов выберите System.Windows.Forms.DLL, нажмите кнопку Выбрать, а затем — OK.
  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 имеет набор CommandBars в объекте Explorer.
       object oActiveExplorer;
       oActiveExplorer= applicationObject.GetType().InvokeMember("ActiveExplorer",BindingFlags.GetProperty,null,applicationObject,null);
       oCommandBars= (CommandBars)oActiveExplorer.GetType().InvokeMember("CommandBars",BindingFlags.GetProperty,null,oActiveExplorer,null);
       }
    
       // Настройка пользовательской кнопки в  панели команд Стандартная.
       try
       {
       oStandardBar = oCommandBars["Standard"];        
       }
       catch(Exception)
       {
       // В Access основная панель задач называется Database.
       oStandardBar = oCommandBars["Database"];      
       }
    
       // Если кнопка не была удалена, используется существующая.
       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;
       }
    
       // Следующие элементы необязательные, но рекомендуемые. 
       //Свойство Tag помогает быстро найти орган управления
       //и помогает MSO отслеживать его, если видимо 
       //более одного окна приложения. Это свойство требуется
       //для некоторых приложений Office и должно быть предоставлено.
       MyButton.Caption = "My Custom Button";
    
       // Свойство OnAction необязательное, но рекомендуемое. 
       //Его необходимо установить на ProgID надстройки, поэтому если даже 
       //надстройка не загружается при нажатии кнопки пользователем,
       //MSO загружает надстройку автоматически и затем вызывает
       //событие Click для надстройки, чтобы обработать его. 
       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);
    
       // Выводит простое сообщение, показывающее, из какого приложения запущена надстройка.
       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. В меню Build выберите команду Build Solution. Обратите внимание, что при сборке надстройки COM класс .NET регистрируется при помощи взаимодействия с COM.
    2. Запустите одно из приложений Office, которое было выбрано главным для надстройки (например Microsoft Word или Microsoft Excel).
    3. После запуска надстройки будет вызвано событие OnStartupComplete данной надстройки и появится окно сообщения. Закройте это окно. Обратите внимание, что надстройка добавляет на панель задач новую кнопку с надписью «Моя пользовательская кнопка».
    4. Нажмите кнопку Моя настраиваемая кнопка. При этом надстройка обработает событие Click для данной кнопки и на экране появится окно сообщения. Закройте это окно.
    5. Закройте приложение Office.
    6. При закрытии приложения будет вызвано событие OnBeginShutDown и появится соответствующее сообщение. Для завершения демонстрации закройте окно с сообщением.

Ссылки

Для получения дополнительных сведений о создании надстроек COM щелкните номер следующей статьи базы знаний Майкрософт:
190253 СВЕДЕНИЯ: Конструкторы VB6 не работают в VB5 (Эта ссылка может указывать на содержимое полностью или частично на английском языке)

Свойства

Код статьи: 302901 - Последний отзыв: 17 апреля 2007 г. - Revision: 8.1
Информация в данной статье относится к следующим продуктам.
  • Microsoft Visual C# .NET 2003 Standard Edition
  • Microsoft Visual C# .NET 2002 Standard Edition
  • Microsoft Office Excel 2003
  • Microsoft Excel 2002 Standard Edition
  • Microsoft Office Outlook 2003
  • Microsoft Outlook 2002 Standard Edition
  • Microsoft Office PowerPoint 2003
  • Microsoft PowerPoint 2002 Standard Edition
  • Microsoft Office Word 2003
  • Microsoft Word 2002 Standard Edition
Ключевые слова: 
kbautomation kbhowtomaster KB302901

Отправить отзыв

 

Contact us for more help

Contact us for more help
Connect with Answer Desk for expert help.
Get more support from smallbusiness.support.microsoft.com