取得應用程式和附加元件的產品資訊Get product info for apps and add-ons

本文示範如何使用 Windows.Services.Store 命名空間中的 StoreContext 類別的方法,來存取目前應用程式及其中一個附加元件的 Microsoft Store 相關資訊。This article demonstrates how to use methods of the StoreContext class in the Windows.Services.Store namespace to access Store-related info for the current app or one of its add-ons.

如需完整的範例應用程式,請參閱市集範例For a complete sample application, see the Store sample.

注意

Windows.Services.Store 命名空間在 Windows 10 (版本 1607) 中引進,只適用於目標為 Visual Studio 中 Windows 10 Anniversary Edition (10.0;組建 14393) 或更新版本的專案。The Windows.Services.Store namespace was introduced in Windows 10, version 1607, and it can only be used in projects that target Windows 10 Anniversary Edition (10.0; Build 14393) or a later release in Visual Studio. 如果您的 app 目標為較早版本的 Windows 10,您必須使用 Windows.ApplicationModel.Store 命名空間,而不是 Windows.Services.Store 命名空間。If your app targets an earlier version of Windows 10, you must use the Windows.ApplicationModel.Store namespace instead of the Windows.Services.Store namespace. 如需詳細資訊,請參閱這篇文章For more information, see this article.

先決條件Prerequisites

這些範例包含下列先決條件:These examples have the following prerequisites:

  • 適用於目標為 Windows 10 Anniversary Edition (10.0;組建 14393) 或更新版本的通用 Windows 平台 (UWP) App 的 Visual Studio 專案。A Visual Studio project for a Universal Windows Platform (UWP) app that targets Windows 10 Anniversary Edition (10.0; Build 14393) or a later release.
  • 您已在合作夥伴中心中 建立提交應用 程式,並在存放區中發佈此應用程式。You have created an app submission in Partner Center and this app is published in the Store. 測試時您也可以選擇將應用程式設定為不可在市集中搜尋。You can optionally configure the app so it is not discoverable in the Store while you test it. 如需詳細資訊,請參閱我們的測試指南For more information, see our testing guidance.
  • 如果您想要取得應用程式之附加元件的產品資訊,您也必須 在合作夥伴中心中建立附加元件。If you want to get product info for an add-on for the app, you must also create the add-on in Partner Center.

這些範例中的程式碼假設:The code in these examples assume:

  • 程式碼會在 Page 的內容中執行,其中包含名為 workingProgressRingProgressRing 和名為 textBlockTextBlockThe code runs in the context of a Page that contains a ProgressRing named workingProgressRing and a TextBlock named textBlock. 這些物件可個別用來表示發生非同步作業,以及顯示輸出訊息。These objects are used to indicate that an asynchronous operation is occurring and to display output messages, respectively.
  • 程式碼檔案含有適用於 Windows.Services.Store 命名空間的 using 陳述式。The code file has a using statement for the Windows.Services.Store namespace.
  • App 是單一使用者 app,僅會在啟動 app 的使用者內容中執行。The app is a single-user app that runs only in the context of the user that launched the app. 如需詳細資訊,請參閱 App 內購買和試用版For more information, see In-app purchases and trials.

注意

如果您的傳統型應用程式使用傳統型橋接器,您可能需要新增這些範例中未顯示的額外程式碼來設定 StoreContext 物件。If you have a desktop application that uses the Desktop Bridge, you may need to add additional code not shown in these examples to configure the StoreContext object. 如需詳細資訊,請參閱在使用傳統型橋接器的傳統型應用程式中使用 StoreContext 類別For more information, see Using the StoreContext class in a desktop application that uses the Desktop Bridge.

取得目前 App 的資訊Get info for the current app

若要取得目前 app 的 Microsoft Store 產品資訊,請使用 GetStoreProductForCurrentAppAsync 方法。To get Store product info about the current app, use the GetStoreProductForCurrentAppAsync method. 這是傳回 StoreProduct 物件的非同步方法,您可以使用該物件來取得資訊,例如價格。This is an asynchronous method that returns a StoreProduct object that you can use to get info such as the price.

private StoreContext context = null;

