Отладка надстроек Office в Visual Studio

В этой статье описывается отладка клиентского кода в надстройках Office, созданных с помощью одного из шаблонов проектов надстройки Office в Visual Studio 2022. Сведения об отладке кода на стороне сервера в надстройках Office см. в статье Обзор отладки надстроек Office на стороне сервера или на стороне клиента?

Примечание.

Visual Studio нельзя использовать для отладки надстроек в Office на Mac. Сведения об отладке на компьютере Mac см. в статье Отладка надстроек Office на компьютере Mac.

Просмотр параметров сборки и отладки

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

Свойства проекта надстройки

Откройте окно Свойства для проекта надстройки, чтобы просмотреть свойства проекта.

  1. В Обозревателе решений выберите проект надстройки (не проект веб-приложения).

  2. В панели меню выберите Вид>Окно свойств.

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

Свойство Описание
Действие при запуске Определяет режим отладки для вашей надстройки. Для надстройки Outlook необходимо задать значение Microsoft Edge . Для всех остальных приложений Office он должен иметь значение Классический клиент Office.
Начальный документ
(только для надстроек Excel, PowerPoint и Word)
Указывает, какой документ следует открыть при запуске проекта. В новом проекте задано значение [Новая книга Excel], [Новый Word документ] или [Новая презентация PowerPoint]. Чтобы указать конкретный документ, выполните действия, описанные в разделе Использование существующего документа для отладки надстройки.
Веб-проект Определяет имя веб-проекта, связанного с надстройкой.
Адрес электронной почты
(только для надстроек Outlook)
Указывает адрес электронной почты учетной записи пользователя на сервере Exchange Server или Exchange Online, который вы хотите использовать для проверки надстройки Outlook. Если оставить пустым, при запуске отладки вам будет предложено ввести адрес электронной почты.
EWS Url
(только для надстроек Outlook)
Указывает URL-адрес веб-служб Exchange (например, https://www.contoso.com/ews/exchange.aspx). Это свойство можно оставить пустым.
URL-адрес OWA
(только для надстроек Outlook)
Указывает URL-адрес Outlook в Интернете (например, https://www.contoso.com/owa). Это свойство можно оставить пустым.
Использование многофакторной проверки подлинности
(только для надстроек Outlook)
Указывает логическое значение, указывающее, следует ли использовать многофакторную проверку подлинности. Значение по умолчанию равно false, но свойство не имеет практического действия. Если для входа в учетную запись электронной почты обычно требуется указать второй фактор, при запуске отладки вам будет предложено выполнить его.
Имя пользователя
(только для надстроек Outlook)
Определяет имя учетной записи на сервере Exchange Server или Exchange Online, которое вы хотите использовать для проверки вашей надстройки Outlook. Это свойство можно оставить пустым.
Файл проекта Задает имя файла, в котором указаны сборка, конфигурация и другие сведения о проекте.
Папка проекта Указывает расположение файла проекта.

Примечание.

Для надстройки Outlook можно указать значения только для одного или нескольких свойств надстройки Outlook в окне Свойства , но это необязательно.

Свойства проекта веб-приложения

Откройте окно Свойства для проекта веб-приложения, чтобы просмотреть свойства проекта.

  1. В Обозреватель решений выберите проект веб-приложения.

  2. В панели меню выберите Вид>Окно свойств.

В таблице ниже описаны свойства проекта веб-приложения, которые наиболее подходят для проектов надстройки Office.

Свойство Описание
SSL включен Указывает, включен ли SSL на сайте. Это свойство должно иметь значение True для проектов надстройки Office.
URL-АДРЕС SSL Задает защищенный HTTPS URL-адрес сайта. Только для чтения.
URL Задает HTTP URL-адрес сайта. Только для чтения.
Файл проекта Задает имя файла, в котором указаны сборка, конфигурация и другие сведения о проекте.
Папка проекта Указывает расположение файла проекта. Только для чтения. Файл манифеста, который генерирует Visual Studio во время выполнения, записывается в папку bin\Debug\OfficeAppManifests в этом расположении.

Отладка проекта надстройки Excel, PowerPoint или Word

В этом разделе описывается запуск и отладка надстройки Excel, PowerPoint или Word.

Запуск проекта надстройки Excel, PowerPoint или Word

Запустите проект, выбрав Отладка>Начать отладку в строке меню или нажмите кнопку F5. Visual Studio автоматически создаст решение и запустит ведущее приложение Office.

Когда Visual Studio создает проект, она выполняет следующие задачи:

  1. Создает копию XML-файла манифеста и добавляет ее в _ProjectName_\bin\Debug\OfficeAppManifests каталог. Приложение Office, в котором размещается надстройка, использует эту копию при запуске Visual Studio и отладке надстройки.

  2. Создает набор записей реестра на компьютере с Windows, который позволяет надстройке отображаться в приложении Office.

  3. Создает проект веб-приложения, а затем развертывает его на локальном веб-сервере IIS (https://localhost).

  4. Если это первый проект надстройки, развернутый на локальном веб-сервере IIS, может появиться запрос на установку сертификата Self-Signed в хранилище доверенных корневых сертификатов текущего пользователя. Это необходимо для того, чтобы приложение IIS Express отображало содержимое вашей надстройки правильно.

Примечание.

Если Office использует устаревший элемент управления webview Edge (EdgeHTML) для запуска надстроек на компьютере с Windows, Visual Studio может предложить добавить исключение из локальной сети. Это необходимо для того, чтобы элемент управления webview имел доступ к веб-сайту, развернутый на локальном веб-сервере IIS. Эту настройку также можно изменить в любое время в Visual Studio в разделе Инструменты>Параметры>Средства Office (веб)>Отладка веб-настройки. Сведения об элементе управления webview, используемом на компьютере с Windows, см. в статье Браузеры и элементы управления webview, используемые надстройками Office.

Затем Visual Studio выполняет следующее:

  1. Изменяет элемент SourceLocation XML-файла манифеста (скопированного в _ProjectName_\bin\Debug\OfficeAppManifests каталог), заменяя ~remoteAppUrl маркер полным адресом начальной страницы (например, https://localhost:44302/Home.html).

  2. Запускает проект веб-приложения в IIS Express.

  3. Проверяет манифест.

    Важно!

    XSD-файлы манифеста Office, устанавливаемые Visual Studio, устарели. Если возникают ошибки проверки манифеста, первым шагом по устранению неполадок должно быть замена одного или нескольких из этих файлов последними версиями. Подробные инструкции см. в статье Ошибки проверки схемы манифеста в проектах Visual Studio.

  4. Открывает приложение Office и загружает неопубликованную надстройку.

Отладка надстройки Excel, PowerPoint или Word

Лучший способ отладки надстройки в Visual Studio 2022 зависит от того, выполняется ли надстройка в WebView2, который является элементом управления webview, связанным с Microsoft Edge (Chromium), или старым элементом управления webview. Чтобы определить, какой элемент управления webview используется, см. статью Браузеры и элементы управления webview, используемые надстройками Office. Если компьютер использует WebView2, см . статью Использование встроенного отладчика Visual Studio. Сведения о любом другом элементе управления webview см. в разделе Использование средств разработчика браузера.

Использование встроенного отладчика Visual Studio

  1. При необходимости устанавливайте точки останова в исходных файлах JavaScript или TypeScript. Это можно сделать до или после запуска надстройки, как описано в предыдущем разделе Запуск проекта надстройки Excel, PowerPoint или Word.

  2. Когда надстройка запущена, используйте пользовательский интерфейс надстройки для выполнения кода, содержащего точки останова.

Важно!

Точки останова, заданные Office.initialize или Office.onReady не попадают. Сведения об отладке этих методов см . в разделе Отладка функций initialize и onReady.

Совет

Если у вас возникли проблемы, дополнительные сведения см . в статье Отладка приложения JavaScript или TypeScript в Visual Studio.

Использование средств разработчика браузера

  1. Выполните действия, описанные в предыдущем разделе Запуск проекта надстройки Excel, PowerPoint или Word.

  2. Запустите надстройку в приложении Office, если она еще не открыта. Например, если это надстройка области задач, она добавит кнопку на ленту Главная (например, кнопка Показать область задач ). Нажмите кнопку на ленте.

    Примечание.

    Если надстройка не загружается неопубликованным visual Studio, ее можно загрузить вручную. Следуйте инструкциям, чтобы загрузить неопубликованную надстройку Office для тестирования для вашей платформы.

    В списке доступных надстроек найдите раздел Надстройки разработчика и выберите вашу надстройку, чтобы зарегистрировать ее.

    Совет

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

  3. Откройте меню личных данных и выберите Подключить отладчик. Откроется средство отладки для элемента управления webview, используемого Office для запуска надстроек на компьютере Windows. Вы можете задать точки останова и выполнить пошаговое выполнение кода, как описано в одной из следующих статей:

  4. Чтобы внести изменения в код, сначала остановите сеанс отладки в Visual Studio и закройте приложение Office. Внесите изменения и запустите новый сеанс отладки.

Отладка проекта надстройки Outlook

В этом разделе описывается запуск и отладка надстройки Outlook. Отладка выполняется в Outlook в Интернете, а не в Outlook в Windows.

Запуск проекта надстройки Outlook

Запустите проект, выбрав Отладка>Начать отладку в строке меню или нажмите кнопку F5. Visual Studio автоматически создаст решение и запустит страницу Outlook клиента Microsoft 365.

Когда Visual Studio создает проект, он выполняет следующие задачи.

  1. Запрашивает учетные данные для входа. Если вам будет предложено выполнить вход несколько раз или вы получаете сообщение об ошибке, что вы не авторизованы, обычная проверка подлинности может быть отключена для учетных записей в клиенте Microsoft 365. В этом случае попробуйте использовать учетную запись Майкрософт. Вы также можете попробовать установить для свойства Использовать многофакторную проверку подлинностизначение True в области свойств проекта надстройки Outlook Web. См . раздел Свойства проекта надстройки.

  2. Создает копию XML-файла манифеста и добавляет ее в _ProjectName_\bin\Debug\OfficeAppManifests каталог. Outlook использует эту копию при запуске Visual Studio и отладке надстройки.

  3. Создает проект веб-приложения, а затем развертывает его на локальном веб-сервере IIS (https://localhost).

  4. Если это первый проект надстройки, развернутый на локальном веб-сервере IIS, может появиться запрос на установку сертификата Self-Signed в хранилище доверенных корневых сертификатов текущего пользователя. Это необходимо для того, чтобы приложение IIS Express отображало содержимое вашей надстройки правильно.

Примечание.

Если Office использует устаревший элемент управления webview Edge (EdgeHTML) для запуска надстроек на компьютере с Windows, Visual Studio может предложить добавить исключение из локальной сети. Это необходимо для того, чтобы элемент управления webview имел доступ к веб-сайту, развернутый на локальном веб-сервере IIS. Эту настройку также можно изменить в любое время в Visual Studio в разделе Инструменты>Параметры>Средства Office (веб)>Отладка веб-настройки. Сведения об элементе управления webview, используемом на компьютере с Windows, см. в статье Браузеры и элементы управления webview, используемые надстройками Office.

Затем Visual Studio выполняет следующее:

  1. Изменяет элемент SourceLocation XML-файла манифеста (скопированного в _ProjectName_\bin\Debug\OfficeAppManifests каталог), заменяя ~remoteAppUrl маркер полным адресом начальной страницы (например, https://localhost:44302/Home.html).

  2. Запускает проект веб-приложения в IIS Express.

  3. Проверяет манифест.

    Важно!

    XSD-файлы манифеста Office, устанавливаемые Visual Studio, устарели. Если возникают ошибки проверки манифеста, первым шагом по устранению неполадок должно быть замена одного или нескольких из этих файлов последними версиями. Подробные инструкции см. в статье Ошибки проверки схемы манифеста в проектах Visual Studio.

  4. Открывает страницу Outlook клиента Microsoft 365 в Microsoft Edge.

Отладка надстройки Outlook

Лучший способ отладки надстройки в Visual Studio 2022 зависит от того, выполняется ли надстройка в WebView2, который является элементом управления webview, связанным с Microsoft Edge (Chromium), или старым элементом управления webview. Чтобы определить, какой элемент управления webview используется, см. статью Браузеры и элементы управления webview, используемые надстройками Office. Если компьютер использует WebView2, см . статью Использование встроенного отладчика Visual Studio. Сведения о любом другом элементе управления webview см. в разделе Использование средств разработчика браузера.

Использование встроенного отладчика Visual Studio

  1. При необходимости устанавливайте точки останова в исходных файлах JavaScript или TypeScript. Это можно сделать до или после запуска надстройки, как описано в предыдущем разделе Запуск проекта надстройки Outlook.

  2. Когда надстройка запущена, используйте пользовательский интерфейс надстройки для выполнения кода, содержащего точки останова.

Совет

  • Иногда в Outlook в Интернете отладчик Visual Studio не подключается. Если в точках останова возникают ошибки, указывающие на то, что они не будут сбиты, используйте средства разработчика браузера, чтобы присоединиться к отладчику Visual Studio. После нажатия клавиши F5 для запуска отладки и открытия Outlook в Интернете выполните первые четыре действия, описанные в разделе Использование средств разработчика браузера в Outlook в Интернете. (Используйте инструкции для Microsoft Edge (на основе Chromium).) После установки точки останова в средствах браузера и ее нажатия выполнение приостанавливается в точке останова как в средствах браузера, таки в Visual Studio. Это означает, что отладчик Visual Studio подключен. На этом этапе вы можете закрыть средства браузера и добавить точки останова в Visual Studio, как обычно.
  • Если у вас возникли проблемы, дополнительные сведения см . в статье Отладка приложения JavaScript или TypeScript в Visual Studio.

Использование средств разработчика браузера в Outlook в Интернете

  1. На странице Outlook выберите сообщение электронной почты или элемент встречи, чтобы открыть его в собственном окне.

  2. Нажмите клавишу F12, чтобы открыть средство отладки Edge.

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

    Кнопка

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

    Совет

    Чтобы отладить код, который выполняется в Office.initialize функции или Office.onReady функции, которая запускается при открытии надстройки, задайте точки останова, а затем закройте и снова откройте надстройку. Дополнительные сведения об этих функциях см. в статье Инициализация надстройки Office.

  5. Чтобы внести изменения в код, сначала остановите сеанс отладки в Visual Studio и закройте страницы Outlook. Внесите изменения и запустите новый сеанс отладки.

Использование существующего документа для отладки надстройки

Если у вас есть документ, содержащий тестовые данные, которые вы хотите использовать при отладке надстройки Excel, PowerPoint или Word, Visual Studio можно настроить на открытия документа при запуске проекта. Чтобы указать существующий документ для использования при отладке надстройки, выполните указанные ниже действия.

  1. В Обозревателе решений выберите проект надстройки (не проект веб-приложения).

  2. В строке меню выберите Проект>добавить существующий элемент.

  3. В диалоговом окне Добавление существующего элемента найдите и выберите документ, который вы хотите добавить.

  4. Нажмите кнопку Добавить, чтобы добавить документ в проект.

  5. В Обозревателе решений выберите проект надстройки (не проект веб-приложения).

  6. В панели меню выберите Вид>Окно свойств.

  7. В окнеСвойства выберите список Стартовый документ, а затем выберите документ, который вы добавили в проект. Проект теперь настроен на запуск надстройки в данном документе.

Дальнейшие действия

Если надстройка работает корректно, см. статью Развертывание и публикация вашей надстройки Office, чтобы ознакомиться со способами распространения вашей надстройки среди пользователей.