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

Статья
08/07/2024

В этом разделе приводятся рекомендации по развертыванию приложений, упакованных с внешним расположением, или распаковки и использующих пакет SDK для приложений Windows.

Такие приложения являются классическими приложениями (а не приложениями UWP).
Они могут быть написаны на языке .NET, например C#, или в C++.
Для пользовательского интерфейса они могут использовать WinUI 3, WPF или WinForms или другую платформу пользовательского интерфейса.

Обзор

Разработчики упакованных с внешним расположением и распакованными приложениями отвечают за развертывание необходимых пакетов среды выполнения windows App SDK для конечных пользователей. Это можно сделать, запустив установщик или установив пакеты MSIX напрямую. Эти параметры подробно описаны в разделе "Развертывание среды выполнения пакета SDK для приложений Windows" ниже.

Упакованные с внешним расположением и распакованными приложениями также имеют дополнительные требования к среде выполнения. Необходимо инициализировать доступ к среде выполнения пакета SDK для приложений Windows с помощью API начальной загрузки. Кроме того, API динамических зависимостей можно использовать, если приложение использует другие пакеты платформы помимо пакета SDK для приложений Windows. Эти требования подробно описаны в требованиях среды выполнения для приложений, упакованных с внешним расположением или распакованным разделом ниже.

Необходимые компоненты

Скачайте последние пакеты установщика и MSIX.
Для приложений, которые упаковываются с внешним расположением или распаковываются, Распространяемый компонент Visual C++ является обязательным требованием. Дополнительные сведения см. в статье microsoft Распространяемый компонент Visual C++ последние поддерживаемые загрузки.
C#. Требуется .NET 6 или более поздней версии. Дополнительные сведения см. в разделе "Загрузки .NET".

Дополнительные требования

Экспериментальные и предварительные версии пакета SDK для приложений Windows требуют, чтобы загрузка неопубликованных данных была включена для установки среды выполнения.
- Загрузка неопубликованных данных автоматически включена в Windows 10 версии 2004 и более поздних версий.
- Если компьютер разработки или компьютер развертывания работает под управлением Windows 11, убедитесь, включена ли загрузка неопубликованных данных:
  - Параметры конфиденциальности и безопасности>для разработчиков.> Убедитесь, что включен параметр режима разработчика.
- Если компьютер разработки или компьютер развертывания работает под управлением Windows 10 версии 1909 или более ранней версии, убедитесь, включена ли загрузка неопубликованных данных:
  - Параметры обновления и безопасности>для разработчиков используют функции разработчика.>> Убедитесь, что выбран режим загрузки неопубликованных приложений или разработчиков.
- Параметр режима разработчика включает загрузку неопубликованных данных, а также другие функции.
  
  Примечание.
  
  Если компьютер управляется в корпоративной среде, может возникнуть политика, препятствующая изменению этих параметров. В этом случае при попытке установки среды выполнения пакета SDK для приложений Windows обратитесь к ИТ-специалисту, чтобы включить загрузку неопубликованных данных или режим разработчика.

Развертывание среды выполнения пакета SDK для приложений Windows

Упакованные с внешним расположением и распакованные приложения имеют два варианта для развертывания среды выполнения пакета SDK для приложений Windows:

Вариант 1. Использование установщика: автоматический установщик распространяет все пакеты MSIX пакета SDK для приложений Windows. Для каждой X64X86 архитектуры и Arm64 архитектуры доступен отдельный установщик.
Вариант 2. Установка пакетов напрямую. Вы можете использовать существующий инструмент установки или MSI, чтобы установить пакеты MSIX для пакета SDK для приложений Windows.

Вариант 1. Использование установщика

Вы можете развернуть все пакеты среды выполнения пакета SDK для приложений Windows, выполнив установщик. Установщик доступен на сайте downloads for the Windows App SDK. При запуске установщика (.exe), вы увидите выходные данные, аналогичные следующим:

Deploying package: Microsoft.WindowsAppRuntime.1.0_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0

