> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 檢查更新

> 在您的遊戲中使用 XStoreQueryGameAndDlcPackageUpdatesAsync 檢查並套用 XBOX 遊戲和 DLC 套件更新，以確保多人遊戲功能一致。

如果遊戲必須保持最新狀態，遊戲可以檢查並套用更新。當遊戲涉及多人遊戲功能，且所有執行遊戲的玩家必須擁有相同功能時，這種情況通常很重要。

遊戲可以使用 [XStoreQueryGameAndDlcPackageUpdatesAsync](/zh-TW/reference/system/xstore/xstore_members) 檢查更新，如下列範例程式碼所示：

```cpp theme={null}
void CALLBACK QueryGameAndDlcPackageUpdatesCallback(XAsyncBlock* async)
{
    unsigned int numUpdates = 0;

    HRESULT hr = XStoreQueryGameAndDlcPackageUpdatesResultCount(async, &numUpdates);

    if (SUCCEEDED(hr))
    {
        if (numUpdates > 0)
        {
            std::vector<XStorePackageUpdate> packages(numUpdates);

            hr = XStoreQueryGameAndDlcPackageUpdatesResult(async, numUpdates, packages.data());

            if (SUCCEEDED(hr))
            {
                for (auto &package : packages)
                {
                    printf("Update available %s\n", package.packageIdentifier);
                }
            }
        }
        else
        {
            printf("No updates are available\n");
        }
    }

    delete async;
}

void CheckForUpdates()
{
    auto asyncBlock = new XAsyncBlock{};
    asyncBlock->queue = m_asyncQueue;
    asyncBlock->callback = QueryGameAndDlcPackageUpdatesCallback;

    if (FAILED(XStoreQueryGameAndDlcPackageUpdatesAsync(m_xStoreContext, asyncBlock)))
    {
        delete asyncBlock;
    }
}
```

如果遊戲包含許多不需要檢查更新的 DLC 項目 (例如僅用於授權的空白 DLC 套件)，前述程式碼會逐一檢查每個項目，因而造成不必要的負荷。

請改用 [XStoreQueryPackageUpdatesAsync](/zh-TW/reference/system/xstore/xstore_members)，並依使用 [XPackageGetCurrentProcessPackageIdentifier](/zh-TW/reference/system/xstore/xstore_members) 取得的目前遊戲套件識別碼進行篩選，或篩選 [XPackageEnumeratePackages](/zh-TW/reference/system/xstore/xstore_members) 傳回的套件識別碼：

```cpp theme={null}
void CALLBACK QueryPackageUpdatesCallback(XAsyncBlock* async)
{
    unsigned int numUpdates = 0;

    HRESULT hr = XStoreQueryPackageUpdatesResultCount(async, &numUpdates);

    if (FAILED(hr))
    {
        printf("XStoreQueryPackageUpdatesResultCount failed : 0x%x\n", hr);
        return;
    }

    printf("Number of updates: %d", numUpdates);

    if (count > 0)
    {
        std::vector<XStorePackageUpdate> packages(numUpdates);

        hr = XStoreQueryPackageUpdatesResult(async, numUpdates, packages.data());
        
        if (SUCCEEDED(hr))
        {
            for (auto &package : packages)
            {
                printf("Update available %s\n", package.packageIdentifier);
            }
        }
    }
}

void QueryPackageUpdates()
{
    std::vector<std::string> packageIds;

    HRESULT hr = XPackageEnumeratePackages(
        XPackageKind::Game,
        XPackageEnumerationScope::ThisOnly, // this will return for the base game only
        &packageIds, [](void* context, const XPackageDetails* details) -> bool
        {
            auto packageIds = reinterpret_cast<std::vector<std::string>*>(context);

            printf("Identifier: %s name: %s\n", details->packageIdentifier, details->displayName);

            packageIds->push_back(details->packageIdentifier);
        });

    // packageIds now populated with just the base game package Id

    auto asyncBlock = new XAsyncBlock();
    asyncBlock->queue = m_asyncQueue;
    asyncBlock->context = m_storeContext;
    asyncBlock->callback = QueryPackageUpdatesCallback;

    hr = XStoreQueryPackageUpdatesAsync(
        m_storeContext,
        packageIds.data(),
        packageIds.size(),
        asyncBlock);

    if (FAILED(hr))
    {
        printf("XStoreQueryPackageUpdatesAsync failed: 0x%x\n", hr);
        return;
    }
}
```

## 下載並安裝更新

識別出更新集合之後，請使用 [XStoreDownloadAndInstallPackageUpdatesAsync](/zh-TW/reference/system/xstore/xstore_members) 將所有更新排入佇列並下載。

<Note />

此時，遊戲會終止以套用更新。此程序會在沒有警告的情況下發生，因此在呼叫此函式之前，請提供充分的使用者通知或確認。

