руководство по развертыванию Windows App SDK для упакованных приложений, зависящих от платформы

В этой статье приводятся рекомендации по развертыванию упакованных приложений, зависящих от фреймворка (см. Что такое MSIX?), которые используют Windows App SDK. Эквивалентный раздел для других параметров упаковки, зависящих от платформы, — это руководство по развертыванию Windows App SDK для приложений, зависящих от платформы, упакованных с внешним расположением или неупакованных.

Overview

По умолчанию, когда вы создаёте проект с помощью одного из шаблонов WinUI 3 в Visual Studio, ваш проект настраивается на сборку приложения в пакет MSIX с использованием либо MSIX одного проекта (см. Упаковка приложения с помощью MSIX одного проекта), либо проекта упаковки приложений Windows (см. Настройка классического приложения для упаковки MSIX в Visual Studio). Затем можно создать пакет MSIX для приложения, следуя инструкциям в Упаковка классического приложения или приложения UWP в Visual Studio. После сборки пакета MSIX для приложения вы можете управление развертыванием MSIX.

Дополнительные сведения о пакетах, которые могут потребоваться упакованному приложению при использовании Windows App SDK, см. в статье Архитектура развертывания Windows App SDK. К ним относятся пакеты Framework, Main и Singleton ; которые подписаны и опубликованы корпорацией Майкрософт. Существует два основных требования к развертыванию упаковаемого приложения:

  1. Разверните пакет платформы Windows App SDK.
  2. Вызовите API развертывания.

Prerequisites

Развертывание пакета платформы Windows App SDK

Пакет платформы Windows App SDK содержит двоичные файлы Windows App SDK, используемые во время выполнения, и устанавливается с приложением. Платформа имеет разные требования к развертыванию для различных каналов Windows App SDK.

Стабильная версия

При установке стабильной версии пакета NuGet Windows App SDK на компьютере разработки и создании проекта с помощью одного из предоставленных шаблонов проектов WinUI созданный манифест пакета содержит PackageDependency элемент, указывающий зависимость от пакета платформы.

Однако при создании пакета приложения вручную с помощью отдельного проекта упаковки приложений Windows необходимо объявить PackageReference в файле Application (package).wapproj, как показано ниже:

<ItemGroup>
   <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.8.260209005">
       <IncludeAssets>build</IncludeAssets>
   </PackageReference>
</ItemGroup>

Эта зависимость пакета гарантирует, что пакет Framework устанавливается при развертывании приложения на другом компьютере.

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

При установке предварительной версии пакета NuGet Windows App SDK на компьютере разработки предварительная версия пакета платформы Windows App SDK развертывается во время сборки в качестве зависимости пакета NuGet.

Вызов API развертывания

См. также Initialize Windows App SDK.

API развертывания предоставляется пакетом платформы Windows App SDK и доступен в пространстве имен Microsoft.Windows.ApplicationModel.WindowsAppRuntime. Модель приложения Windows не поддерживает объявление зависимости от пакетов Main и Singleton. Поэтому API развертывания требуется по следующим причинам:

  1. Развертывание пакета Singleton для функций, не входящих в пакет Framework (например, push-уведомлений).
  2. Для развертывания основного пакета, который необходимо установить для автоматического обновления пакета Framework из магазина Microsoft.

Для упакованных приложений, которые не распространяются через Магазин, вы, как разработчик, отвечаете за распространение пакета Framework. Рекомендуется вызвать API развертывания, чтобы все критически важные обновления обслуживания были доставлены. Обратите внимание, что для использования функций за пределами пакета Платформы (например, push-уведомлений) необходимо развернуть пакет Singleton (это можно сделать с помощью API развертывания или путем распространения пакетов MSIX с помощью собственного метода установки).

Important

Только упакованные приложения с полным доверием или с ограниченной возможностью packageManagement имеют разрешение использовать API развертывания для установки зависимостей основных и Singleton пакетов.

После инициализации процесса приложения необходимо вызвать API развертывания, но прежде чем приложение использует функции среды выполнения Windows App SDK, использующие пакет Singleton (например, push-уведомления). Основными методами API развертывания являются статические методы GetStatus и инициализация класса DeploymentManager .

  • Метод GetStatus возвращает текущее состояние развертывания среды выполнения Windows App SDK, загруженной в данный момент. Используйте этот метод, чтобы определить, требуется ли установка пакетов среды выполнения Windows App SDK, прежде чем текущее приложение сможет использовать функции Windows App SDK.
  • Метод Initialize проверяет, присутствуют ли все необходимые пакеты в минимальной версии, необходимой для загруженной среды выполнения Windows App SDK. Если отсутствуют зависимости пакетов, метод пытается зарегистрировать эти отсутствующие пакеты. Начиная с Windows App SDK 1.1 метод Initialize также поддерживает возможность принудительного развертывания пакетов среды выполнения Windows App SDK. Это завершает все процессы для пакетов среды выполнения Main и Singleton , поэтому прерывает их службы (например, push-уведомления не будут доставлять уведомления в течение этого времени). Вы должны вызывать инициализацию только один раз. Вам не нужно вызывать Initialize для приложений, развернутых с помощью команд Start без отладки и Start Debugging в Visual Studio.

Important

Значение свойства Visual Studio по умолчанию <WindowsAppSdkDeploymentManagerInitialize> равно true. Поэтому, если вы хотите вызвать DeploymentManager.Initialize явно, задайте <WindowsAppSdkDeploymentManagerInitialize>false</WindowsAppSdkDeploymentManagerInitialize> в файле проекта Visual Studio.

Образец приложения API для развертывания

Дополнительные инструкции по использованию методов GetStatus и Initialize класса DeploymentManager см. в доступном примере приложения.

ознакомьтесь с примерным приложением API развертывания

Устранение ошибок установки

Если API развертывания обнаруживает ошибку во время установки пакетов среды выполнения Windows App SDK, он возвращает код ошибки, описывающий проблему.

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

Код ошибки Name Распространенная причина
0x80070005 ACCESS_DENIED Приложение не является доверенным или не имеет ограниченной возможности packageManagement. Запустите с повышенными привилегиями или добавьте необходимое разрешение.
0x80073CF0 ERROR_INSTALL_OPEN_PACKAGE_FAILED Пакет MSIX поврежден или недоступен. Убедитесь, что файл пакета нетронут и путь правильный.
0x80073CF3 ERROR_INSTALL_PREREQUISITE_FAILED Необходимый пакет зависимостей отсутствует или несовместим. Убедитесь, что установлен пакет платформы VCLibs и все другие предварительные требования.
0x80073D06 ERROR_PACKAGES_IN_USE Один или несколько пакетов используются и не могут быть обновлены. Закройте все приложения с помощью среды выполнения Windows App SDK, а затем повторите попытку.
0x80073CFB ERROR_PACKAGE_ALREADY_EXISTS Версия пакета уже зарегистрирована. Это информационное сообщение — ваше приложение может продолжить работу.
0x80073CF9 ОШИБКА_УСТАНОВКИ_НЕУДАЛАСЬ Общий сбой установки. Дополнительные сведения см. в журналах событий (см. ниже).

Подсказка

Полный список кодов ошибок установки пакета MSIX см. в разделе "Устранение неполадок в упаковке, развертывании и запросе приложений Windows".

Если код ошибки не предоставляет достаточно сведений, дополнительные диагностические сведения можно найти в подробных журналах событий (см. получение диагностических сведений). Журналы событий находятся в Просмотр событий в разделе "Журналы> приложений и служб Microsoft>Windows>AppxDeployment-Server.

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

  • Last updated on