有关依赖框架的未打包应用的Windows 应用 SDK部署指南

本主题介绍如何部署Windows 应用 SDK运行时,以及如何为依赖框架的未打包桌面应用初始化其框架依赖项。

  • 此类应用是桌面应用(而不是 UWP 应用)。
  • 可以使用 .NET 语言(如 C#)或 C++ 编写它们。
  • 对于用户界面,他们可以使用 WinUI 3、WPF、WinForms 或其他 UI 框架。

有关打包的应用(包括采用外部位置打包的应用(稀疏包)),请参阅适用于依赖框架的打包应用的 Windows 应用 SDK 部署指南。 有关在本地携带框架二进制文件的应用,而不是依赖于框架 MSIX 包的应用,请参阅Windows 应用 SDK自包含应用的部署指南。

概述

你负责为未打包的应用部署所需的 Windows 应用 SDK 运行时包,可通过运行运行时安装程序或直接安装 MSIX 包来进行。 这些选项在Deploy Windows 应用 SDK runtime中有介绍。

应用还必须使用 Bootstrapper API(自动或显式)将框架包添加到其进程包图,然后再使用 Windows 应用 SDK API。 如果应用使用其他 MSIX 框架包,则它可以通过动态依赖项 API 引用它们。 请参阅Windows 应用 SDK运行时依赖项和初始化。

先决条件

其他先决条件

  • Windows 应用 SDK 的实验版和预览版需要启用旁加载才能安装运行时。
    • Windows 10 版本 2004 及更高版本上会自动启用旁加载。

    • 如果开发计算机或部署计算机正在运行 Windows 11,请确认是否启用了旁加载:

      • 设置>隐私和安全>面向开发人员。 确保开发人员模式设置已打开。
    • 如果开发计算机或部署计算机正在运行 Windows 10 版本 1909 或更低版本,请确认是否启用了旁加载:

      • 设置>更新和安全性>面向开发人员>使用开发人员功能。 确认已选择旁加载应用 或 开发人员模式。
    • 开发人员模式设置包括侧载和其他功能。

      注意

      如果计算机在企业环境中管理,则可能存在阻止这些设置更改的策略。 在这种情况下,如果你或应用尝试安装Windows 应用 SDK运行时时遇到错误,请联系 IT 专业人员以启用旁加载或开发模式。

部署 Windows 应用 SDK 运行时

你有两个选项可为未打包的应用部署 Windows 应用 SDK 运行时:

  • 选项 1:使用安装程序:无提示安装程序分发所有Windows 应用 SDK MSIX 包。 每个 X64、X86 和 Arm64 体系结构都有单独的安装程序。
  • 选项 2:直接安装包:可以让现有安装程序或 MSI 工具捆绑并安装适用于 Windows 应用 SDK 的 MSIX 包。

选项 1:使用安装程序

可以通过运行安装程序来部署所有Windows 应用 SDK运行时包。 Windows 应用 SDK 的下载中提供了安装程序。 运行 installer (.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 包,并使用 --force 选项关闭当前正在运行的任何Windows 应用 SDK进程。 1.1 中引入了此功能。

WindowsAppRuntimeInstall.exe --force

要查看所有安装程序命令行选项,运行 WindowsAppRuntimeInstall --h。

安装后,应用必须通过 Bootstrapper 初始化将框架依赖项添加到其进程包图。 有关使用显式调用的示例,请参阅 教程:在未打包的应用中使用引导程序 API。

将Windows 应用 SDK安装程序链接到应用的设置

如果你的应用有自定义安装程序,则可以在应用的设置过程中链接Windows 应用 SDK设置过程。 Windows 应用 SDK 安装程序当前不提供默认 UI,因此需要使用你的安装程序的自定义 UI 进行串联。

可以使用 ShellExecute 以无提示方式启动和跟踪 Windows 应用 SDK 的设置,并同时显示您自定义的设置进度视图。 Windows 应用 SDK安装程序以无提示方式解压缩Windows 应用 MSIX 捆绑包,并调用 PackageManager.AddPackageAsync 方法来完成安装。 这与你可能使用的其他运行时安装程序非常相似,例如 .NET、Visual C++ 或 DirectX。

有关演示如何通过安装程序运行 Windows 应用 SDK 安装程序的代码示例,请参阅 RunInstaller 函数中的 installer 功能性测试。

安装程序示例

请参阅以下示例,了解如何在安装过程中从 Win32 安装程序启动安装程序,而无需弹出控制台窗口:

故障排除

返回代码

下表列出了Windows 应用 SDK .exe安装程序最常见的返回代码。 所有版本的安装程序的返回代码都是相同的。

返回代码 说明
0x0 包安装或预配已成功完成。
0x80073d06 一个或多个包安装失败。
0x80070005 无法进行系统范围的安装或预配,因为应用没有以提升权限运行或执行安装的用户没有管理员权限。

安装错误

如果Windows 应用 SDK安装程序在安装过程中返回错误,它将返回描述问题的错误代码。

选项 2:直接部署Windows 应用 SDK运行时包

作为将 Windows 应用 SDK 安装程序用于部署到最终用户的替代方法,可以通过应用的程序或 MSI 手动部署 MSIX 包。 此选项最适合希望获得更多控制权的开发人员。

有关演示如何安装 MSIX 包的示例,请参阅Windows 应用 SDK安装程序代码中的 install.cpp。

若要检查是否已安装Windows 应用 SDK(如果是,则为哪个版本),可以通过调用 PackageManager.FindPackagesForUserWithPackageTypes 来检查特定包系列。

在 mediumIL(完全信任)未打包进程(请参阅应用程序元素)中,可以使用以下代码检查是否存在注册到当前用户的包:

using Windows.Management.Deployment;

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

        foreach (var p in new 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 参数设置为空字符串。

现在,一些信息可帮助你决定 如何在 上面的代码示例中调用函数。 正确安装的运行时由多个包组成,这些包依赖于系统的 CPU 体系结构:

  • 在 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 包,其体系结构应与系统的 CPU 体系结构匹配;例如,x64 系统上的 x64 包。 对于框架包,x64 系统可以同时运行 x64 和 x86 应用;同样,arm64 系统可以运行 arm64、x64 和 x86 应用。 DDLM 包检查类似于 Framework 检查,不同之处在于 PackageType=main,packagefamilyname 不同,并且由于 DDLM 的唯一命名方案,多个(不同的)packagefamilyname 可能适用。 有关详细信息,请参阅 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 ProcessorArchitecture DetectSystemArchitecture()
{
    // Implementation: call IsWow64Process2() as shown in IsPackageApplicable() in
    // [install.cpp](https://github.com/microsoft/WindowsAppSDK/blob/main/installer/dev/install.cpp)
    // lines 99-116. WARNING: Use IsWow64Process2 — other similar APIs give unreliable results.
    throw new NotImplementedException();
}

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 == ProcessorArchitecture.Arm64))
    {
        if (!IsPackageRegisteredForCurrentUser(
            global::Microsoft.WindowsAppSDK.Runtime.Packages.Framework.PackageFamilyName,
            minVersion, ProcessorArchitecture.X64,
            PackageTypes.Framework))
        {
            return false;
        }
    }

    // Check arm64 (if necessary).
    if (systemArchitecture == ProcessorArchitecture.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.
}

上面的信息和代码涵盖了当前用户的基本检测方案。 需要其他逻辑来检测是否为所有用户预配运行时。

部署方案

  • 在系统范围内安装 Windows 应用 SDK 运行时:系统范围的安装会更改该计算机,适用于所有用户,包括将来添加的新用户。 如果应用正在特权运行并且执行安装的用户具有管理员权限,则安装程序将通过调用 ProvisionPackageForAllUsersAsync 在系统范围内注册 MSIX 包。 如果系统范围的注册不成功,安装将仅为当前执行安装的用户进行。 在托管企业环境中,IT 管理员应该能够像往常一样为每个人进行预配。

  • 由 Windows 应用 SDK 安装程序重新分发的体系结构:Windows 应用 SDK 安装程序提供 Arm64、x86 和 x64 架构版本。 安装程序的每个版本都仅包含其命名的特定体系结构的 MSIX 包。 例如,如果在 x64 或 Arm64 设备上运行x86WindowsAppRuntimeInstall.exe,则该x86安装程序将仅部署到该设备的 x86 体系结构包。

  • 计算机上已安装所有Windows 应用 SDK MSIX 包:MSIX 包安装在系统范围内,磁盘上只有一个副本。 如果在计算机上已经安装了所有 MSIX 包依赖项的情况下,应用尝试安装 Windows 应用 SDK,则不会执行安装。

  • 计算机上未安装一个或多个Windows 应用 SDK MSIX 包:部署Windows 应用 SDK时,请始终尝试安装所有 MSIX 包(框架、主包、单一实例包、DDLM),以确保安装所有依赖项,并避免最终用户体验中断。

Windows 应用 SDK运行时依赖项和初始化

使用 Windows 应用 SDK API 之前,依赖于框架的未打包应用必须动态建立框架包依赖项。 安装运行时包本身不会将框架包添加到应用的进程包图。

使用 Windows 应用 SDK 运行时

Bootstrapper API 执行两项重要任务:

  • 查找已安装的 Windows 应用 SDK Framework 包,并将其添加到应用程序的进程包图中。
  • 初始化操作系统所需的动态依赖项生存期管理器(DDLM)。 DDLM 在应用程序使用时将动态引用的框架包保留在使用中;支持的 Windows 11 版本可以通过 OS 本机动态依赖项提供此生存期管理。

对于依赖于框架的可执行文件,默认情况下,项目文件(.csproj或.vcxproj)中的设置<WindowsPackageType>None</WindowsPackageType>会启用 Bootstrapper 自动初始值设定项。

当自动初始值设定项执行此操作时,不需要显式调用 Bootstrapper API。 如果需要更多控制(例如自定义错误处理或特定框架版本的选择),请禁用自动初始值设定项并直接调用 Bootstrapper API。

有关详细信息,请参阅动态初始化 Windows 应用 SDK Framework 包和教程:在未打包的应用中使用引导程序 API。

Windows 应用 SDK Framework 包的每个版本和体系结构都有一个 DDLM。 这意味着,在 x64 计算机上,可能同时存在 x64 和 x86 DDLM 版本,以支持这两种体系结构的应用程序。

注意

其他功能依赖项独立于框架依赖项。 推送通知可能需要 Singleton 包。 对于依赖于框架的未打包应用,即使框架初始化成功,使用 AppNotificationManager 进行应用通知注册也需要 Singleton。 独立应用中的应用通知不需要 Singleton,但特定于 API 的要求仍适用。 请参阅Windows 应用 SDK的部署体系结构。

使用动态依赖项 API 引用其他框架包

若要引用除 Windows 应用 SDK Framework 包以外的 MSIX 框架包,未打包的应用可以使用动态依赖项 API。 Windows 应用 SDK提供实现此 API 的 C/C++ 函数和 WinRT 类。

有关详细信息,请参阅 从桌面应用动态使用 MSIX 框架包和 动态依赖项示例。

将 .winmd 文件部署到目标计算机

除了应用,我们建议继续部署 Windows 元数据 (.winmd) 文件。 元数据可由运行时的各种 API 和行为使用,并且其缺失可能会限制或中断功能。 例如,元数据可用于跨单元边界封送对象;并且封送的需要可能是计算机性能的一种功能。 由于没有确定性的方式来了解是否需要元数据,因此除非非常关心大小,否则应该部署 .winmd。