管理并授权可下载内容 (DLC)

可下载内容 (DLC) 是一种产品，购买后会给用户提供一个可下载的包。DLC 需要单独授权和挂载后，其内容才能被访问。 DLC 包可根据每个设备的内容共享行为进行授权，如游戏的产品共享模式所述。合作伙伴中心还支持不带包的耐用品。无包的耐用品适用于仅授权的产品，用于启用基础游戏已经安装的内容。这类仅授权产品省去了创建空包所需的步骤，否则用户还需下载这些空包。有关更多信息，请参阅如何使用无包的耐用品。

DLC 的开发工作流程

请参阅可下载内容 (DLC) 包的文档，以了解如何配置 DLC 内容的更多信息，包括如何通过 MicrosoftGame.config 与基础游戏建立关联。安装 DLC 有三种方式：

Loose DLC 部署
本地安装 DLC 包
从商店安装 DLC 包

1. Loose DLC 部署

安装指向你的 loose DLC MicrosoftGame.config 和资产文件的目录： XBOX：

> xbapp deploy <DLC directory>

Package Full Name: 41336MicrosoftATG.DLC1_2020.10.14.0_neutral__dspnxghe87tn0
The operation completed successfully.

PC：

> wdapp register <DLC directory>  

Registered 41336MicrosoftATG.DLC1_2020.10.14.0_x64__dspnxghe87tn0
Copied temporary generated AppXManifest.xml file to C:\Users\<ntuser>\AppData\Local\Temp\41336MicrosoftATG.DLC1_2020.10.14.0_x64__dspnxghe87tn0_AppXManifest.xml
The operation completed successfully.

2. 本地安装 DLC 包

安装由 makepkg 创建的 .xvc/.msixvc： XBOX：

> xbapp install <xvc package>  

12:16:21.800 Registered for streaming: 41336MicrosoftATG.DLC1_2020.10.14.0_neutral__dspnxghe87tn0_xs.xvc
12:16:22.645 Launch   0.00% Package   0.00%
12:16:32.650 Launch 100.00% Package 100.00%
12:16:32.651 Streaming install finished

The operation completed successfully.

PC：

> wdapp install <.msixvc package>  

Starting installation. See the Microsoft Store app for further details.
Launch   100% Package   100%
Installed 100%.
Installed 41336MicrosoftATG.DLC1_2020.10.14.0_x64__dspnxghe87tn0

3. 从商店安装 DLC 包

使用登录到开发沙盒的测试账号，在 Store 应用中搜索或直接链接到 DLC 产品页面并进行安装。

验证 DLC 安装

XBOX：

> xbapp listdlc

Registered DLC by Package Full Name:

   41336MicrosoftATG.DLC1_2020.10.14.0_neutral__dspnxghe87tn0

The operation completed successfully.

PC：

> wdapp listdlc

Registered DLC packages by Package Full Name:

41336MicrosoftATG.DLC1_2020.10.14.0_x64__dspnxghe87tn0

The operation completed successfully.

在 PC 上，也可以使用 PowerShell 中的 get-appxpackage 查看特定游戏已安装的 DLC，请注意 Dependencies 部分：

> get-appxpackage 41336MicrosoftATG.DownloadableContent

Name              : 41336MicrosoftATG.DownloadableContent
Publisher         : CN=A4954634-DF4B-47C7-AB70-D3215D246AF1
Architecture      : X64
ResourceId        :
Version           : 2020.10.14.0
PackageFullName   : 41336MicrosoftATG.DownloadableContent_2020.10.14.0_x64__dspnxghe87tn0
InstallLocation   : E:\Repos\ATG\gx_dev\Samples\Live\DownloadableContent\Gaming.Desktop.x64\Debug
IsFramework       : False
PackageFamilyName : 41336MicrosoftATG.DownloadableContent_dspnxghe87tn0
PublisherId       : dspnxghe87tn0
IsResourcePackage : False
IsBundle          : False
IsDevelopmentMode : True
NonRemovable      : False
Dependencies      : {41336MicrosoftATG.DLC1_2020.10.14.0_x64__dspnxghe87tn0}
IsPartiallyStaged : False
SignatureKind     : None
Status            : Ok

