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

Преобразование надстройки для использования унифицированного манифеста для Microsoft 365

  • Статья

Чтобы добавить возможности Teams в надстройку, которая использует только манифест надстройки, или только для подтверждения надстройки в будущем, необходимо преобразовать ее в единый манифест для Microsoft 365.

Существует три основные задачи преобразования проекта надстройки из манифеста только надстройки в унифицированный манифест.

  • Убедитесь, что надстройка готова к преобразованию.
  • Преобразуйте сам манифест надстройки в формате XML в формат JSON унифицированного манифеста.
  • Упакуйте новый манифест и файлы изображений двух значков в ZIP-файл для загрузки или развертывания.

Примечание.

Надстройки Office, использующие унифицированный манифест для Microsoft 365, поддерживаются непосредственно в Office в Интернете, в новом Outlook для Windows и в Office в Windows, подключенных к подписке Microsoft 365 версии 2304 (сборка 16320.00000) или более поздней версии.

Если пакет приложения, содержащий унифицированный манифест, развертывается в AppSource или центре Microsoft 365 Admin, то, если манифест имеет допустимое свойство alternateIcons, на основе унифицированного манифеста создается только манифест надстройки и сохраняется. Только этот манифест надстройки позволяет устанавливать надстройку на платформах, которые не поддерживают унифицированный манифест напрямую, включая Office для Mac, Office на мобильных устройствах, версии Office для Windows по подписке до 2304 (сборка 16320.00000) и бессрочные версии Office в Windows.

Примечание.

  • Надстройки, использующие унифицированный манифест, можно загрузить только в Office версии 2304 (сборка 16320.20000) или более поздней.
  • Проекты, созданные в Visual Studio, в отличие от Visual Studio Code, в настоящее время не могут быть преобразованы.
  • Если вы создали проект с помощью набора средств Teams или с параметром "унифицированный манифест" в генераторе Office Yeoman, он уже использует унифицированный манифест.

Убедитесь, что надстройка готова к преобразованию

В следующих разделах описаны условия, которые должны быть выполнены перед преобразованием манифеста.

Убедитесь, что у вас есть два файла образа.

После добавления файлов в проект добавьте <IconUrl> и <HighResolutionIconUrl> (в этом порядке) в манифест надстройки только под элементом <Description> . Ниже приведен пример.

<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MailApp">
  <Id>01234567-89ab-cdef-0123-4567-89abcdef0123</Id>
  <Version>1.0</Version>
  <ProviderName>Contoso</ProviderName>
  <DefaultLocale>en-us</DefaultLocale>
  <DisplayName DefaultValue="Great Add-in"/>
  <Description DefaultValue="A great add-in."/>
  <IconUrl DefaultValue="https://localhost:3000/assets/icon-64.png" />
  <HighResolutionIconUrl DefaultValue="https://localhost:300/assets/icon-128.png" />

  <!-- Other markup omitted -->

Убедитесь, что имена команд функции достаточно коротки.

Если манифест содержит какие-либо <элементы FunctionName> , убедитесь, что их значения содержат менее 65 символов. Значение этого элемента должно точно соответствовать имени функции в файле JavaScript или TypeScript. Если вы измените его в манифесте, обязательно измените его и в файле кода.

Убедитесь, что надстройка единого входа запрашивает разрешения.

Если ваша надстройка использует единый вход Майкрософт в потоке on-behalf-of (OBO), надстройка имеет <элемент Scopes> , указывающий разрешения Microsoft Graph или другие разрешения API, необходимые надстройке. При использовании унифицированного манифеста разрешения должны запрашиваться во время выполнения в коде. Обновите код по мере необходимости, чтобы запросить эти разрешения. Точный код зависит от используемой архитектуры и библиотек кода авторизации. Как правило, код запрашивает разрешения в функции, которая запрашивает маркер доступа.

Средства и параметры преобразования

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

Преобразование проекта с помощью набора средств Teams

Самый простой способ преобразования — использовать Набор средств Teams.

Предварительные условия

Импорт проекта надстройки в Набор средств Teams

  1. Откройте Visual Studio Code и щелкните значок Набора средств Teams на панели действий.

    Значок набора средств Teams.

  2. Выберите Создать приложение.

  3. В раскрывающемся списке Новый проект выберите Надстройка Outlook.

    Четыре параметра в раскрывающемся списке Новый проект. Четвертый вариант называется надстройкой Outlook.

  4. В раскрывающемся списке Функции приложения с помощью надстройки Outlook выберите Импорт существующей надстройки Outlook.

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

  5. В раскрывающемся списке Существующий проект надстройки перейдите к корневой папке проекта надстройки.

  6. В раскрывающемся списке Выбор файла манифеста проекта импорта перейдите к файлу манифеста только надстройки, который обычно называется manifest.xml.

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

  8. В диалоговом окне Имя приложения присвойте проекту имя (без пробелов). Teams Toolkit создает проект с исходными файлами и шаблонами. Затем откроется проект во втором окне Visual Studio Code. Закройте исходное окно Visual Studio Code.

Загрузка неопубликованного Visual Studio Code надстройки

Вы можете загрузить неопубликованную надстройку с помощью набора средств Teams или в командной строке, оболочке bash или терминале.