Deploying package: Microsoft.WindowsAppRuntime.1.0_0.318.928.0_x86__8wekyb3d8bbwe
Package deployment result : 0x0

Deploying package: MicrosoftCorporationII.WindowsAppRuntime.Main.1.0_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WindowsAppRuntime.Singleton_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WinAppRuntime.DDLM.0.318.928.0-x6_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WinAppRuntime.DDLM.0.318.928.0-x8_0.318.928.0_x86__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

All install operations successful.

Установщик можно запустить без взаимодействия с пользователем и отключить все текстовые выходные данные с --quiet помощью параметра:

WindowsAppRuntimeInstall.exe --quiet

Вы также можете принудительно обновить пакеты MSIX и завершить работу всех текущих процессов пакета SDK для приложений Windows с помощью этого --force параметра. Эта функция представлена в версии 1.1.

WindowsAppRuntimeInstall.exe --force

Чтобы просмотреть все параметры командной строки установщика, выполните команду WindowsAppRuntimeInstall --h.

После завершения установки можно запустить пакет с внешним расположением или распаковкой приложения. Пример создания и запуска упаковаемого с внешним расположением или распаковки приложения, использующего пакет SDK для приложений Windows, см . в руководстве. Использование API загрузчика в приложении, упакованом с внешним расположением или распаковкой, использующим пакет SDK для приложений Windows.

Привязка установщика пакета SDK для приложений Windows к настройке приложения

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

Вы можете автоматически запускать и отслеживать настройку пакета SDK для приложений Windows, показывая собственное представление хода выполнения установки с помощью ShellExecute. Установщик пакета SDK для приложений Windows автоматически распаковывает пакет WINDOWS App MSIX и вызывает метод PackageManager.AddPackageAsync для завершения установки. Это очень похоже на другие установщики среды выполнения, которые вы могли использовать, например .NET, Visual C++или DirectX.

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

Пример установщика

См. пример ниже, чтобы узнать, как запустить установщик из программы установки Win32 без всплывающих окон консоли во время установки:

Изучение примера установщика

Устранение неполадок

Коды возврата

В следующей таблице перечислены наиболее распространенные коды возврата для установщика .exe пакета SDK для приложений Windows. Коды возврата одинаковы для всех версий установщика.

Код возврата	Description
0x0	Установка пакета или подготовка успешно завершена.
0x80073d06	Не удалось установить один или несколько пакетов.
0x80070005	Не удалось установить или подготовить систему, так как приложение не работает с повышенными привилегиями или пользователь, выполняющий установку, не имеет прав администратора.

Ошибки установки

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

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

Вариант 2. Развертывание пакетов среды выполнения пакета sdk для приложений Windows напрямую

В качестве альтернативы использованию установщика пакета SDK для приложений Windows для развертывания для конечных пользователей можно вручную развернуть пакеты MSIX с помощью программы или MSI приложения. Этот вариант лучше всего подходит для разработчиков, которые хотят больше контроля.

Пример, демонстрирующий, как программа установки может установить пакеты MSIX, см . install.cpp в коде установщика пакета SDK для Windows.

Чтобы проверить, установлен ли пакет SDK для приложений Windows (и если да, какая версия), можно проверить наличие определенных семейств пакетов, вызвав PackageManager.FindPackagesForUserWithPackageTypes.

Из разпакованного процесса среднего уровня ( полное доверие) (см . элемент Application) можно использовать следующий код, чтобы проверить наличие пакета, зарегистрированного для текущего пользователя:

using Windows.Management.Deployment;