SignatureKind 表示已安装包的类型：本地构建并安装的包为 None，从商店安装的包为 Store。

购买并安装 DLC

请参阅商店基本操作一文，了解如何枚举目录并提供购买附加内容的功能。可通过检查 [XStoreProduct](/reference/system/xstore/xstore_members).hasDigitalDownload 判断附加内容产品是否为 DLC。如果 DLC 是从商店购买的，则 DLC 会被排队等待下载。如果 DLC 是使用 XStoreShowPurchaseUiAsync 购买的，DLC 不会排队等待下载。相反，游戏应根据代码手动请求下载。也可以选择创建监控器以跟踪进度。 包标识符 (package identifier) 是一个用于标识特定包的不透明字符串。该标识符在每个包上唯一，但游戏每次启动实例都不同。因此，请勿在当前会话之外存储或复用该标识符。根据不同场景，你可以使用以下方法获取包的包标识符：

调用 XStoreDownloadAndInstallPackagesAsync 下载并安装包后，可以通过调用 XStoreDownloadAndInstallPackagesResult 获取这些包的包标识符。
对于已下载并已安装的包，可以通过调用 XPackageEnumeratePackages，然后从每个枚举包传回给你的 XPackageEnumerationCallback 回调函数的 XPackageDetails 结构中检索包标识符。
可以通过调用 XPackageGetCurrentProcessPackageIdentifier 获取当前游戏的包标识符。

void StartDownload()
{
    auto async = new XAsyncBlock{};
    async->queue = m_asyncQueue;
    async->context = this;
    async->callback = [](XAsyncBlock* asyncBlockInner)
    {
        uint32_t count = 0;
        HRESULT hr = XStoreDownloadAndInstallPackagesResultCount(asyncBlockInner, &count);

        std::vector<char[XPACKAGE_IDENTIFIER_MAX_LENGTH]> packageIds(count);

        XStoreDownloadAndInstallPackagesResult(asyncBlockInner, count, packageIds.data());

        for(auto packageId : packageIds)
        {
            hr = XPackageCreateInstallationMonitor(
                packageId,  
                0,  
                nullptr,  
                1000,  
                m_asyncQueue,
                &m_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);

                // Persist callbackToken to unregister upon completion
            }
        }

        delete asyncBlockInner;
    }

    const char* storeIds[] =  
    {
        "9PLNMXRKNM4C",  
        "9PLNMXRKNM5D"
    };

    HRESULT hr = XStoreDownloadAndInstallPackagesAsync(storeContext, storeIds, ARRAYSIZE(storeIds), async);

    if (FAILED(hr))
    {
        delete async;
        return;
    }
}

枚举 DLC 包

无论 DLC 以何种方式安装，游戏在使用之前都需要枚举已安装的 DLC。枚举已安装的 DLC 是获取包标识符的地方。

bool CALLBACK DlcCallback(void* context, const XPackageDetails* details)
{
    printf("DLC found: name: %s packageId: %s\n", details->displayName, details->packageIdentifier);

    return true;
}

void RefreshInstalledPackages()
{
    HRESULT hr = XPackageEnumeratePackages(
        XPackageKind::Content,  
        XPackageEnumerationScope::ThisAndRelated,  
        this,  
        DlcCallback);
}

检测 DLC 包已安装

void RegisterPackageInstalledEvent()
{
    XPackageRegisterPackageInstalled(
        m_asyncQueue,
        this,  
        [](void *context, const XPackageDetails *package)
        {
            printf("Package Installed event received: %s\n", package->displayName);
        },  
        &m_packageInstallToken);
}

如果代码示例未被触及，请参阅故障排除部分。无论 DLC 包通过哪种方法安装，事件都应被触发。

获取 DLC 的许可证

