应用内购买和试用

注意

其他类型的加载项（例如带有包的耐用品加载项（也称为可下载内容或 DLC））仅适用于有限的开发人员，本文档不进行介绍。

本部分概述了 Windows.Services.Store 命名空间的重要任务和概念。 在 Visual Studio 中，此命名空间仅适用于面向 Windows 10 周年纪念版（10.0；内部版本 14393）或更高版本（对应于 Windows 10 版本 1607）的应用。 建议应用尽可能使用 Windows.Services.Store 命名空间而不是 Windows.ApplicationModel.Store 命名空间。 有关 Windows.ApplicationModel.Store 命名空间的信息，请参阅本文。

本部分内容

Windows.Services.Store 命名空间的主要入口点是 StoreContext 类。 此类提供的方法可用于获取当前应用及其可用加载项的信息、获取当前应用或其加载项的许可证信息、为当前用户购买应用或加载项以及执行其他任务。 若要获取 StoreContext 对象，请执行以下操作之一：

在单用户应用（即仅在启动应用的用户的上下文中运行的应用）中，使用静态 GetDefault 方法获取可用于访问用户的 Microsoft Store 相关数据的 StoreContext 对象。 大多数通用 Windows 平台 (UWP) 应用都是单用户应用。

在多用户应用中，使用静态 GetForUser 方法获取 StoreContext 对象，该对象可用于访问在使用应用时通过其 Microsoft 帐户登录的特定用户的相关数据。 以下示例获取第一个可用用户的 StoreContext 对象。

注意

使用桌面桥的 Windows 桌面应用程序必须执行额外的步骤来配置 StoreContext 对象，然后才能使用此对象。 有关详细信息，请参阅此部分。

拥有 StoreContext 对象后，可以开始调用此对象的方法来获取当前应用及其加载项的 Store 产品信息、检索当前应用及其加载项的许可证信息、为当前用户购买应用或加载项，以及执行其他任务。 有关可以使用此对象执行的常见任务的详细信息，请参阅以下文章：

有关演示如何使用 StoreContext 和 Windows.Services.Store 命名空间中的其他类型的示例应用，请参阅 Store 示例。

使用 Windows.Services.Store 命名空间在应用中向客户提供应用内购买：

如果应用提供可供客户购买的加载项，请在合作伙伴中心为应用创建加载项提交。

在应用中编写代码以检索应用或应用提供的加载项的产品信息，然后确定许可证是否处于活动状态（即用户是否有使用应用或加载项的许可证）。 如果许可证未处于活动状态，则会显示一个 UI，以应用内购买的形式向用户出售应用或加载项。

如果用户选择购买应用或加载项，请使用适当的方法来购买产品：

按照本文中的测试指南测试你的实现。

使用 Windows.Services.Store 命名空间排除或限制应用的试用版功能：

在合作伙伴中心将应用配置为免费试用。

在应用中编写代码以检索应用或应用提供的加载项的产品信息，然后确定与应用关联的许可证是否为试用版许可证。

如果是试用版，请排除或限制应用中的某些功能，然后在用户购买完整许可证后启用这些功能。 有关详细信息和代码示例，请参阅实现应用的试用版。

按照本文中的测试指南测试你的实现。

如果应用使用 Windows.Services.Store 命名空间中的 API 来实现应用内购买或试用功能，则必须将应用发布到 Store 并将其下载到开发设备，才可使用其许可证进行测试。 按照以下过程测试代码：

如果应用尚未在 Microsoft Store 中发布和提供，请确保应用满足 Windows 应用认证工具包最低要求、将应用提交到合作伙伴中心，并确保应用通过认证过程。 可以配置应用，使其在测试期间无法在 Store 中被发现。 请注意正确配置软件包外部测试版。 可能无法下载错误配置的软件包外部测试版。

接下来，确保你已完成以下操作：

在项目在 Visual Studio 中打开的情况下，单击“项目菜单”，指向“Microsoft Store”，然后单击“将应用与 Microsoft Store 关联”。 完成向导中的说明以将应用项目与合作伙伴中心帐户中要用于测试的应用关联。

