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

  • Статья

Примечание

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

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

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

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

Общие сведения о динамических зависимостях см. в разделе Пакеты платформы MSIX и динамические зависимости.

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

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

  • <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>
    • Предложите пользователю приобрести среду выполнения Windows App SDK, если не удается найти соответствующую среду выполнения.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
    • Успешно выполняется при вызове в процессе с удостоверением пакета (в противном случае произойдет сбой и возвращается ошибка).

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

Примечание

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

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

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

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

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

Важно!

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

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

MddBootstrapInitialize2

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

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

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

MddBootstrapShutdown

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

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

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

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

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

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

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

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

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

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