public async void GetAppInfo()
{
    if (context == null)
    {
        context = StoreContext.GetDefault();
        // If your app is a desktop app that uses the Desktop Bridge, you
        // may need additional code to configure the StoreContext object.
        // For more info, see https://aka.ms/storecontext-for-desktop.
    }

    // Get app store product details. Because this might take several moments,   
    // display a ProgressRing during the operation.
    workingProgressRing.IsActive = true;
    StoreProductResult queryResult = await context.GetStoreProductForCurrentAppAsync();
    workingProgressRing.IsActive = false;

    if (queryResult.Product == null)
    {
        // The Store catalog returned an unexpected result.
        textBlock.Text = "Something went wrong, and the product was not returned.";

        // Show additional error info if it is available.
        if (queryResult.ExtendedError != null)
        {
            textBlock.Text += $"\nExtendedError: {queryResult.ExtendedError.Message}";
        }

        return;
    }

    // Display the price of the app.
    textBlock.Text = $"The price of this app is: {queryResult.Product.Price.FormattedBasePrice}";
}

取得具有與目前應用程式相關聯的已知 Microsoft Store 識別碼的附加元件資訊Get info for add-ons with known Store IDs that are associated with the current app

若要針對您已經知道 Microsoft Store 識別碼的與目前應用程式相聯之附加元件的 Microsoft Store 產品資訊,請使用 GetStoreProductsAsync 方法。To get Store product info for add-ons that are associated with the current app and for which you already know the Store IDs, use the GetStoreProductsAsync method. 這是非同步方法,會傳回代表每個附加元件的 StoreProduct 物件集合。This is an asynchronous method that returns a collection of StoreProduct objects that represent each of the add-ons. 除了 Store 識別碼,您還必須將一個字串清單傳入此方法,以識別附加元件的類型。In addition to the Store IDs, you must pass a list of strings to this method that identify the types of the add-ons. 如需支援的字串值清單,請參閱 ProductKind 屬性。For a list of the supported string values, see the ProductKind property.

注意

GetStoreProductsAsync方法傳回與應用程式相關聯之指定附加元件的產品資訊,無論目前是否能買到附加元件。The GetStoreProductsAsync method returns product info for the specified add-ons that are associated with the app, regardless of whether the add-ons are currently available for purchase. 若要擷取的目前目前可購買的應用程式的所有附加元件相關資訊,請改為使用 下列區段中所述的 GetAssociatedStoreProductsAsync 方式。To retrieve info for all the add-ons for the current app that can currently be purchased, use the GetAssociatedStoreProductsAsync method as described in the following section instead.

此範例利用與目前應用程式相關聯之指定 Microsoft Store 識別碼來擷取耐久性附加元件的資訊。This example retrieves info for durable add-ons with the specified Store IDs that are associated with the current app.

private StoreContext context = null;

public async void GetProductInfo()
{
    if (context == null)
    {
        context = StoreContext.GetDefault();
        // If your app is a desktop app that uses the Desktop Bridge, you
        // may need additional code to configure the StoreContext object.
        // For more info, see https://aka.ms/storecontext-for-desktop.
    }

    // Specify the kinds of add-ons to retrieve.
    string[] productKinds = { "Durable" };
    List<String> filterList = new List<string>(productKinds);

    // Specify the Store IDs of the products to retrieve.
    string[] storeIds = new string[] { "9NBLGGH4TNMP", "9NBLGGH4TNMN" };

    workingProgressRing.IsActive = true;
    StoreProductQueryResult queryResult =
        await context.GetStoreProductsAsync(filterList, storeIds);
    workingProgressRing.IsActive = false;

    if (queryResult.ExtendedError != null)
    {
        // The user may be offline or there might be some other server failure.
        textBlock.Text = $"ExtendedError: {queryResult.ExtendedError.Message}";
        return;
    }

    foreach (KeyValuePair<string, StoreProduct> item in queryResult.Products)
    {
        // Access the Store info for the product.
        StoreProduct product = item.Value;

        // Use members of the product object to access info for the product...
    }
}

從目前應用程式取得可購買的附加元件資訊Get info for add-ons that are available for purchase from the current app

若要針對目前應用程式可購買的附加元件取得 Microsoft Store 產品資訊,請使用 GetAssociatedStoreProductsAsync 方法。To get Store product info for the add-ons that are currently available for purchase from the current app, use the GetAssociatedStoreProductsAsync method. 這是非同步方法,會傳回代表每個可用附加元件的 StoreProduct 物件集合。This is an asynchronous method that returns a collection of StoreProduct objects that represent each of the available add-ons. 您必須將一個字串清單傳入此方法,以識別您想要擷取的附加元件類型。You must pass a list of strings to this method that identify the types of add-ons you want to retrieve. 如需支援的字串值清單,請參閱 ProductKind 屬性。For a list of the supported string values, see the ProductKind property.

