Как создать надстройку COM (COM Add-In) для Office 2000 в Visual Basic.

На этой странице
• Введение
• Подробнее
• Ссылки

Microsoft Office 2000 и более поздние версии поддерживают новую, единую архитектуру для создания надстроек, для улучшения и управления приложениями Office. Эти дополнения называются "надстройками COM"(или "надстройками для модели компонентных объектов (COM)" - так переведено название этой команды в категории "Сервис" в моей версии Office XP. В оригинале - "COM Add-Ins". Прим. перев.). Эта статья демонстрирует пример создания надстройки COM, используя Visual Basic.

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

OnConnection

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

• Application - ссылка на интерфейс вызывающего приложения.
• ConnectMode - константа, которая определяет, как надстройка была подключена.
  • ext_cm_AfterStartup - инициализировано пользователем из диалогового окна "Надстройки для модели компонентных объектов (COM)".
  • ext_cm_CommandLine - подключение из командной строки.(Неприменимо к COM add-ins для приложений Office.)
  • ext_cm_External - подключение от внешнего приложения через автоматизацию.(Неприменимо к COM add-ins для приложений Office.)
  • ext_cm_Startup - инициализировано вызывающим приложением при запуске. (Этим режимом можно управлять установками в системном реестре.)
• AddInInst - ссылка на объект COMAddIn, которая заносит этот модуль в коллекцию COMAddIns для вызывающего приложения.
• Custom - массив Variant, который может содержать определяемые пользователем данные.(Насколько я знаю, в Microsoft Office не используется. Прим. перев.)

OnDisconnection

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

• RemoveMode - константа, которая определяет, как надстройка была отключена.
  • ext_dm_HostShutdown - Отключено, когда закрылось основное приложение.
  • ext_dm_UserClosed - Отключено пользователем или диспетчером Автоматизации.
• Custom - массив Variant, который может содержать определяемые пользователем данные.

OnAddInsUpdate

Событие OnAddInsUpdate происходит при изменении количества зарегистрированных надстроек COM. Другими словами, когда COM add-in устанавливается или удаляется из вызывающего приложения.

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

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

В дополнение к нормальной регистрации COM ( например, с помощью RegSvr32.exe - прим.перев.), COM Add-In должен быть зарегистрирован для каждого приложения Office, в котором он выполняется. Чтобы надстройка была зарегистрирована с определённым приложением, необходимо создать раздел (sub key), используя свой ProgID как имя ключа (название_проекта.имя_класса . Прим. перев.), в следующем разделе реестра:

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

• 0 = Disconnect - Не загружено.
• 1 = Connected - Загружено.
• 2 = Bootload - Загрузка при старте приложения.(Без подключения. Прим. перев.)
• 8 = DemandLoad - Загрузка по требованию пользователя.
• 16 = ConnectFirstTime - Загружается только один раз (при следующем старте вызывающего приложения).

Типичное значение - 0x03 (Connected|Bootload. Подключение при старте приложения).

Создание COM Add-In

Создание надстройки, с помощью шаблона (Com Add-in Template).

Если Вы располагаете Microsoft Office 2000 Developer или Microsoft Office XP Developer и Visual Basic 6.0, самый легкий способ создания COM Add-In - использовать COM Add-in.vbp шаблон. Этот проект расположен в директории ODETools\V9\Samples\OPG\Samples\CH11\VB _COM_AddIn на CD Office 2000 Developer. Скопируйте файлы из этой папки в папку Visual Basic 6.0 Template\Projects, которая находится обычно в C:\Program Files\Microsoft Visual Studio\VB98\Template\Projects. Копирование проекта шаблона в это место будет гарантировать, что шаблон появится в диалоговом окне New Project Visual Basic 6.0. См. Главу 11 Руководства для программиста Microsoft Office 2000 Visual Basic для получения дополнительной информации об этом шаблоне и создании COM Add-ins.

Создание COM Add-In используя VB6 Add-in Designer.

