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

  • Статья

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

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

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

Примечание.

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

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

Примечание.

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

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

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

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

После добавления файлов в проект добавьте <IconUrl> и <HighResolutionIconUrl> (в этом порядке) в XML-манифест сразу под элементом <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. Если вы измените его в манифесте, обязательно измените его и в файле кода.

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

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

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

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

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

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

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

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

  2. Выберите Create новое приложение.

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

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

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

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

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

  6. В раскрывающемся списке Выбор файла манифеста проекта импорта перейдите к 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. Теперь вы можете работать с надстройкой.

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

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

  1. В корневой части проекта откройте командную строку или оболочку bash и выполните следующую команду. Это преобразует манифест и обновляет package.json для указания текущих пакетов инструментов. Новый унифицированный манифест находится в корне проекта, а старый XML-манифест — в 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.

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

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

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

npx office-addin-manifest-converter convert -m <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>