Вызов кода настроек уровня документа из VBA

Статья
04/28/2010

Обновлен: Ноябрь 2007

Применение
Сведения, приведенные в данном разделе, относятся только к указанным проектам Visual Studio Tools for Office и версиям Microsoft Office. Тип проекта Проекты уровня документа Версия Microsoft Office Выпуск системы Microsoft Office 2007 Дополнительные сведения см. в разделе Доступность функций по типам приложений и проектов.

Сведения, приведенные в данном разделе, относятся только к указанным проектам Visual Studio Tools for Office и версиям Microsoft Office.

Тип проекта

Проекты уровня документа

Версия Microsoft Office

Выпуск системы Microsoft Office 2007

Дополнительные сведения см. в разделе Доступность функций по типам приложений и проектов.

Можно настроить проект уровня документа для Word 2007 или Excel 2007 таким образом, чтобы код Visual Basic для приложений (VBA) в документе мог вызывать код в сборке настройки. Это рекомендуется делать в следующих случаях.

Необходимо расширить существующий код VBA в документе с помощью возможностей решения Visual Studio Tools for Office, связанного с этим же документом.
Необходимо предоставить доступ к службам, разрабатываемым с помощью Visual Studio Tools for Office, конечным пользователям, которые могут обращаться к службам, записывая код VBA в документ.

Visual Studio Tools for Office также предоставляет подобную возможность для надстроек уровня приложения. При разработке надстройки можно вызывать код в надстройке из других решений Microsoft Office. Дополнительные сведения см. в разделе Вызов кода в надстройках уровня приложения из других решений Office.

Примечание.
Эту функцию нельзя использовать в проектах шаблонов Word. Она может быть использована только в документе Word, книге Excel или проектах Excel.

Требования

Чтобы код VBA мог быть вызван в сборке настройки, проект должен соответствовать следующим требованиям.

Документ должен иметь одно из следующих расширений имени файла:
- Для Word: DOCM или DOC
- для Excel: XLSM, XLTM, XLS или XLT.
Документ должен содержать проект VBA, который, в свою очередь, содержит код VBA.
Выполнение кода VBA в документе должно быть разрешено без вывода пользователю сообщения о необходимости включения макросов. Чтобы сделать код VBA доверенным и разрешить его выполнение, добавьте расположение проекта Visual Studio Tools for Office в список надежных расположений в параметрах центра управления безопасностью для Word или Excel.
В проект Visual Studio Tools for Office должен входить по крайней мере один открытый класс, содержащий один или несколько открытых членов, предоставляемых коду VBA.

Можно предоставлять коду VBA методы, свойства и события. Предоставляемый класс может быть классом ведущего элемента (например, ThisDocument для Word или ThisWorkbook и Sheet1 для Excel) или другим классом, определенным в проекте. Дополнительные сведения о ведущих элементах см. в разделе Общие сведения о ведущих элементах и элементах управления ведущего приложения.

Предоставление коду VBA возможности вызова кода сборки настройки

Существует два способа, с помощью которых можно предоставлять члены в сборке настройки коду VBA в документе.

Можно предоставлять члены класса ведущего элемента в проекте Visual Basic коду VBA. Для этого установите для свойства EnableVbaCallers класса ведущего элемента значение True. Visual Studio Tools for Office автоматически выполнит все действия, необходимые, чтобы позволить коду VBA вызывать члены класса.
Можно предоставлять коду VBA члены любого открытого класса в проекте Visual C# или члены класса, не являющегося классом ведущего элемента, в проекте Visual Basic. Этот вариант предоставляет более широкий выбор классов, которые можно предоставить коду VBA, но для него требуется выполнение большего количества действий вручную.

Для реализации последнего варианта необходимо вручную выполнить следующие действия.
1. Предоставьте класс модели COM.
2. Переопределите метод GetAutomationObject класса ведущего элемента проекта, чтобы получить экземпляр класса, к которому предоставляется доступ из кода VBA.
3. Задайте для свойства ReferenceAssemblyFromVbaProject любого класса ведущего элемента в проекте значение True. Это приведет к внедрению библиотеки типов сборки настройки в сборку и добавлению ссылки на библиотеку типов в проект VBA в документе.

Подробные инструкции см. в разделах Практическое руководство. Предоставление доступа к коду со стороны VBA в проекте Visual Basic и Практическое руководство. Предоставление доступа к коду со стороны VBA в проекте Visual C#.

Свойства EnableVbaCallers и ReferenceAssemblyFromVbaProject доступны только в окне Свойства во время разработки. Их нельзя использовать во время выполнения. Чтобы просмотреть свойства, откройте конструктор для ведущего элемента в Visual Studio. Дополнительные сведения о конкретных задачах, выполняемых Visual Studio Tools for Office при установке данных свойств, см. в разделе Задачи, выполняемые с помощью свойств ведущего элемента.