注意

如果應用程式有很多可購買的附加元件,您也可以使用 GetAssociatedStoreProductsWithPagingAsync 方法,使用分頁來傳回附加元件結果。If the app has many add-ons that are available for purchase, you can alternatively use the GetAssociatedStoreProductsWithPagingAsync method to use paging to return the add-on results.

下列範例會擷取適用於所有耐久性附加元件、Microsoft Store 管理的消費性附加元件,以及開發人員管理的消費性附加元件的相關資訊,這些均可從目前應用程式購買。The following example retrieves info for all durable add-ons, Store-managed consumable add-ons, and developer-managed consumable add-ons that are available for purchase from the current app.

private StoreContext context = null;

public async void GetAddOnInfo()
{
    if (context == null)
    {
        context = StoreContext.GetDefault();
        // If your app is a desktop app that uses the Desktop Bridge, you
        // may need additional code to configure the StoreContext object.
        // For more info, see https://aka.ms/storecontext-for-desktop.
    }

    // Specify the kinds of add-ons to retrieve.
    string[] productKinds = { "Durable", "Consumable", "UnmanagedConsumable" };
    List<String> filterList = new List<string>(productKinds);

    workingProgressRing.IsActive = true;
    StoreProductQueryResult queryResult = await context.GetAssociatedStoreProductsAsync(filterList);
    workingProgressRing.IsActive = false;

    if (queryResult.ExtendedError != null)
    {
        // The user may be offline or there might be some other server failure.
        textBlock.Text = $"ExtendedError: {queryResult.ExtendedError.Message}";
        return;
    }

    foreach (KeyValuePair<string, StoreProduct> item in queryResult.Products)
    {
        // Access the Store product info for the add-on.
        StoreProduct product = item.Value;

        // Use members of the product object to access listing info for the add-on...
    }
}

取得使用者已購買之目前應用程式的附加元件資訊Get info for add-ons for the current app that the user has purchased

若要針對目前使用者已購買的目前應用程式取得附加元件的 Microsoft Store 產品資訊,請使用 GetUserCollectionAsync 方法。To get Store product info for add-ons that the current user has purchased, use the GetUserCollectionAsync method. 這是傳回 StoreProduct 物件集合的非同步方法,其代表每個附加元件。This is an asynchronous method that returns a collection of StoreProduct objects that represent each of the add-ons. 您必須將一個字串清單傳入此方法,以識別您想要擷取的附加元件類型。You must pass a list of strings to this method that identify the types of add-ons you want to retrieve. 如需支援的字串值清單,請參閱 ProductKind 屬性。For a list of the supported string values, see the ProductKind property.

注意

如果 App 有很多附加元件,您也可以使用 GetUserCollectionWithPagingAsync 方法,使用分頁來傳回附加元件結果。If the app has many add-ons, you can alternatively use the GetUserCollectionWithPagingAsync method to use paging to return the add-on results.

下列範例會使用指定的 存放區識別碼來抓取持久附加元件的資訊。The following example retrieves info for durable add-ons with the specified Store IDs.

private StoreContext context = null;

public async void GetUserCollection()
{
    if (context == null)
    {
        context = StoreContext.GetDefault();
        // If your app is a desktop app that uses the Desktop Bridge, you
        // may need additional code to configure the StoreContext object.
        // For more info, see https://aka.ms/storecontext-for-desktop.
    }

    // Specify the kinds of add-ons to retrieve.
    string[] productKinds = { "Durable" };
    List<String> filterList = new List<string>(productKinds);

    workingProgressRing.IsActive = true;
    StoreProductQueryResult queryResult = await context.GetUserCollectionAsync(filterList);
    workingProgressRing.IsActive = false;

    if (queryResult.ExtendedError != null)
    {
        // The user may be offline or there might be some other server failure.
        textBlock.Text = $"ExtendedError: {queryResult.ExtendedError.Message}";
        return;
    }

    foreach (KeyValuePair<string, StoreProduct> item in queryResult.Products)
    {
        StoreProduct product = item.Value;

        // Use members of the product object to access info for the product...
    }
}