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

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

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

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

В фоновом режиме и отказ от использования автоинициализаторов

Код, созданный свойством WindowsPackageType, упомянутым выше, использует auto-initializers для вызова 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 bootstrapper на ранних этапах запуска вашего приложения. В этом случае в файле project не требуется WindowsPackageType.

Примечание.

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

Отказ от использования (или подключение) автоинициализаторов

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

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

Использование API Bootstrapper

Внимание

Функция 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 Dynamic Dependencies для добавления пакета платформы среды выполнения 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 и более поздних версий в сборке Microsoft.WindowsAppRuntime.Bootstrap.Net.dll доступна оболочка .NET API начального загрузчика. Эта сборка предоставляет более простой и более естественный API для разработчиков .NET, чтобы получить доступ к функциональности загрузчика. Класс Bootstrap предоставляет статические функции Initialize, TryInitialize и Shutdown, которые упаковывают вызовы mddBootstrapInitialize и MddBootstrapShutdown для большинства распространенных сценариев. Для примера, демонстрирующего использование оболочки .NET для API начального загрузчика, см. инструкции по C# в Учебник: используйте API начального загрузчика в приложении, упакованного с внешним расположением или не упакованного с помощью Windows App SDK.

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

Обертка C++ для API загрузчика

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

Смотрите Bootstrapper C++ API.

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

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

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

Замените атрибут 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>

См. также

  • Last updated on