应用内购买和试用

使用 Windows.Services.Store 命名空间进行应用内购买和试用

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

本部分

• 视频
• 开始使用 StoreContext 类
• 实现应用内购买
• 实现试用功能
• 测试应用内购买功能或试用版实现
• 应用内购买的收据
• 使用 StoreContext 类与 Desktop Bridge
• 产品、SKU 和可用性
• 存储 ID

StoreContext 类入门

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

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

  Windows.Services.Store.StoreContext context = StoreContext.GetDefault();
  

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

  var users = await Windows.System.User.FindAllAsync();
  Windows.Services.Store.StoreContext context = StoreContext.GetForUser(users[0]);
  

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

• 获取应用和附加组件的产品信息
• 获取应用和加载项的许可证信息
• 启用应用内购买和附加功能
• 启用消耗品附加购买功能
• 为应用启用订阅附加组件
• 实现应用的试用版

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

实现应用内购买

以便使用 Windows.Services.Store 命名空间为您的应用客户提供应用内购买功能：

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

2. 在应用中编写代码，以 检索应用或其提供的加载项的产品信息，然后 确定许可证是否为有效状态（即用户是否持有使用该应用或加载项的许可证）。 如果许可证未处于活动状态，请显示一个界面，以应用内购买的形式向用户提供应用或插件。

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

   • 如果用户正在购买您的应用或持久附加组件，请按照 启用应用和附加组件内购买中的说明进行操作。
   • 如果用户正在购买易耗型加载项，请按照 启用易耗型加载项购买中的说明进行操作。
   • 如果用户正在购买订阅加载项，请按照 “为应用启用订阅加载项”中的说明作。

4. 根据本文 测试指南 对实现进行测试。

实现试用功能

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

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

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

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

4. 根据本文 测试指南 对实现进行测试。

测试应用内购买或试用功能的实现

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

1. 如果你的应用尚未在应用商店中发布并可用，请确保你的应用满足最低 Windows 应用认证工具包 要求，在合作伙伴中心 提交你的应用 ，并确保你的应用通过认证过程。 你可以 配置你的应用，使其在测试期间在应用商店 中不可见。 请注意正确配置 包航班。 配置不正确的包航班可能无法被下载。

2. 接下来，请确保已完成以下内容：

   • 在应用中编写代码，该代码使用 Windows.Services.Store 命名空间中的 StoreContext 类和其他相关类型来实现应用内购买或试用功能。
   • 如果应用提供客户可以购买的加载项，在合作伙伴中心为应用创建加载项提交。
   • 如果想要排除或限制应用试用版中的某些功能， 请在合作伙伴中心将应用配置为免费试用。

3. 在 Visual Studio 中打开项目后，单击 “项目”菜单，指向 “应用商店”，然后单击“ 将应用与应用商店关联”。 完成向导中的说明，将应用项目与要用于测试的合作伙伴中心帐户中的应用相关联。

   注释

   如果不将项目与应用商店中的应用相关联， StoreContext 方法会将其返回值的 ExtendedError 属性设置为错误代码值0x803F6107。 此值指示应用商店对应用没有任何了解。

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

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

   注释

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

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

应用内购收据

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

如果您使用 Windows.Services.Store 命名空间实现应用内购买，并且希望验证指定客户是否已购买某个应用或附加组件，则可以使用 Microsoft Store 集合 REST API中的 产品查询方法。 此方法的返回数据确认指定的客户是否具有给定产品的权利，并为用户获取该产品的事务提供数据。 Microsoft 商店集合 API 使用 Azure AD 身份验证来检索此信息。

将 StoreContext 类与桌面桥配合使用

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

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

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

对于 .NET 6 或更高版本

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

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

   <PropertyGroup>
     <!-- You can also target other versions of the Windows SDK and .NET, e.g. "net6.0-windows10.0.19041.0" -->
     <TargetFramework>net6.0-windows10.0.22000.0</TargetFramework>
   </PropertyGroup>
   

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

   StoreContext context = StoreContext.GetDefault();
   // Obtain window handle by passing in pointer to the window object
   var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(windowObject);
   // Initialize the dialog using wrapper function for IInitializeWithWindow
   WinRT.Interop.InitializeWithWindow.Initialize(context, hwnd); 
   

对于较早版本的 .NET 或 C++

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

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

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

     [ComImport]
     [Guid("3E68D4BD-7135-4D10-8018-9FB6D9F33FA1")]
     [InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
     public interface IInitializeWithWindow
     {
         void Initialize(IntPtr hwnd);
     }
     

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

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

   StoreContext context = StoreContext.GetDefault();
   IInitializeWithWindow initWindow = (IInitializeWithWindow)(object)context;
   initWindow.Initialize(System.Diagnostics.Process.GetCurrentProcess().MainWindowHandle);
   

产品、SKU 和可用性

商店中的每个产品至少有一个 SKU，每个 SKU 至少有一个 库存情况。 在合作伙伴中心，这些概念对大多数开发人员而言是抽象的，多数开发人员永远不会为他们的应用或附加组件定义 SKU 或可用性。 但是，由于 Windows.Services.Store 命名空间中 Store 产品的对象模型包括 SKU 和可用性，因此对这些概念的基本了解对于某些方案很有用。

存储 ID

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

在商店中，任何产品的商店 ID 都是一个由 12 个字符组成的字母数字字符串，例如 9NBLGGH4R315。 可通过多种不同的方式在应用商店中获取产品的应用商店 ID：

• 对于应用，可以在合作伙伴中心 应用标识页上获取应用商店 ID。
• 在合作伙伴中心的附加组件概述页上，您可以获取附加组件的应用商店 ID。
• 对于任何产品，也可以使用代表产品的 StoreProduct 对象的 StoreId 属性以编程方式获取应用商店 ID。

对于具有 SKU 和可用性的产品，这些 SKU 和可用性还拥有格式不同的专属店铺 ID。

如何在代码中使用产品 ID 添加加载项

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

使用 Windows.Services.Store 命名空间的应用

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

使用 Windows.ApplicationModel.Store 命名空间的应用

如果应用程序使用 Windows.ApplicationModel.Store 命名空间，那么在为大多数操作指定加载项时需要使用您在合作伙伴中心分配的产品 ID。 例如：

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

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

• 使用 ReportConsumableFulfillmentAsync 方法将消耗型附加组件报告为已完成时，请指定产品 ID。 有关详细信息，请参阅 启用应用内产品购买。

相关主题

• 获取应用和附加组件的产品信息
• 获取应用和加载项的许可证信息
• 启用应用内购买和附加功能
• 启用消耗品附加购买功能
• 为应用启用订阅附加组件
• 实现应用的试用版
• 应用商店操作的错误代码
• 使用 Windows.ApplicationModel.Store 命名空间 应用内购买和试用