1. Запустите Microsoft Visual Basic 6.0 и выберите Addin как тип проекта. Это должно добавить к проекту класс (Connect) и форму (frmAddin).
2. Откройте окно Designer для Connect и выберите Microsoft Excel в ниспадающем меню Application.
3. В ниспадающем меню Initial Load Behavior , выберите Startup.
4. Удалите frmAddin из проекта.
5. В окне Project кликните правой кнопкой пункт Connect и выберите View Code.
6. Удалите весь код в окне. Этот код работает для надстроек к VB, но не для надстроек к Office.
7. Добавьте следующий код:

   Option Explicit Dim oXL As Object Dim WithEvents MyButton As Office.CommandBarButton Private Sub AddinInstance_OnConnection(ByVal Application As Object, _ ByVal ConnectMode As AddInDesignerObjects.ext_ConnectMode, _ ByVal AddInInst As Object, custom() As Variant) On Error Resume Next MsgBox "My Addin started in " & Application.Name Set oXL = Application Set MyButton = oXL.CommandBars("Standard").Controls.Add(1) With MyButton .Caption = "My Custom Button" .Style = msoButtonCaption ' Следующий пункт дополнительный, но рекомендуется. ' Свойство Tag позволяет Вам быстро найти control ' и помогает MSO сохранить путь к нему когда открыто ' несколько окон приложений. Свойство востребовано ' некоторыми приложениями Office и должно быть предусмотрено. .Tag = "My Custom Button" ' Свойство OnAction дополнительное, но рекомендуется. ' Оно должно быть установлено в ProgID надстройки, так, чтобы ' если add-in не загружен, по нажатию кнопки пользователем, ' MSO автоматически загружает надстройку и затем обрабатывает ' событие Click для надстройки. .OnAction = "!<" & AddInInst.ProgId & ">" .Visible = True End With End Sub Private Sub AddinInstance_OnDisconnection(ByVal RemoveMode As _ AddInDesignerObjects.ext_DisconnectMode, custom() As Variant) On Error Resume Next MsgBox "My Addin was disconnected by " & _ IIf(RemoveMode = ext_dm_HostShutdown, _ "Excel shutdown.", "end user.") MyButton.Delete Set MyButton = Nothing Set oXL = Nothing End Sub Private Sub MyButton_Click(ByVal Ctrl As Office.CommandBarButton, _ CancelDefault As Boolean) MsgBox "Our CommandBar button was pressed!" End Sub

8. Сохраните проект и создайте MyAddin.dll. Ваша надстройка будет зарегистрирована.
9. Откройте Microsoft Excel и Вы увидите в окне сообщения о загрузке или выгрузке надстройки. На Стандартной панели инструментов (Standart), будет находиться новая кнопка My Custom Button, нажатие на которую будет обработано вашей надстройкой.

Создание COM Add-In с помощью Implements.

С другой стороны, можно создать COM Add-In, используя Microsoft Visual Basic 5.0 и ключевое слово Implement для непосредственной реализации интерфейса IDTExtensibility2. Единственное неудобство в таком подходе - регистрация. Так как Microsoft Visual Basic не знает как добавлять ключи, необходимые для регистрации надстройки к Office, Вы должны сделать это самостоятельно (отдельной утилитой, или применив REG-скрипт).

Тем не менее преимущество Implements в том, что этот путь более прямой и эффективный, нежели использование VB6 Add-in Designer, и это даёт возможность для создания единственного COM объекта, который может работать с несколькими приложениями Office (вместо создания отдельного подключения объекта для каждого приложения, с которым мы хотим работать).

Ниже последовательность действий для написания надстройки, применяя Implements:

