Поделиться через

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

  • Статья

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

Примечание.

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

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

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

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

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

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

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

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

Свойство Описание
Действие при запуске Определяет режим отладки для вашей надстройки. Если требуется выполнить отладку в Microsoft 365 в Windows, это значение должно быть установлено как Классический клиент Office . Для отладки в Microsoft 365 в Интернете необходимо установить microsoft Edge.
Начальный документ
(только для надстроек 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. Это свойство можно оставить пустым.
Файл проекта Задает имя файла, в котором указаны сборка, конфигурация и другие сведения о проекте.
Папка проекта Указывает расположение файла проекта.
Конфигурация активного развертывания
(присутствует только при отладке Excel,
PowerPoint или Word в Интернете)		 Указывает конфигурацию развертывания. Для параметра должно быть задано значение По умолчанию.
Подключение к серверу
(присутствует только при отладке Excel,
PowerPoint или Word в Интернете)		 Указывает, подключается ли проект к службе SharePoint, указанной в свойстве URL-адрес сайта . Для параметра должно быть задано значение В сети.
URL-адрес сайта;
(присутствует только при отладке Excel,
PowerPoint или Word в Интернете)		 Указывает полный абсолютный URL-адрес клиента SharePoint, в котором вы хотите разместить страницы надстройки при отладке. Например https://mysite.sharepoint.com/

Примечание.

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

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

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

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

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

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

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

Отладка проекта надстройки на рабочем столе Windows

В этом разделе описано, как запустить и отладить надстройку в классическом office в Windows. то есть, если для свойства Start Action проекта надстройки задано значение Office Desktop Client.

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

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

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

  1. Создает копию файла манифеста только надстройки и добавляет ее в _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 только файла манифеста надстройки (который был скопирован _ProjectName_\bin\Debug\OfficeAppManifests в каталог), заменив ~remoteAppUrl маркер полным адресом начальной страницы (например, https://localhost:44302/Home.html).

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

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

    Важно!

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

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

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

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

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

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

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

Важно!

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

Совет

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

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

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

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

    Примечание.

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

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

    Совет

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

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

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

Отладка проекта надстройки в Microsoft 365 в Интернете

В этом разделе описано, как запустить и отладить надстройку в классическом Office в Интернете. то есть, когда свойству Start Action проекта надстройки присвоено значение Microsoft Edge.

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

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

Примечание.

При отладке надстройки в Интернете может появиться сообщение об ошибке AADSTS50011 следующего вида:

"URI {Full absolute URL to add-in home page} перенаправления, указанный в запросе, не соответствует URI перенаправления, настроенным для приложения ... "

Это происходит из-за того, что новые веб-приложения, развернутые в SharePoint, могут быть доступны до 24 часов. Чтобы сразу сделать надстройку отлаживаемой, сделайте следующее:

  1. Остановите отладку в Visual Studio.

  2. Создайте скрипт PowerShell со следующими строками. Замените заполнитель {Full absolute URL to add-in home page} URL-адресом перенаправления в сообщении об ошибке, например "https://contoso-79d42f062409ae.sharepoint.com/_forms/default.aspx".

    Connect-MgGraph -Scopes Application.ReadWrite.All
$sharepointPrincipal = Get-MgServiceprincipal -Filter "AppId eq '00000003-0000-0ff1-ce00-000000000000'"
$sharepointPrincipal | fl
$replyUrls = $sharepointPrincipal.ReplyUrls
$replyUrls += "{Full absolute URL to add-in home page}"
Update-MgServiceprincipal -ServicePrincipalId $sharepointPrincipal.Id -ReplyUrls $replyUrls

  3. Запустите скрипт в PowerShell.

  4. Перезапустите проект, выбрав Отладка>Начать отладку в строке меню или нажав кнопку F5.

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

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

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

  3. Создает проект веб-приложения, а затем развертывает его в клиенте Microsoft 365.

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

  1. Изменяет элемент SourceLocation только файла манифеста надстройки (который был скопирован _ProjectName_\bin\Debug\OfficeAppManifests в каталог), заменив ~remoteAppUrl маркер полным адресом начальной страницы (например, https://contoso-79d42f062409ae.sharepoint.com/_forms/default.aspx).

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

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

    Важно!

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

  4. Открывает страницу узла приложения Office клиента Microsoft 365 в Microsoft Edge.

Отладка надстройки в Интернете

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

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

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

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

Совет

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

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

  1. Для надстройки на любом узле, кроме Outlook, на странице ведущего приложения Office нажмите клавишу F12, чтобы открыть средство отладки.

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

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

    Кнопка

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

    Совет

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

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

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

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

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

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

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

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

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

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

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

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

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