```cpp theme={null}
void DownloadUpdates()
{
    std::vector<const char*> packageIds;

    for (XStorePackageUpdate package : m_updates)
    {
        // m_updates populated from the update check
        packageIds.push_back(package.packageIdentifier);
    }

    if (!packageIds.empty())
    {
        auto asyncBlock = new XAsyncBlock{};
        asyncBlock->context = this;
        asyncBlock->queue = m_asyncQueue;
        asyncBlock->callback = [](XAsyncBlock* asyncBlockInner)
        {
            // Called when update is complete
            auto pThis = reinterpret_cast<Sample*>(asyncBlockInner->context);
            HRESULT hr = XStoreDownloadAndInstallPackageUpdatesResult(asyncBlockInner);

            delete asyncBlockInner;
        };

        HRESULT hr = XStoreDownloadAndInstallPackageUpdatesAsync(m_xStoreContext, packageIds.data(), packageIds.size(), asyncBlock);
    }
}
```

## 監視下載進度

下載進行中時，請使用 [XPackageCreateInstallationMonitor](/zh-TW/reference/system/xstore/xstore_members) 監視下載進度：

```cpp theme={null}
void CreateInstallationMonitor(const char* packageId)
{
    XPackageInstallationMonitorHandle pimHandle;

    HRESULT hr = XPackageCreateInstallationMonitor(packageId, 0, nullptr, 1000, m_asyncQueue, &pimHandle);

    if(SUCCEEDED(hr))
    {
        XTaskQueueRegistrationToken callbackToken;

        XPackageRegisterInstallationProgressChanged(
            m_pimHandle,
            this,
            [](void* context, XPackageInstallationMonitorHandle pimHandle)
            {
                XPackageInstallationProgress progress;
                XPackageGetInstallationProgress(pimHandle, &progress);

                if(!progress.completed)
                {
                    printf("%llu%% installed\n", static_cast<double>(progress.installedBytes) / static_cast<double>(progress.totalBytes);
                }
                else
                {
                    XPackageCloseInstallationMonitorHandle(pimHandle);
                }
            }, &callbackToken);
    }
}
```

## 測試更新

在開發期間，您只能使用本機套件測試更新的可用性。

1. 建立含有更新檢查和下載程式碼的 V1 套件。
2. 建立具有相同身分識別但版本號碼遞增的 V2 套件。
3. 執行 `xbapp/wdapp install` V1。
4. 執行 `xbapp/wdapp update` V2 `/a`。
5. 啟動 V1。

請確定套件之間的內容識別碼相符。

此程序的結果是，V1 的 `XStoreQueryGameAndDlcPackageUpdatesAsync` 或 `XStoreQueryPackageUpdatesAsync` 呼叫會找到任何可用的更新，而 `XStoreDownloadAndInstallPackageUpdatesAsync` 會使用所公告的 V2 套件更新 V1。當 V2 正在「下載」時，此狀態會以佇列中項目的形式顯示在 XBOX 下載佇列、XBOX 應用程式或 Microsoft Store 應用程式中。安裝完成時，V2 即已安裝。您可以使用 `xbapp/wdapp list[dlc]` 驗證安裝。

使用 `/m` 而非 `/a` 會使更新成為「必要」更新，這只會影響 [XStorePackageUpdate](/zh-TW/reference/system/xstore/xstore_members)`.isMandatory` 欄位。

由於簽署方式不同，您無法從開發組建更新至從商店下載的套件。

如需如何建立有效率的更新以及不同測試方式的詳細資訊，請參閱下一節所參考的內容更新頁面。

## 參考 API 文件

* [XStore (API 內容)](/zh-TW/reference/system/xstore/xstore_members)
  * 函式
    * [XStoreQueryGameAndDlcPackageUpdatesAsync](/zh-TW/reference/system/xstore/xstore_members)
    * [XStoreQueryPackageUpdatesAsync](/zh-TW/reference/system/xstore/xstore_members)
    * [XStoreDownloadAndInstallPackageUpdatesAsync](/zh-TW/reference/system/xstore/xstore_members)
  * 結構
    * [XStorePackageUpdate](/zh-TW/reference/system/xstore/xstore_members)
* [XPackage (API 內容)](/zh-TW/reference/system/xstore/xstore_members)
  * 函式
    * [XPackageGetCurrentProcessPackageIdentifier](/zh-TW/reference/system/xstore/xstore_members)
    * [XPackageEnumeratePackages](/zh-TW/reference/system/xstore/xstore_members)
    * [XPackageCreateInstallationMonitor](/zh-TW/reference/system/xstore/xstore_members)

## 另請參閱

[商務概觀](/zh-TW/publishing/xstore-commerce/xstore-commerce-overview)

[啟用 XStore 開發與測試](/zh-TW/publishing/xstore-commerce/xstore-product-testing-setup)

內容更新最佳做法

建立、檢查和測試內容更新

[XStore API 參考](/zh-TW/reference/system/xstore/xstore_members)


## Related topics

- [检查更新](/zh-CN/publishing/xstore-commerce/xstore-checking-updates.md)
- [创建、检查和测试内容更新](/zh-CN/build/core-features/common/packaging/packaging-testing-updates.md)
- [XStoreDownloadAndInstallPackageUpdatesAsync](/zh-CN/reference/system/xstore/functions/xstoredownloadandinstallpackageupdatesasync.md)
- [XStoreQueryGameAndDlcPackageUpdatesAsync](/zh-CN/reference/system/xstore/functions/xstorequerygameanddlcpackageupdatesasync.md)
- [XStoreQueryPackageUpdatesAsync](/zh-CN/reference/system/xstore/functions/xstorequerypackageupdatesasync.md)