注意

如果未将项目与 Store 中的应用关联，StoreContext 方法会将其返回值的 ExtendedError 属性设置为错误代码值 0x803F6107。 此值指示 Store 完全不知道该应用。

如果尚未这样做，请从上一步中指定的 Store 安装应用，运行该应用一次，然后将其关闭。 这可确保将应用的有效许可证安装到开发设备。

在 Visual Studio 中，开始运行或调试项目。 代码应从与本地项目关联的 Store 应用中检索应用和加载项数据。 如果系统提示重新安装应用，请按照说明操作，然后运行或调试项目。

注意

完成这些步骤后，可以继续更新应用的代码，然后在开发计算机上调试更新的项目，而无需将新的包提交到 Store。 只需将应用的 Store 版本下载到开发计算机一次即可获取将用于测试的本地许可证。 只需在完成测试后向 Store 提交新的应用包，并向客户提供应用内购买或试用相关功能。

如果应用使用 Windows.ApplicationModel.Store 命名空间，则可以在应用中使用 CurrentAppSimulator 类在测试期间模拟许可证信息，然后再将应用提交到 Store。 有关详细信息，请参阅 CurrentApp 和 CurrentAppSimulator 类入门。

注意

Windows.Services.Store 命名空间不提供可用于在测试期间模拟许可证信息的类。 如果使用 Windows.Services.Store 命名空间中来实现应用内购买或试用，则必须将应用发布到 Store 并将其下载到开发设备，才可使用其许可证进行测试，如上所述。

Windows.Services.Store 命名空间不提供可用于在应用代码中获取成功购买的交易收据的 API。 此体验不同于与使用 Windows.ApplicationModel.Store 命名空间的应用，后者可以使用客户端 API 检索交易收据。

如果使用 Windows.Services.Store 命名空间实现应用内购买，并且想要验证给定客户是否已购买应用或加载项，则可以使用 Microsoft Store 集合 REST API 中的查询产品方法。 此方法的返回数据可确认指定的客户是否具有给定产品的权利，并提供用户获取该产品的交易数据。 Microsoft Store 集合 API 使用 Azure AD 身份验证来检索此信息。

使用桌面桥的桌面应用程序可以使用 StoreContext 类来实现应用内购买和试用。 但是，如果你有一个 Win32 桌面应用程序或者一个其窗口句柄 (HWND) 与呈现框架相关联的的桌面应用程序（如 WPF 或 Windows 应用 SDK 应用程序），则该应用程序必须配置 StoreContext 对象，以便为该对象所显示的模式对话框指定哪个应用程序窗口是所有者窗口。

许多 StoreContext 成员（以及通过 StoreContext 对象访问的其他相关类型的成员）向用户显示 Store 相关操作（例如购买产品）的模式对话框。 如果桌面应用程序没有配置 StoreContext 对象来指定模式对话框的所有者窗口，则此对象返回不准确的数据或错误信息。

若要在使用桌面桥的桌面应用程序中配置 StoreContext 对象，请执行以下步骤。

如果应用程序通过 C# 结合使用 .NET 6 或更高版本编写，请执行以下步骤。

确保将项目文件中的 TargetFramework 属性设置为特定的 Windows SDK 版本以访问 Windows 运行时 API，该 API 提供对 WinRT.Interop 命名空间的访问权限。 例如：

按照本文前面部分所述，使用 GetDefault 方法（或 GetForUser 方法，如果应用是多用户应用）获取 StoreContext 对象。 若要使用指定的窗口句柄初始化对话框，请使用 WinRT.Interop.WindowNative.GetWindowHandle 和 WinRT.Interop.InitializeWithWindow.Initialize 方法（请参阅检索窗口句柄 (HWND) 和显示依赖于 CoreWindow 的 WinRT UI 对象）。

如果应用程序使用早期版本的 .NET 或 C++ 编写，请执行以下步骤。