1. Откройте Visual Basic и создайте новый проект ActiveX DLL. Имя проекта MyCOMAddin, и имя класса Connect.
2. В диалоговом окне References (Project | References), добавьте ссылку на библиотеку объектов (Object Library) Microsoft Office 9.0 (или 10.0 для Office XP) и библиотеку типов (type library) Microsoft Add-In Designer. Если Вы не можете найти Add-In Designer в списке, найдите в браузере Msaddndr.dll или Msaddndr.tlb, расположенные, как правило, в папке "C:\Program Files\Common Files\Designer".
3. В окне Code для Connect, добавьте следующее:

   Option Explicit Implements IDTExtensibility2 Dim oHostApp As Object Dim WithEvents MyButton As Office.CommandBarButton Private Sub IDTExtensibility2_OnConnection(ByVal Application As Object, _ ByVal ConnectMode As AddInDesignerObjects.ext_ConnectMode, _ ByVal AddInInst As Object, custom() As Variant) On Error Resume Next ' Установка ссылки на вызывающее приложение... Set oHostApp = Application ' Если не при запуске, то вызов OnStartupComplete вручную... If (ConnectMode <> ext_cm_Startup) Then _ Call IDTExtensibility2_OnStartupComplete(custom) End Sub Private Sub IDTExtensibility2_OnStartupComplete(custom() As Variant) Dim oCommandBars As Office.CommandBars Dim oStandardBar As Office.CommandBar On Error Resume Next ' Устанока своей кнопки на панель "Standard"... Set oCommandBars = oHostApp.CommandBars If oCommandBars Is Nothing Then 'Outlook has the CommandBars collection on the Explorer object Set oCommandBars = oHostApp.ActiveExplorer.CommandBars End If Set oStandardBar = oCommandBars.Item("Standard") If oStandardBar Is Nothing Then ' В Access главная панель инструментов - Database Set oStandardBar = oCommandBars.Item("Database") End If ' В случае, если кнопка не была удалена, выход такой Set MyButton = oStandardBar.Controls.Item("My Custom Button") If MyButton Is Nothing Then Set MyButton = oStandardBar.Controls.Add(1) With MyButton .Caption = "My Custom Button" .Style = 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 there is more than ' one application window visible. The property is required ' by some Office applications and should be provided. .Tag = "My Custom Button" ' The OnAction property is optional but recommended. ' It should be set to the ProgID of the add-in, such 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. .OnAction = "!<MyCOMAddin.Connect>" .Visible = True End With End If ' Простое сообщение, чтобы знать, в каком приложении Вы запустили... MsgBox "Started in " & oHostApp.Name & "." Set oStandardBar = Nothing Set oCommandBars = Nothing End Sub Private Sub IDTExtensibility2_OnDisconnection(ByVal RemoveMode As _ AddInDesignerObjects.ext_DisconnectMode, custom() As Variant) On Error Resume Next If RemoveMode <> ext_dm_HostShutdown Then _ Call IDTExtensibility2_OnBeginShutdown(custom) Set oHostApp = Nothing End Sub Private Sub IDTExtensibility2_OnBeginShutdown(custom() As Variant) On Error Resume Next ' Уведомление пользователя о завершении, и удаляете кнопку... MsgBox "Our custom Add-In is unloading." MyButton.Delete Set MyButton = Nothing End Sub Private Sub MyButton_Click(ByVal Ctrl As Office.CommandBarButton,_ CancelDefault As Boolean) MsgBox "Our CommandBar button was pressed!" End Sub Private Sub IDTExtensibility2_OnAddInsUpdate(custom() As Variant) 'Здесь ничего не делается,но комментарий должен быть 'так Visual Basic корректно всё выполнит... End Sub

