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

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

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

Обзор

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

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

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

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

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

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

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

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

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

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

Вы можете развернуть все пакеты среды выполнения Windows App SDK, запустив установщик. Установщик доступен по адресу Downloads для 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 и завершить работу всех запущенных в настоящее время процессов Windows App SDK с помощью параметра --force. Эта функция представлена в версии 1.1.

WindowsAppRuntimeInstall.exe --force

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

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

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

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

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

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

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

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

пример установщика Explore Installer

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

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

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

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

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

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

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

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

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

Пример, демонстрирующий установку пакетов MSIX, см. в разделе install.cpp в коде установщика Windows App SDK.

Чтобы проверить, установлен ли Windows App SDK уже (и если да, какая версия), можно проверить наличие определенных семейств пакетов, вызвав 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 имя packagefamilyname отличается, и более одного (различных) 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, необходима дополнительная логика.

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

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

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

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

Использование среды выполнения Windows App SDK

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

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

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

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

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

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

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

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

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

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

Архитектура развертывания Windows App SDK

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-03-10