执行下列操作之一，使应用能够访问 IInitializeWithWindow 接口：

如果应用程序使用 C# 或 Visual Basic 之类的托管语言（.NET 6 之前）编写，则在应用代码中使用 ComImport 属性声明 IInitializeWithWindow 接口，如以下 C# 示例所示。 此示例假设代码文件具有 System.Runtime.InteropServices 命名空间的 using 语句。

如果应用程序是采用 C++ 编写的，请在代码中添加对 shobjidl.h 头文件的引用。 此头文件包含 IInitializeWithWindow 接口的声明。

按照本文前面部分所述，使用 GetDefault 方法（或 GetForUser 方法，如果你的应用是多用户应用）获取 StoreContext 对象，并将此对象转换为 IInitializeWithWindow 对象。 然后，调用 IInitializeWithWindow.Initialize 方法，并传递希望作为 StoreContext 方法显示的任何模式对话框的所有者的窗口句柄。 以下 C# 示例演示如何将应用主窗口的句柄传递给该方法。 另请参阅检索窗口句柄 (HWND) 和显示依赖于 CoreWindow 的 WinRT UI 对象。

Store 中的每个产品至少有一个 SKU，每个 SKU 至少有一个可用性。 已经为合作伙伴中心的大多数开发人员抽象掉这些概念，大多数开发人员永远不需要为其应用或加载项定义 SKU 或可用性。 但是，由于 Windows.Services.Store 命名空间中 Store 产品的对象模型包括 SKU 和可用性，因此对这些概念有基本了解对于某些方案很有用。

Store 中的每个应用、加载项或其他产品都有关联的 Store ID（有时也称为产品 Store ID）。 许多 API 需要 Store ID 才能对应用或加载项执行操作。

Store 中任何产品的 Store ID 为 12 个字符的字母数字字符串，例如 9NBLGGH4R315。 可通过多种不同的方式获取 Store 中产品的 Store ID：

对于具有 SKU 和可用性的产品，SKU 和可用性也有自己的不同格式的 Store ID。

如果要在应用上下文中向客户提供加载项，你必须在合作伙伴中心创建加载项提交时为加载项输入唯一产品 ID。 你可以使用此产品 ID 来引用代码中的加载项，但可以使用产品 ID 的具体场景取决于你在应用中用于应用内购买的命名空间。

注意

你在合作伙伴中心为加载项输入的产品 ID 不同于此加载项的 Store ID。 Store ID 由合作伙伴中心生成。

如果你的应用使用 Windows.Services.Store 命名空间，则可以使用产品 ID 轻松标识表示加载项的 StoreProduct 或表示加载项许可证的 StoreLicense。 产品 ID 由 StoreProduct.InAppOfferToken 和 StoreLicense.InAppOfferToken 属性公开。

注意

尽管产品 ID 是标识代码中的加载项的有用方法，但 Windows.Services.Store 命名空间中的大多数操作都使用加载项的 Store ID，而不是产品 ID。 例如，若要以编程方式检索应用的一个或多个已知加载项，请将加载项的 Store ID（而不是产品 ID）传递给 GetStoreProductsAsync 方法。 同样，若要将易耗品加载项报告为已完成，请将加载项的 Store ID（而不是产品 ID）传递给 ReportConsumableFulfillmentAsync 方法。

如果应用使用 Windows.ApplicationModel.Store 命名空间，你需要使用自己在合作伙伴中心向加载项分配的产品 ID 来进行大多数操作。 例如：

使用产品 ID 标识表示加载项的 ProductListing 或表示加载项许可证的 ProductLicense。 产品 ID 由 ProductListing.ProductId 和 ProductLicense.ProductId 属性公开。

在使用 RequestProductPurchaseAsync 方法为用户购买加载项时，请指定产品 ID。 有关详细信息，请参阅启用应用内产品购买。

在使用 ReportConsumableFulfillmentAsync 方法将易耗品加载项报告为已完成时，请指定产品 ID。 有关详细信息，请参阅启用易耗品应用内产品购买。