Using ComparePackage to understand version differences and user impacts

ComparePackage is a new Windows 10 SDK (ver 10.0.15003.1001) tool that analyzes the differences between versions of your UWP app packages and helps you estimate what the update impact of the new version will be to users. This guide will cover how to get started using the tool and how to interpret its output.

Preparation

Make sure you have the Windows SDK (which can be acquired here if you don’t already have it) and find the previous version of your package. ComparePackage supports UWP packages of .appx, .appxbundle, .eappx, and .eappxbundle (and alternatively it also supports AppxBlockMap.xml as inputs). Both versions of your package must be the same type, so pack the current version of your app to the same package form as your previous version.

For interpreting ComparePackage’s output, it will also be helpful to understand how UWP app updates work if you don’t already. More information on this can be found in this blog post.

Usage

ComparePackage takes the locations of your old package and new package in this order as inputs.

 C:\>ComparePackage AppInstaller_1.0.12.0_x86.appx AppInstaller_1.0.38.0_x86.appx

If you want an XML version of the output for further processing, you can use the “-xml” flag and provide a location and name to save the .xml file. The console output lists all the differences between the two versions and should be sufficient for most cases, but the XML version has more granular data if you need it.

(If you are running into an error and unsure of how to fix it, try using the “-v” flag for verbose error output to help you determine what’s causing the error. The verbose flag will have no effect if there are no errors.)

Interpretation

Here’s the output from running the command above for the App Installer.

Since the App Installer is an .appx, there is only 1 super section in the output (marked by the “=” separators). For an .appxbundle, each individual package within (architectures and resources) would have its own super section, and since resources can be added or deleted, these changes would be listed separately at the top. Within each super section is the summary, changed files, added files, deleted files, and duplicate files.

For changed files, they are ranked by the most impact first . Impact is how much this particular file will contribute to a user’s update download size in bytes. And size difference is the file size change in bytes.

Taking a look at the second ranked changed file, “Assets\SplashScreen.scale-200.png”, we can see that this file has a positive impact, but a negative size change. This is because this particular image file had a decrease in size overall, but also had new bits that were not in the old image. So for example, if this image file can be represented by blocks ABCDE in the old version, and blocks ABCF in the new version, then block F is “new” in the new version and must be downloaded during the update (thus having positive impact), but overall the image now has 1 less block than before (thus having negative size difference).

By looking at both impact and size difference, we can determine whether any packaging changes are inconsistent with the actual changes you made to the project. So if I know that there were minimal code changes to the App Installer but the .exe file is showing up as having the most impact, then some unintentional changes must have taken placed that I should look into.

For added files, since these files are new, they will be downloaded during a user’s update, so the entirety of the added files will show up as impact (byte differences between impact and size can be attributed to compression of the files if any).

The opposite is true for deleted files; since these files no longer exist in the new version, nothing will be downloaded for them during update, so they’re impacts will be 0.

The duplicate files section looks at only the new version of the package to determine if there are duplicate files within it. This section is helpful to see where optimizations can be made to the package to decrease the update impact to users. As you can see here for the App Installer, there are multiple duplicate image assets, so these should be cleaned up before we officially submit the new version.

ComparePackage should be a tool you use before you submit updates for your apps. It analyzes the previous and current versions of your app to estimate the update impact to users and to help you determine whether unintentional changes were made and how to further optimize the update. ComparePackage should enable you to be confident in your update.