Примечание.
Если книга или документ не содержат кода VBA или код VBA в документе не имеет достаточного уровня доверия для выполнения, при задании для свойства EnableVbaCallers или ReferenceAssemblyFromVbaProject значения True выводится сообщение об ошибке. Это связано с тем, что в данном случае в Visual Studio Tools for Office не поддерживается изменение проекта VBA в документе.

Если книга или документ не содержат кода VBA или код VBA в документе не имеет достаточного уровня доверия для выполнения, при задании для свойства EnableVbaCallers или ReferenceAssemblyFromVbaProject значения True выводится сообщение об ошибке. Это связано с тем, что в данном случае в Visual Studio Tools for Office не поддерживается изменение проекта VBA в документе.

Использование членов кода VBA для вызова кода в сборке настройки

После настройки проекта для предоставления коду VBA возможности вызывать код в сборке настройки пакет инструментов Visual Studio Tools for Office добавляет следующие члены в проект VBA в документе.

Во все проекты пакет Visual Studio Tools for Office добавляет метод GetManagedClass.
В проектах Visual Basic, в которых члены класса ведущего элемента предоставляются с помощью свойства EnableVbaCallers, Visual Studio Tools for Office также добавляет свойство CallVSTOAssembly в модуль ThisDocument, ThisWorkbook, Sheet1, Sheet2 или Sheet3 проекта VBA.

Для доступа к открытым членам класса, предоставляемого коду VBA в проекте Visual Studio Tools for Office можно использовать свойство CallVSTOAssembly или метод GetManagedClass.

Примечание.
При разработке и развертывании решения существует несколько различных копий документа, в которые можно добавлять код VBA. Дополнительные сведения см. в разделе Правила добавления кода VBA в документ.

Использование свойства "CallVSTOAssembly" в проекте Visual Basic

Для доступа к открытым членам, добавленным к классу ведущего элемента, следует использовать свойство CallVSTOAssembly. Например, следующий макрос VBA вызывает метод MyVSTOMethod, определенный в классе Sheet1 в проекте книги Excel.

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

Данное свойство является более удобным способом вызова кода в сборке настройки, чем непосредственное использование метода GetManagedClass. Свойство CallVSTOAssembly возвращает объект, представляющий класс ведущего элемента, предоставленный коду VBA. Члены и параметры метода возвращенного объекта отображаются в IntelliSense.

Свойство CallVSTOAssembly имеет объявление, сходное со следующим кодом. В этом коде предполагается, что класс ведущего элемента Sheet1 в проекте книги Excel ExcelWorkbook1 предоставляется коду VBA.

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

Использование метода GetManagedClass

Чтобы использовать глобальный метод GetManagedClass, следует передать коду VBA объект, соответствующий классу ведущего элемента, содержащему переопределенный метод GetAutomationObject. Затем следует использовать полученный объект для доступа к классу, переданному коду VBA.

Например, следующий макрос VBA вызывает метод MyVSTOMethod, определенный в классе ведущего элемента Sheet1 в проекте книги Excel ExcelWorkbook1.

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

Метод GetManagedClass имеет следующее объявление.

GetManagedClass(pdispInteropObject Object) As Object

Этот метод возвращает объект, представляющий класс, предоставленный коду VBA. Члены и параметры метода возвращенного объекта отображаются в IntelliSense.

Правила добавления кода VBA в документ

Существует несколько различных копий документа, в которые можно добавлять код VBA, вызывающий код настройки Visual Studio Tools for Office.

В процессе разработки и тестирования решения можно записать код VBA в документ, который открывается при отладке или запуске проекта в Visual Studio (то есть документ в выходной папке построения). Однако любой добавляемый в этот документ код VBA будет перезаписан при следующем построении проекта, поскольку Visual Studio заменяет документ в выходной папке построения копией документа из главной папки проекта.

Если необходимо сохранить код VBA, добавленный в документ при отладке или выполнении решения, следует скопировать код VBA в документ из папки проекта. Дополнительные сведения о процессе построения см. в разделе Общие сведения о процессе построения решений Office.

Когда решение уже готово для развертывания, существует три основных расположения документа, в которые можно добавить код VBA.

В папке проекта на компьютере разработчика

Это расположение удобно, если необходим полный контроль как над кодом VBA в документе, так и над кодом настройки Visual Studio Tools for Office. Поскольку данный документ расположен на компьютере разработчика, можно легко изменять код VBA при изменении кода настройки. Код VBA, добавляемый к этой копии документа, сохраняется в документе при построении, отладке и публикации решения.

Нельзя добавлять код VBA в документ, открытый в конструкторе. Необходимо сначала закрыть документ в конструкторе, а затем открыть его непосредственно в Word или Excel.

Внимание!
При добавлении кода VBA, который выполняется, когда документ открыт, в редких случаях код может повредить документ или сделать невозможным его открытие в конструкторе.

В папке публикации или установки

В некоторых случаях целесообразно добавлять код VBA в документ в папке публикации или установки. Этот вариант можно выбрать, например, если код VBA написан и протестирован другим разработчиком на компьютере, на котором пакет Visual Studio Tools for Office не установлен.