public class WindowsAppSDKRuntime
{
    public static IsPackageRegisteredForCurrentUser(
        string packageFamilyName,
        PackageVersion minVersion,
        Windows.System.ProcessorArchitecture architecture,
        PackageTypes packageType)
    {
        ulong minPackageVersion = ToVersion(minVersion);

        foreach (var p : PackageManager.FindPackagesForUserWithPackageTypes(
            string.Empty, packageFamilyName, packageType)
        {
            // Is the package architecture compatible?
            if (p.Id.Architecture != architecture)
            {
                continue;
            }

            // Is the package version sufficient for our needs?
            ulong packageVersion = ToVersion(p.Id.Version);
            if (packageVersion < minPackageVersion)
            {
                continue;
            }

            // Success.
            return true;
        }

        // No qualifying package found.
        return false;
    }

    private static ulong ToVersion(PackageVersion packageVersion)
    {
        return ((ulong)packageVersion.Major << 48) |
               ((ulong)packageVersion.Minor << 32) |
               ((ulong)packageVersion.Build << 16) |
               ((ulong)packageVersion.Revision);
    }
}

Для приведенного выше сценария вызов FindPackagesForUserWithPackageTypes предпочтительнее вызывать FindPackagesForUser. Это связано с тем, что вы можете сузить поиск (в этом примере), просто платформу или основные пакеты. И это позволяет избежать сопоставления других типов пакетов (таких как ресурс, необязательный или пакет), которые не являются интересом для этого примера.

Чтобы использовать контекст текущего или вызывающего пользователя, задайте для параметра userSecurityId пустую строку.

А теперь некоторые сведения помогут вам решить , как вызвать функцию в приведенном выше примере кода. Правильно установленная среда выполнения состоит из нескольких пакетов, зависящих от архитектуры ЦП системы:

На компьютере x86: Fwk=[x86], Main=[x86], Singleton=[x86], DDLM=[x86].
На компьютере x64: Fwk=[x86, x64], Main=[x64], Singleton=[x64], DDLM=[x86, x64].
На компьютере arm64: Fwk=[x86, x64, arm64], Main=[arm64], Singleton=[arm64], DDLM=[x86, x64, arm64].

Для пакетов Main и Singleton их архитектура должна соответствовать архитектуре ЦП системы, например пакетам x64 в системе x64. Для пакета Framework система x64 может запускать приложения x64 и x86. Аналогично система arm64 может запускать приложения arm64, x64 и x86. Проверка пакета DDLM аналогична проверке платформы, за исключением того, что PackageType=mainи имя пакетаfamilyname отличается, а несколько (разных) packagefamilyname могут быть применимы из-за уникальной схемы именования DDLM. Дополнительные сведения см. в спецификации пакетов MSIX. Таким образом, проверки больше похожи на следующее:

public static bool IsRuntimeRegisteredForCurrentUser(PackageVersion minVersion)
{
    ProcessorArchitecture systemArchitecture = DetectSystemArchitecture();

    return IsFrameworkRegistered(systemArchitecture, minVersion) &&
           IsMainRegistered(systemArchitecture, minVersion) &&
           IsSingletonRegistered(systemArchitecture, minVersion) &&
           IsDDLMRegistered(systemArchitecture, minVersion);
}

private static ProcecssorArchitecture DetectSystemArchitecture()
{
    // ...see the call to IsWow64Process2(), and how the result is used...
    // ...as per `IsPackageApplicable()` in
    // [install.cpp](https://github.com/microsoft/WindowsAppSDK/blob/main/installer/dev/install.cpp)
    // line 99-116...
    // ...WARNING: Use IsWow64Process2 to detect the system architecture....
    // ...         Other similar APIs exist, but don't give reliably accurate results...
}

private static bool IsFrameworkRegistered(ProcessorArchitecture systemArchitecture,
    PackageVersion minVersion)
{
    // Check x86.
    if (!IsPackageRegisteredForCurrentUser(
        global::Microsoft.WindowsAppSDK.Runtime.Packages.Framework.PackageFamilyName,
        minVersion, ProcessorArchitecture.X86,
        PackageTypes.Framework))
    {
        return false;
    }

    // Check x64 (if necessary).
    if ((systemArchitecture == ProcessorArchitecture.X64) || 
        (systemArchitecture == ProcessorArchitcture.Arm64))
    {
        if (!IsPackageRegisteredForCurrentUser(
            global::Microsoft.WindowsAppSDK.Runtime.Packages.Framework.PackageFamilyName,
            minVersion, ProcessorArchitecture.X64,
            PackageTypes.Framework))
        {
            return false;
        }
    }

    // Check arm64 (if necessary).
    if (systemArchitecture == ProcessorArchitcture.Arm64)
    {
        if (!IsPackageRegisteredForCurrentUser(
            global::Microsoft.WindowsAppSDK.Runtime.Packages.Framework.PackageFamilyName,
            minVersion, ProcessorArchitecture.Arm64,
            PackageTypes.Framework))
        {
            return false;
        }
    }

    return true;
}

private static bool IsMainRegistered(ProcessorArchitecture systemArchitecture,
    PackageVersion minVersion)
{
    return IsPackageRegisteredForCurrentUser(
        global::Microsoft.WindowsAppSDK.Runtime.Packages.Main.PackageFamilyName,
        minVersion,
        systemArchitecture,
        PackageTypes.Main);
}

private static bool IsSingletonRegistered(ProcessorArchitecture systemArchitecture,
    PackageVersion minVersion)
{
    return IsPackageRegisteredForCurrentUser(
        global::Microsoft.WindowsAppSDK.Runtime.Packages.Singleton.PackageFamilyName,
        minVersion,
        systemArchitecture,
        PackageTypes.Main);
}

private static bool IsDDLMRegistered(ProcessorArchitecture systemArchitecture,
    PackageVersion minVersion)
{
    // ...similar to IsFrameworkRegistered, but the packageFamilyName is more complicated...
    // ...and no predefined constant is currently available...
    // ...for more details, see
    // https://github.com/microsoft/WindowsAppSDK/blob/main/specs/Deployment/MSIXPackages.md.
}

Приведенные выше сведения и код охватывают базовый сценарий обнаружения. Чтобы определить, подготовлена ли среда выполнения для всех пользователей или выполнить указанные выше действия из контейнера приложений, и (или) выполните это из упакованного mediumIL процесса, необходима дополнительная логика.

Сценарии развертывания

Установка системы среды выполнения пакета SDK для приложений Для Windows: установка системы изменяет компьютер для всех пользователей, включая новых пользователей, добавленных в будущем. Если приложение работает с повышенными привилегиями, и пользователь, выполняющий установку, имеет права администратора, установщик регистрирует пакеты MSIX на уровне системы, вызвав ProvisionPackageForAllUsersAsync. Если регистрация на уровне системы не выполнена, установка будет выполнена только для текущего пользователя, выполняющего установку. В управляемой корпоративной среде ИТ-администратор должен иметь возможность подготавливать всех пользователей как обычно.
Архитектуры, распространяемые установщиком пакета SDK для приложений Windows: установщик пакета SDK для приложений Windows доступен в x86x64и Arm64 архитектурах. Каждая версия установщика включает пакеты MSIX для конкретной архитектуры, для которых она называется. Например, если запустить x86 WindowsAppRuntimeInstall.exe устройство x64 или Arm64, x86 установщик будет развертываться на этом устройстве только для пакетов архитектуры x86.
Все пакеты MSIX пакета SDK для приложений Windows уже установлены на компьютере: пакеты MSIX устанавливаются в системное расположение только с одной копией на диске. Если приложение пытается установить пакет SDK для приложений Windows, когда все зависимости пакета MSIX уже установлены на компьютере, установка не выполняется.
На компьютере не устанавливается один или несколько пакетов MSIX пакета SDK для приложений Windows: при развертывании пакета SDK для приложений Windows всегда пытается установить все пакеты MSIX (платформа, основной, однотонный, DDLM), чтобы обеспечить установку всех зависимостей и не прерывать работу с конечным пользователем.

Требования к среде выполнения для приложений, упакованных с внешним расположением или распаковкой

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

Использование среды выполнения пакета SDK для приложений Windows

Упакованные с внешним расположением и распакованными приложениями должны вызывать API начальной загрузки для использования пакета SDK для приложений Windows во время выполнения. Это необходимо, прежде чем приложение сможет использовать такие функции пакета SDK для приложений Windows, как WinUI, жизненный цикл приложений, MRT Core и DWriteCore. Компонент начальной загрузки позволяет упаковывать внешние приложения и распаковывать приложения для выполнения следующих важных задач:

Найдите и загрузите пакет пакета SDK для приложений Для Windows в граф пакетов приложения.
Инициализировать диспетчер времени существования динамических зависимостей (DDLM) для пакета платформы sdk для приложений Windows. Цель DDLM заключается в том, чтобы предотвратить обслуживание пакета пакета sdk для приложений Для Windows во время его использования упакованным с внешним расположением или распакованным приложением.

Самый простой способ загрузить среду выполнения пакета SDK для приложений Windows для упаковки с внешним расположением и распаковкой приложений — задать <WindowsPackageType>None</WindowsPackageType> свойство в файле проекта (CSPROJ или .vcxproj). Вы также можете вызвать API начальной загрузки непосредственно в коде запуска приложения, чтобы получить больше контроля над инициализацией. Дополнительные сведения см. в разделе "Использование среды выполнения пакета SDK для приложений Windows", упакованных с внешним расположением или распаковкой и учебником. Используйте API загрузчика в приложении, упакованом с внешним расположением или распаковкой, использующим пакет SDK для приложений Windows.

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

Существует один DDLM для каждой версии и архитектуры пакета пакета sdk для приложений Windows. Это означает, что на x64 компьютере может быть как x86 версия DDLM, так и x64 для поддержки приложений обеих архитектур.

Справочник по другим пакетам платформы с помощью API динамических зависимостей

Если вы хотите использовать функции в других пакетах платформы за пределами пакета SDK для приложений Windows (например, DirectX), упакованные с внешним расположением и распакованными приложениями, могут вызывать API динамических зависимостей. Помимо компонента начальной загрузки пакет SDK для приложений Windows также предоставляет более широкий набор функций C/C++ и классов WinRT, реализующих API динамической зависимости. Этот API предназначен для динамической ссылки на любой пакет платформы во время выполнения.

Дополнительные сведения см. в статье Использование пакетов платформы MSIX динамически из классического приложения и примера динамических зависимостей

Развертывание winmd-файлов на целевом компьютере

Вместе с приложением рекомендуется идти вперед и развертывать файлы метаданных.winmd Windows. Метаданные могут использоваться различными API и поведением во время выполнения, а его отсутствие может ограничить или нарушить функциональные возможности. Например, метаданные можно использовать для маршалинга объектов через границы квартир; и необходимость маршалирования может быть функцией производительности компьютера. Так как не существует детерминированного способа узнать, нужны ли метаданные, следует развернуть .winmdего, если вы не очень обеспокоены размером.

Архитектура развертывания для пакета SDK для приложений Windows

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

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

Обзор

Необходимые компоненты

Дополнительные требования

Развертывание среды выполнения пакета SDK для приложений Windows

Вариант 1. Использование установщика

Привязка установщика пакета SDK для приложений Windows к настройке приложения

Пример установщика

Устранение неполадок

Вариант 2. Развертывание пакетов среды выполнения пакета sdk для приложений Windows напрямую

Сценарии развертывания

Требования к среде выполнения для приложений, упакованных с внешним расположением или распаковкой

Использование среды выполнения пакета SDK для приложений Windows

Справочник по другим пакетам платформы с помощью API динамических зависимостей

Развертывание winmd-файлов на целевом компьютере

Дополнительные ресурсы

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

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

Обзор

Необходимые компоненты

Дополнительные требования

Развертывание среды выполнения пакета SDK для приложений Windows

Вариант 1. Использование установщика

Привязка установщика пакета SDK для приложений Windows к настройке приложения

Пример установщика

Устранение неполадок

Вариант 2. Развертывание пакетов среды выполнения пакета sdk для приложений Windows напрямую

Сценарии развертывания

Требования к среде выполнения для приложений, упакованных с внешним расположением или распаковкой

Использование среды выполнения пакета SDK для приложений Windows

Справочник по другим пакетам платформы с помощью API динамических зависимостей

Развертывание winmd-файлов на целевом компьютере

См. также

Дополнительные ресурсы