Загрузка неопубликованных приложений с помощью набора средств Teams
  1. Сначала убедитесь, что рабочий стол Outlook закрыт.
  2. В Visual Studio Code откройте набор средств Teams.
  3. В разделе УЧЕТНЫе записи убедитесь, что вы вошли в Microsoft 365.
  4. Выберите Просмотр | выполнить в Visual Studio Code. В раскрывающемся меню ЗАПУСК И ОТЛАДКА выберите параметр Outlook Desktop (Edge Chromium) и нажмите клавишу F5. Выполняется сборка проекта, и откроется окно Node dev-server. Этот процесс может занять несколько минут, после чего откроется рабочий стол Outlook.
  5. Теперь вы можете работать с надстройкой. Убедитесь, что вы работаете в папке "Входящие"удостоверения учетной записи Microsoft 365.
Загрузка неопубликованных приложений с помощью системного запроса, оболочки Bash или терминала
  1. Сначала убедитесь, что рабочий стол Outlook закрыт.
  2. Откройте системный запрос, оболочку bash или Visual Studio Code TERMINAL и перейдите к корню проекта.
  3. Выполните команду npm run start:desktop. Выполняется сборка проекта, и откроется окно Node dev-server. Этот процесс может занять несколько минут, после чего откроется рабочий стол Outlook.
  4. Теперь вы можете работать с надстройкой.
  5. Завершив работу с надстройкой, обязательно выполните команду npm run stop.

Проекты, созданные с помощью генератора Office Yeoman (он же Yo Office)

Если проект был создан с помощью генератора Office Yeoman и вы не хотите использовать набор средств Teams, преобразуйте его, выполнив следующие действия.

  1. В корневой части проекта откройте командную строку или оболочку bash и выполните следующую команду. Это преобразует манифест и обновляет package.json для указания текущих пакетов инструментов. Новый унифицированный манифест находится в корне проекта, а старый манифест только надстройки — в backup.zip файле. Дополнительные сведения об этой команде см. в разделе Office-Addin-Project.

    npx office-addin-project convert -m <relative-path-to-XML-manifest>

  2. Запустите npm install.

  3. Чтобы загрузить неопубликованную надстройку, выполните команду npm run start:desktop. Эта команда помещает унифицированный манифест и два файла изображений в ZIP-файл и загружает его в приложение Office. Он также запускает сервер в отдельном окне NodeJS для размещения файлов надстройки на localhost.

Когда вы будете готовы остановить сервер разработки и удалить надстройку, выполните команду npm run stop.

Проекты NodeJS и npm, созданные не с помощью генератора Yeoman

Если вы не хотите использовать набор средств Teams и ваш проект не был создан с помощью генератора Office Yeoman, используйте средство office-addin-manifest-converter.

В корневой части проекта откройте командную строку или оболочку bash и выполните следующую команду. Эта команда помещает унифицированный манифест во вложенную папку с тем же именем, что и ствол имени файла исходного манифеста надстройки. Например, если манифест называется MyManifest.xml, унифицированный манифест создается в .\MyManifest\MyManifest.json. Дополнительные сведения об этой команде см. в разделе Office-Addin-Manifest-Converter.

npx office-addin-manifest-converter convert <relative-path-to-XML-manifest>

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

Загрузка неопубликованных приложений с помощью средства Office-Addin-Debugging

  1. Чтобы загрузить неопубликованную надстройку, выполните следующую команду. Эта команда помещает унифицированный манифест и два файла изображений значков по умолчанию в ZIP-файл и загружает его в приложение Office. Он также запускает сервер в отдельном окне NodeJS для размещения файлов надстройки на localhost. Обратите внимание, что вы передаете путь к единому манифесту , созданному на предыдущем шаге. Дополнительные сведения об этой команде см. в разделе Office-Addin-Debugging.

    npx office-addin-debugging start <relative-path-to-unified-manifest> desktop

  2. При использовании office-addin-debugging для запуска надстройки всегда прерывайте сеанс с помощью следующей команды. Закрытие окна сервера не приводит к надежной остановке сервера, а закрытие приложения Office не приводит к отмене запроса надстройки Office.

    npx office-addin-debugging stop <relative-path-to-unified-manifest>

Загрузка неопубликованных приложений с помощью интерфейса командной строки набора средств Teams (интерфейс командной строки)

  1. Создайте ZIP-пакет вручную, выполнив следующие действия.

    1. Откройте унифицированный манифест и прокрутите страницу до свойства icons. Обратите внимание на относительный путь к двум файлам изображений.
    2. Используйте любую служебную программу ZIP, чтобы создать ZIP-файл, содержащий унифицированный манифест и два файла изображений. Файлы изображений должны иметь тот же относительный путь в ZIP-файле, что и в проекте. Например, если относительный путь — "assets/icon-64.png" и "assets/icon-128.png", необходимо включить папку assets с двумя файлами в ZIP-пакет.
    3. Если папка содержит другие файлы, например файлы изображений, используемые на ленте Office, удалите их из ZIP-пакета. В нем должны быть только два файла изображений, указанные в свойстве icons (в дополнение к манифесту в корневом каталоге ZIP-пакета).

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

    npm install -g @microsoft/teamsfx-cli

teamsfx m365 sideloading --file-path <relative-path-to-zip-file>