4. Запишите проект и создайте MyCOMAddin.dll. Но перед запуском вашей надстройки, Вам необходимо ассоциировать её с каждым приложением Office с которым надстройка должна работать. В действительности это может делать утилита установки в момент инсталляции DLL (обычно используют RegSvr32.exe. Прим. перев.). В этом примере, Вы вызываете функцию регистрации непосредственно из Visual Basic IDE.
5. Добавьте новый модуль в проект . В коде для Module1, добавьте следующее:

   Option Explicit Private Declare Function RegCreateKeyEx Lib "advapi32.dll" _ Alias "RegCreateKeyExA" (ByVal hKey As Long, ByVal lpSubKey As String, _ ByVal Reserved As Long, ByVal lpClass As String, ByVal dwOptions As _ Long, ByVal samDesired As Long, ByVal lpSecurityAttributes As Long, _ phkResult As Long, lpdwDisposition As Long) As Long Private Declare Function RegSetValueEx Lib "advapi32.dll" _ Alias "RegSetValueExA" (ByVal hKey As Long, ByVal lpValueName As _ String, ByVal Reserved As Long, ByVal dwType As Long, lpData As Any, _ ByVal cbData As Long) As Long Private Declare Function RegDeleteKey Lib "advapi32.dll" _ Alias "RegDeleteKeyA" (ByVal hKey As Long, ByVal lpSubKey As String) _ As Long Private Declare Function RegCloseKey Lib "advapi32.dll" _ (ByVal hKey As Long) As Long Private Const HKEY_CURRENT_USER = &H80000001 Private Const KEY_ALL_ACCESS = &H1F0037 Private Const REG_CREATED_NEW_KEY = &H1 Private Const REG_SZ = 1 Private Const REG_DWORD = 4 'These are the settings for your Add-in... Private Const PROGID As String = "MyCOMAddin.Connect" Private Const DESCRIPTION As String = "My VB5/6 COM Add-In Sample" Private Const LOADBEHAVIOR As Long = 3 Private Const SAFEFORCOMMANDLINE As Long = 0 Public Sub RegisterAll() RegisterOfficeAddin "Access" RegisterOfficeAddin "Excel" RegisterOfficeAddin "FrontPage" RegisterOfficeAddin "Outlook" RegisterOfficeAddin "PowerPoint" RegisterOfficeAddin "Word" End Sub Public Sub UnregisterAll() UnRegisterOfficeAddin "Access" UnRegisterOfficeAddin "Excel" UnRegisterOfficeAddin "FrontPage" UnRegisterOfficeAddin "Outlook" UnRegisterOfficeAddin "PowerPoint" UnRegisterOfficeAddin "Word" End Sub Public Sub RegisterOfficeAddin(sTargetApp As String) Dim sRegKey As String Dim nRet As Long, dwTmp As Long Dim hKey As Long sRegKey = "Software\Microsoft\Office\" & sTargetApp _ & "\Addins\" & PROGID nRet = RegCreateKeyEx(HKEY_CURRENT_USER, sRegKey, 0, _ vbNullString, 0, KEY_ALL_ACCESS, 0, hKey, dwTmp) If nRet = 0 Then If dwTmp = REG_CREATED_NEW_KEY Then Call RegSetValueEx(hKey, "FriendlyName", 0, _ REG_SZ, ByVal PROGID, Len(PROGID)) Call RegSetValueEx(hKey, "Description", 0, _ REG_SZ, ByVal DESCRIPTION, Len(DESCRIPTION)) Call RegSetValueEx(hKey, "LoadBehavior", 0, _ REG_DWORD, LOADBEHAVIOR, 4) Call RegSetValueEx(hKey, "CommandLineSafe", 0, _ REG_DWORD, SAFEFORCOMMANDLINE, 4) End If Call RegCloseKey(hKey) End If End Sub Public Sub UnRegisterOfficeAddin(sTargetApp As String) Dim sRegKey As String sRegKey = "Software\Microsoft\Office\" & sTargetApp _ &"\Addins\" & PROGID Call RegDeleteKey(HKEY_CURRENT_USER, sRegKey) End Sub

6. В окне Immediate (View | Immediate Window), напечатайте RegisterAll, и затем нажмите ENTER. Это зарегистрирует надстройку со всеми приложениями Office (Access, Excel, FrontPage, Outlook, PowerPoint, and Word).
7. Откройте любое из вышеперечисленных приложений Office. Обратите внимание на окно сообщений при запуске и завершении, и на кнопку, добавленную на стандартную панель инструментов.
8. Если Вам нужно отменить регистрацию надстройки,наберите UnregisterAll в окне Visual Basic Immediate и затем нажмите ENTER.( Я использовал RegSvr32.exe с опцией /u . Прим. перев.)

Ссылки

"Microsoft Office 2000 Visual Basic Programmer's Guide", Chapter 11. Add-ins, Templates, Wizards, and Libraries.

Для дополнительной информации о написании COM Add-ins, пожалуйста, кликните на номерах статей в Microsoft Knowledge Base:

230689 Пример: Comaddin.exe Office 2000 COM Add-In в Visual C++

190253 Информация: VB6 Designers не работает в VB5

За дополнительной информацией о разработке Web приложений для Microsoft Internet Explorer, посетите следующие сайты Microsoft:
http://msdn.microsoft.com/workshop/entry.asp
http://msdn.microsoft.com/ie/
http://support.microsoft.com/?scid=http://support.microsoft.com/...

Замечания переводчика:

Перевод этой статьи изначально был предназначен только лишь для личного использования. Переведены были только некоторые неизвестные мне на тот момент термины и слова, и, как следствие, текст понятен был лишь только мне, и разбирающимся в VB товарищам (которым сам перевод, собственно говоря, не нужен вовсе - им всё понятно из листинга примеров :). Это моя первая попытка "собрать" нечто "читабельное", поэтому прошу не судить слишком строго. Я постарался оставить стилистику и построение перевода наиболее близко к оригиналу, листинги примеров изменены только лишь в некоторых комментариях.