在开发阶段，请参阅在开发中测试 DLC 授权中的注意事项。基础游戏需要为 DLC 获取许可证，以决定是否应向用户提供其内容的访问权限。游戏通常使用限制式授权 (Restrictive Licensing)：在游戏获取包的许可证后，对该包的访问将锁定到该设备和产品的该实例上。游戏必须释放该许可证，另一个实例或设备才能获得访问权和许可证。请与你的 Microsoft 客户代表沟通，以确保你的游戏被配置为使用限制式授权（不在合作伙伴中心中配置）。有关更多信息，请参阅开放式与限制式授权。由于游戏必须释放许可证，因此游戏负责跟踪它获取的所有 DLC 许可证，并在不再需要时或终止时释放它们。如果游戏未能释放许可证，则会在超时期后自动释放该许可证。

void CALLBACK AcquireLicenseForPackageCallback(XAsyncBlock* async)
{
    XStoreLicenseHandle licenseHandle = nullptr;

    HRESULT hr = XStoreAcquireLicenseForPackageResult(
        async,
        &licenseHandle);

    if (FAILED(hr))
    {
        printf("Failed retrieve the license handle: 0x%x\n", hr);
        return;
    }

    bool isValid = XStoreIsLicenseValid(licenseHandle);

    printf("isValid: %s\n", isValid ? "true" : "false");

    hr = XStoreRegisterPackageLicenseLost(licenseHandle, m_asyncQueue, context,
       [](void *context)  
       {
           // Check if the license lost corresponded to any mounted DLC
           // If so, it is up to the game to determine an appropriate time
           // to unmount the DLC, e.g. after the current match is completed
       });

    delete async;
}

void AcquireLicenseForPackage(const char* packageIdentifier)
{
    auto async = new XAsyncBlock{};
    async->context = this;
    async->queue = m_asyncQueue;
    async->callback = AcquireLicenseForPackageCallback;

    HRESULT hr = XStoreAcquireLicenseForPackageAsync(
        m_storeContext,
        packageIdentifier,
        async);

    if (FAILED(hr))
    {
        delete async;
        return;
    }
}

确定 DLC 的许可证来源

使用 XStoreCanAcquireLicenseForPackageAsync 或 XStoreCanAcquireLicenseForStoreIdAsync（取决于标识符类型），可以判断 DLC 是否：

可授权，以便在不可授权时呈现购买选项
通过光盘或数字许可证进行授权

void PreviewLicense(const char* storeId)
{
    auto async = new XAsyncBlock{};
    async->queue = m_asyncQueue;
    async->callback = [](XAsyncBlock* async)
    {
        XStoreCanAcquireLicenseResult result;

        HRESULT hr = XStoreCanAcquireLicenseForStoreIdResult(
            async,
            &result);

        if (FAILED(hr))
        {
            printf("Error calling XStoreCanAcquireLicenseForStoreIdResult: 0x%x\n", hr);
        }
        else
        {
            // Status = 1 Licensable and
            // a. licensableSku = "DISC" if disc licensed
            // b. licensableSku = "0010" or similar if digital licensed
            printf("Status: %u LicensableSku: %s\n", result.status, result.licensableSku);
        }

        delete async;
    };

    HRESULT hr = XStoreCanAcquireLicenseForStoreIdAsync(
        m_xStoreContext,
        storeId,
        async);

    if (FAILED(hr))
    {
        delete async;

        printf("Error calling XStoreCanAcquireLicenseForStoreIdAsync: 0x%x", hr);
        return;
    }
}

挂载和卸载 DLC

一旦成功获取 DLC 许可证，就可以挂载并访问 DLC 内容。

void CALLBACK MountPackageCallback(XAsyncBlock* async)
{
    XPackageMountHandle mountHandle = {};

    HRESULT hr = XPackageMountWithUiResult(async, &mountHandle);

    if (SUCCEEDED(hr))
    {
        // Access DLC goodness
    }
    else
    {
        XStoreCloseLicenseHandle(license);
        printf("Error mounting package: 0x%x\n", hr);
    }

    delete async;
};

