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

Статья
06/24/2024

Примечание.

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

Если приложение не установлено с помощью MSIX (т. е. упаковано с внешним расположением или распаковкой), необходимо инициализировать пакет SDK для приложений Windows для использования, прежде чем вызывать функции пакета SDK для приложений Windows, такие как WinUI 3, жизненный цикл приложений, MRT Core и DWriteCore. Приложение должно инициализировать среду выполнения пакета SDK для приложений Windows, прежде чем использовать любую другую функцию пакета SDK для приложений Windows.

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

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

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

За кулисами и отказ от автоматической инициализации модуля

Код, созданный указанным выше свойством WindowsPackageType , использует инициализаторы модулей для вызова API начального загрузчика. Загрузчик выполняет тяжелый подъем, чтобы найти пакет SDK для приложений Windows и включить текущий процесс его использования. Созданный код обрабатывает инициализацию и завершение работы. Поведение инициализации можно управлять следующими свойствами проекта:

<WindowsAppSDKBootstrapAutoInitializeOptions_Default>true</WindowsAppSDKBootstrapAutoInitializeOptions_Default>
- Используйте параметры по умолчанию.
<WindowsAppSDKBootstrapAutoInitializeOptions_None>true</WindowsAppSDKBootstrapAutoInitializeOptions_None>
- Не используйте параметры.
<WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>
- Вызов debugBreak() при возникновении ошибки.
<WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>
- Вызов DebugBreak(), если ошибка возникает только в том случае, если отладчик подключен к процессу.
<WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>
- Выполните сбой при возникновении ошибки.
<WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>
- Предложите пользователю получить среду выполнения пакета SDK для приложений Windows, если не удается найти соответствующий.
<WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
- При вызове в процессе с удостоверением пакета (в противном случае происходит сбой и возвращается ошибка).

Если вы хотите, чтобы приложение было явным контролем, вы можете напрямую вызвать API boostrapper в начале запуска приложения. В этом случае в файле проекта не требуется WindowsPackageType .

Примечание.

Помимо автоматической инициализации и API загрузчика пакет SDK для приложений Windows также предоставляет реализацию API динамической зависимости. Этот API позволяет распаковывать приложениям зависимость от любого пакета платформы (а не только пакета SDK для приложений Для Windows), и он используется внутренне API загрузчика. Дополнительные сведения об API динамической зависимости см. в разделе "Использование API динамической зависимости", чтобы ссылаться на пакеты MSIX во время выполнения.

Отказ от автоматической инициализации модуля (или в)

Свойство <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> проекта отключает автоматическую инициализацию модуля, описанную выше (API начальной загрузки не вызывается). Это позволяет приложению взять на себя ответственность и напрямую вызвать API начального загрузчика.

Начиная с версии 1.2 пакета SDK для приложений Windows (из стабильного канала), автоматическая инициализация модуля применяется только к проектам, которые создают исполняемый файл (то есть свойство проекта OutputType имеет значение Exe или WinExe). Это позволяет предотвратить добавление автоматических инициализаторов в библиотеки классов DLL и других не исполняемых файлов по умолчанию. Если вам нужен автоматический инициализатор в неисполняемом файле (например, тестовая библиотека DLL, загруженная исполняемым файлом узла, который не инициализирует загрузочный загрузчик), можно явно включить автоинициализатор в проекте.<WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize>

Использование API начального загрузчика

Внимание

Функция MddBootstrapInitialize2 , указанная ниже, доступна начиная с версии 1.1.

API начальной загрузки состоит из трех функций C/C++, объявленных в файле заголовка mddbootstrap.h в пакете SDK для приложений Windows: MddBootstrapInitialize, MddBootstrapInitialize2 и MddBootstrapShutdown. Эти функции предоставляются библиотекой загрузчика в пакете SDK для приложений Windows. Эта библиотека представляет собой небольшую библиотеку DLL, которую необходимо распространить вместе с приложением; он не является частью самого пакета платформы.

MddBootstrapInitialize2

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

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

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

MddBootstrapShutdown

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

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

Оболочка .NET для API начальной загрузки

Хотя вы можете вызвать API начальной загрузки C/C++ непосредственно из приложений .NET, которые требуют использования вызова платформы для вызова функций. В пакетах SDK для приложений Windows 1.0 и более поздних выпусков в сборке Microsoft.WindowsAppRuntime.Bootstrap.Net.dll доступна оболочка .NET для API загрузчика. Эта сборка предоставляет более простой и более естественный API для разработчиков .NET для доступа к функциям загрузчика. Класс Bootstrap предоставляет статические функции Initialize, TryInitialize и Shutdown, которые упаковывают вызовы mddBootstrapInitialize и MddBootstrapShutdown для большинства распространенных сценариев. Пример, демонстрирующий использование оболочки .NET для API начальной загрузки, см. в инструкциях по C# в руководстве. Использование API загрузчика в приложении, упакованном с внешним расположением или распаковкой, использующим пакет SDK для приложений Windows.

Дополнительные сведения о оболочке .NET для API загрузчика см. в следующих ресурсах:

API-интерфейсы C# начальной загрузки.
Раздел 6.1.4 спецификации динамических зависимостей.
Bootstrap.cs. Реализация открытый код оболочки .NET для API начального загрузчика.

Оболочка C++ для API начальной загрузки

Оболочка C++ для API загрузчика доступна начиная с пакета SDK для приложений Windows 1.1.

См . API начальной загрузки C++.

Объявление совместимости ОС в манифесте приложения

Чтобы объявить совместимость операционной системы (ОС) и избежать поведения Windows App SDK по умолчанию для Windows 8 (и потенциальных сбоев), можно включить параллельный манифест приложения с пакетом с внешним расположением или распаковкой приложения. См. раздел Манифесты приложений (это файл, который объявляет такие вещи, как поддержка DPI, и внедряется в .exe приложения во время сборки). Это может быть проблема, если вы добавляете поддержку пакета SDK для приложений Windows в существующее приложение, а не создаете новый с помощью шаблона проекта Visual Studio.

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

Замените атрибут Id элемента maxversiontested номером версии Windows, предназначенным для вас (должен быть 10.0.17763.0 или более поздней версии). Обратите внимание, что установка более высокого значения означает, что старые версии Windows не будут работать должным образом, так как каждый выпуск Windows знает только о версиях перед ним. Поэтому, если вы хотите, чтобы приложение выполнялось в Windows 10 версии 1809 (10.0; Сборка 17763), то следует оставить значение 10.0.17763.0 как есть, или добавить несколько элементов maxversiontested для различных значений, поддерживаемых приложением.

<?xml version="1.0" encoding="UTF-8"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
    <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
        <application>
            <!-- Windows 10, version 1809 (10.0; Build 17763) -->
            <maxversiontested Id="10.0.17763.0"/>
            <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}" />
        </application>
    </compatibility>
</assembly>

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