Creating, examining, and testing content updates

Overview

The document covers how content updates are delivered, the tools that are used to generate and measure updates, and details on how to test key update scenarios to ensure expected and optimal behaviour.

How content updates work

Gaming services will always minimize the number of bytes that need to be transferred when you provide an update to game packages, both to customers on gaming devices, and from developers when packages are uploaded. This difference ("delta") is computed using algorithms that, at a high level, attempts to maximize the matches of 4KiB segments between two packages.

This delta is encoded as part of .xsp (update streaming plan) files that are used by the system to know exactly what bytes need to be downloaded from the network and how to apply them to any possible existing package version.

Therefore, in order to simulate and test accurate delta update behaviour in development, the proper makepkg options must be used to create packages, and using the proper commands to install and update packages must be used.

Create an update based on a previous package version

makepkg pack is used to create packages. In order to create a package that utilizes a previous package, use the /priorpackage parameter:

makepkg pack /f chunks_layout.xml /d [build directory] /pd .\output /priorpackage [previous version].xvc

The previous package must share the same package identity as the package being created, as defined in the microsoftgame.config.

The result of this command is an .xsp file with the name [new package name]_update-[old version number].[guid].xsp, e.g. 41336MicrosoftATG.ATGGameHubRequiredGame_200.0.0.0_neutral__dspnxghe87tn0_xs_update-100.0.0.0.5890f4a0-b449-4c5d-80ff-b78b19ed3439.xsp

This is the streaming plan that encodes what needs to be changed when updating from the old to the new package. How this is used will be demonstrated below in the section on testing updates.

Examine update size

When the above command is run, some additional files are generated with the same filename: an .html file and a .json file.

Both will contain the following:

1. A summary of the bytes that will be downloaded as part of the update
2. A table that summarizes the amount of data that would be installed given a specific tag, language, or device type
3. A sortable table of files that shows the amount of the bytes that will be updated and the percentage of the overall file size this represents
4. For each file that is not 100% updated, this is linked to individual tables that show the ranges of data in each file that are updated.

With this information, it is possible to identify which files are the most changed in an update, and to look at the individual files to see if the proportion and location of changes are as expected. If files are seen that seem to result in a bigger update than usual, review the guidelines found in the Authoring updates efficientlyAuthorization required section.

packageutil compare on the two .xvc files will also generate these same files and provide a summary output of the package differences; this command will also generate 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:

1. xbapp install [old version.xvc]
2. xbapp update [new version.xvc] (/plan=[.xsp file])

When updating, go to the Queue in the system UI to see the friendly number of bytes that is being updated.

The /plan parameter is optional if the .xsp has been previously generated by other commands and is in the same location as the .xvc files.

On PC, the 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 does not support the /plan parameter, it will use the .xsp file generated for the target version if one was created.

Advertising updates

Advertising updates is slightly different in that you are making an update available to the game, which results in specific system behaviour.

To advertise an available update, apply the /m or /a flag to xbapp/wdapp update. This will result in the update not being applied until the game is launched. When this happens:

• Console: a system dialog will show stating an update is required
• PC: for dev builds, no system prompt will show, and the build can freely be launched, unless the build is installed with wdapp install /bootstrapper. In this case, launching the game will invoke the PC bootstrapper, which will find and prompt for update.

Advertising the update will also result in certain XStore API to react, allowing the game to also detect available updates; this is most relevant to DLC packages. See Checking for updates for more details.

Store package updates

The above examples involve installing and updating with local packages. It may be desired to test updating with packages that have been uploaded to Parter Center and downloaded from the Store CDN. This validates two things: performance when updating from the Store, and utilizing the streaming plan that is generated as part of the ingestion process.

Unfortunately, it is not possible to update from a local package to a Store package due to signing differences. What is possible, without additional help, is to upload one version (to Partner Center), install this version from the Store app onto one or more devkits. Upload the new version, then once published, on the devkits with the older version installed, verify that that the newer version is detected and can be updated with the expected delta size.

To be able to repeat this test, prior to updating, copy the old version installation to an external drive so it can be copied back over any new version later. If this was not saved, it is possible to request the CDN url from which an older version can be xbapp/wdapp installed. Contact your Microsoft representative for assistance. Once an older version is installed, the update test can be repeated.

Hybrid disc+CDN updates

Updates are also relevant for optical disc installations. When a disc installation happens, any disc contents that are unchanged relative to the latest available digital package will be installed from disc; the rest is concurrently installed from Store CDN. This happens automatically.

To simulate this, use the following command:

xbapp update http://server/[latest version].xvc /p:[disc package].xvc`

Serving the update package through an HTTP server is a workaround for the fact that an installation can only have one source from the development PC's local storage.

The disc package can point to the optical disc path if you have burned a test disc with the disc .xvc package.

See also

Content update best practicesAuthorization required

Checking for updates