Overview
This article explains how to deliver content updates, the tools you use to generate and measure updates, and how to test key update scenarios to ensure expected and optimal behavior.How content updates work
Gaming services always minimize the number of bytes that need to be transferred when you provide an update to game packages. This optimization applies to both customers on gaming devices and developers when uploading packages. The system computes this difference (delta) by using algorithms that, at a high level, attempt to maximize the matches of 4-KiB segments between two packages. The system encodes this delta as part of.xsp (update streaming plan) files. By using these files, the system knows exactly what bytes to download from the network and how to apply them to any possible existing package version.
To simulate and test accurate delta update behavior in development, use the proper makepkg options to create packages. Also, use the proper commands to install and update packages.
Create an update based on a previous package version
Usemakepkg pack to create packages. To create a package that uses a previous package, use the /priorpackage parameter:
[new package name]_update-[old version number].[guid].xsp. For example, 41336MicrosoftATG.ATGGameHubRequiredGame_200.0.0.0_neutral__dspnxghe87tn0_xs_update-100.0.0.0.5890f4a0-b449-4c5d-80ff-b78b19ed3439.xsp
This file is the streaming plan that encodes what needs to change when updating from the old to the new package. The section on testing updates demonstrates how to use this plan.
Examine update size
When you run the preceding command, it generates two additional files with the same filename: an .html file and a .json file. Both files contain the following information:- A summary of the bytes that the update downloads
- A table that summarizes the amount of data that the update installs for a specific tag, language, or device type
- A sortable table of files that shows the number of bytes the update changes and the percentage of the overall file size this change represents
- For each file that isn’t 100% updated, links to individual tables that show the ranges of data in each file that the update changes
packageutil compare on the two .xvc files also generates these same files and provides a summary output of the package differences. This command also generates the .xsp file.
Delta uploads
Uploads to Partner Center will automatically take advantage of the delta computation algorithms. The delta between your last uploaded package (for that branch) and the uploading package is computed at the beginning so that only the changed data will be transferred from the upload machine to the ingestion service.Testing updates
To validate the update size as seen in the system UI, perform the following steps:xbapp install[old version.xvc]xbapp update[new version.xvc] (/plan=[.xsp file])
wdapp command is used instead. Package files have the .msixvc file extension, and installation and update progress can be seen in the download queue section in both the XBOX app and Microsoft Store app. wdapp update doesn’t support the /plan parameter. It uses the .xsp file generated for the target version if one was created.
Advertising updates
Advertising updates is slightly different from other update methods. When you advertise an update, you make the update available to the game, which results in specific system behavior. To advertise an available update, apply the/m or /a flag to xbapp or wdapp update. This action results in the update not being applied until the game is launched. When this condition happens:
- Console: a system dialog shows stating an update is required.
- PC: for dev builds, no system prompt shows, and the build can freely be launched, unless the build is installed by using
wdapp installor the bootstrapper. In this case, launching the game invokes the PC bootstrapper, which checks for and prompts you to install updates.
XStore APIs to react, which allows the game to detect available updates. This behavior is most relevant to DLC packages. For more information, see Checking for updates.
Store package updates
The preceding examples involve installing and updating by using local packages. In some scenarios, you might want to test updates by using packages that you uploaded to Partner Center and downloaded from the Store CDN. This process validates two things: performance when updating from the Store, and utilizing the streaming plan that is generated as part of the ingestion process. Unfortunately, you can’t update from a local package to a Store package due to signing differences. What you can do, without other help, is upload a single version to Partner Center and then install that version from the Store app on one or more devkits. Then, upload the new version. When the new version is published, on the devkits with the older version installed, verify that the newer version is detected and can be updated by using the expected delta size. To repeat this test, before updating, copy the old version installation to an external drive so you can copy it back over any new version later. If you didn’t save this version, you can request the CDN URL from which an older version can be installed by usingxbapp install or wdapp install. After you install an older version, you can repeat the update test.