void MountPackage(const char* packageIdentifier)
{
    auto async = new XAsyncBlock{};
    async->queue = m_asyncQueue;
    async->context = context;
    async->callback = MountPackageCallback;

    HRESULT hr = XPackageMountWithUiAsync(packageIdentifier, async);

    if (FAILED(hr))
    {
        printf("XPackageMountWithUiAsync failed : 0x%x\n", hr);
        delete async;
    }
}

卸载时，请释放所有令牌和句柄：

void UnmountPackage(XPackageMountHandle mountHandle, XStoreLicenseHandle license, XTaskQueueRegistrationToken licenseLostToken)
{
    XStoreUnregisterPackageLicenseLost(license, licenseLostToken, false);

    XPackageCloseMountHandle(mountHandle);

    XStoreCloseLicenseHandle(license);
}

卸载 DLC

使用 XPackageUninstallPackage 卸载 DLC 包。必须先卸载挂载。

Smart Delivery 与 DLC

XBOX Series X/S 游戏可以授权并挂载为 XBOX One 游戏创建的 DLC。通常，这种情况发生在 DLC 包不包含游戏使用的数据时。唯一的检查方法是查看 ERA DLC 的 package.appxmanifest 中的 AllowedProduct ID（一个 GUID）是否与在合作伙伴中心分配给该产品的 Legacy XBOX Product ID 相匹配。如果不匹配，则该游戏可能是从已停用的 XBOX Developer Portal (XDP) 迁移而来，并且只能与从商店下载的包一起使用，因为 XBOX Series X/S 版本被分配到 XBOX One 的 product ID。出于开发目的，请参阅故障排除部分中的说明。

来自不同产品的 DLC

可以枚举并使用来自不同产品的 DLC。对于希望使用来自不同产品的 DLC 的游戏，请在合作伙伴中心的 产品关系设置 (Product relationship setup) 部分为该 DLC 产品分配 “Can sell and use” 关系。可选的产品仅限于发行商账户。

在开发中测试 DLC 授权

有关更多信息，请参阅启用授权测试。本地 DLC 包必须使用 /contentid 参数创建。每个 DLC 包的 EKBID 都必须相对于默认值被覆盖。

参考 API 文档

另请参阅

商务概述启用授权测试如何使用无包的耐用品 XStore API 参考

XBOX publishing overviews

Partner Center features

XStore commerce

Game setup tutorials

XBOX Certification

XBOX Certification submissions

XBOX resources and terminology

Partner Center how-to guides

Microsoft Store Policies and Code of Conduct

DLC 的开发工作流程

1. Loose DLC 部署

2. 本地安装 DLC 包

3. 从商店安装 DLC 包

验证 DLC 安装

购买并安装 DLC

枚举 DLC 包

检测 DLC 包已安装

获取 DLC 的许可证

确定 DLC 的许可证来源

挂载和卸载 DLC

卸载 DLC

Smart Delivery 与 DLC

来自不同产品的 DLC

在开发中测试 DLC 授权

参考 API 文档

另请参阅

​DLC 的开发工作流程

​1. Loose DLC 部署

​2. 本地安装 DLC 包

​3. 从商店安装 DLC 包

​验证 DLC 安装

​购买并安装 DLC

​枚举 DLC 包

​检测 DLC 包已安装

​获取 DLC 的许可证

​确定 DLC 的许可证来源

​挂载和卸载 DLC

​卸载 DLC

​Smart Delivery 与 DLC

​来自不同产品的 DLC

​在开发中测试 DLC 授权

​参考 API 文档

​另请参阅

DLC 的开发工作流程

1. Loose DLC 部署

2. 本地安装 DLC 包

3. 从商店安装 DLC 包

验证 DLC 安装

购买并安装 DLC

枚举 DLC 包

检测 DLC 包已安装

获取 DLC 的许可证

确定 DLC 的许可证来源

挂载和卸载 DLC

卸载 DLC

Smart Delivery 与 DLC

来自不同产品的 DLC

在开发中测试 DLC 授权

参考 API 文档

另请参阅