Если пользователи устанавливают решение непосредственно из папки публикации, необходимо добавлять код VBA в документ при каждой публикации решения. Visual Studio перезаписывает документ в папке публикации при каждой публикации решения.

Если пользователи устанавливают решение из папки установки, отличной от папки публикации, можно избежать необходимости добавлять код VBA в документ при каждой публикации решения. Когда обновление публикации готово для перемещения из папки публикации в папку установки, следует скопировать все файлы в папку установки, кроме самого документа.

На компьютере конечного пользователя

Если конечные пользователи являются разработчиками VBA, вызывающими службы, которые предоставляются с настройкой Visual Studio Tools for Office, можно сообщить им, каким образом вызывать код с помощью свойства CallVSTOAssembly или метода GetManagedClass в их копиях документа. При публикации обновлений для решения код VBA в документе на компьютере конечного пользователя не будет перезаписан, поскольку документ не изменяется при обновлении публикации.

Задачи, выполняемые с помощью свойств ведущего элемента

При использовании свойств EnableVbaCallers и ReferenceAssemblyFromVbaProject пакет Visual Studio Tools for Office выполняет различные наборы задач.

EnableVbaCallers

Если для свойства EnableVbaCallers ведущего элемента установлено значение True в проекте Visual Basic, пакет Visual Studio Tools for Office выполняет следующие задачи.

Добавляет атрибуты ComClassAttribute и ComVisibleAttribute к классу ведущего элемента.
Переопределяет метод GetAutomationObject класса ведущего элемента.
Устанавливает для свойства ReferenceAssemblyFromVbaProject ведущего элемента значение True.

Если снова задать для свойства EnableVbaCallers значение False, пакет Visual Studio Tools for Office выполняет следующие задачи.

Удаляет атрибуты ComClassAttribute и ComVisibleAttribute из класса ThisDocument.

Удаляет метод GetAutomationObject из класса ведущего элемента.

Примечание.
Visual Studio Tools for Office не устанавливает для свойства ReferenceAssemblyFromVbaProject значение False автоматически. Можно установить для этого свойства значение False вручную с помощью окна Свойства.

ReferenceAssemblyFromVbaProject

Если для свойства ReferenceAssemblyFromVbaProject какого-либо ведущего элемента в проекте Visual Basic или Visual C# установлено значение True, пакет Visual Studio Tools for Office выполняет следующие задачи.

Создает библиотеку типов для сборки настройки и внедряет библиотеку типов в сборку.
Добавляет ссылку на следующие библиотеки типов в проекте VBA в документе.
- Библиотека типов для сборки настройки.
- Библиотека типов для ядра исполнения Microsoft Visual Studio Tools for Office Execution Engine 9.0. Эта библиотека типов включена в среду выполнения Visual Studio Tools for Office.

Если для свойства ReferenceAssemblyFromVbaProject снова установить значение False, пакет Visual Studio Tools for Office выполняет следующие задачи.

Удаляет ссылки на библиотеки типов из проекта VBA в документе.
Удаляет внедренные библиотеки типов из сборки.

Устранение неполадок

В следующей таблице приведены типичные ошибки и рекомендации по их устранению.

Ошибка	Рекомендации
После задания значения для свойства EnableVbaCallers или ReferenceAssemblyFromVbaProject появляется сообщение об ошибке с информацией о том, что документ не содержит проект VBA или отсутствуют необходимые разрешения для доступа к проекту VBA в документе.	Убедитесь, что документ в проекте содержит по крайней мере один макрос VBA, проекту VBA предоставлен достаточный уровень доверия для выполнения и проект не защищен паролем.
После задания значения для свойства EnableVbaCallers или ReferenceAssemblyFromVbaProject появляется сообщение об ошибке с информацией о том, что объявление атрибута GuidAttribute отсутствует или повреждено.	Убедитесь, что объявление атрибута GuidAttribute расположено в файле AssemblyInfo.cs или AssemblyInfo.vb проекта и для этого атрибута указан допустимый идентификатор GUID.
После задания значения для свойства EnableVbaCallers или ReferenceAssemblyFromVbaProject появляется сообщение об ошибке с информацией о том, что номер версии, указанный в атрибуте AssemblyVersionAttribute, не является допустимым.	Убедитесь, что объявление атрибута AssemblyVersionAttribute расположено в файле AssemblyInfo.cs или AssemblyInfo.vb проекта и для этого атрибута указан допустимый номер версии. Дополнительные сведения о допустимых номерах версий сборок см. в описании класса AssemblyVersionAttribute.
После переименования сборки настройки код VBA, который вызывает код сборки настройки, прекращает выполняться.	Если изменить имя сборки настройки после предоставления его коду VBA, связь между проектом VBA в документе и сборкой настройки будет нарушена. Чтобы исправить данную ошибку, следует изменить значение свойства ReferenceFromVbaAssembly в проекте на False, затем снова установить значение True. После этого следует заменить все ссылки на старое имя сборки в коде VBA на новое имя сборки.