On demand resource packages

Resource packages offers a great way to reduce users disk footprint by segmenting language or scale specific asset into separate packages that are downloaded automatically by Windows depending on the users machine configuration. If the user adds a new language to his/ her list of OS languages in Region & language settings or changes the display configuration, across an automatic store update, the OS will fetch applicable resource packages for all installed apps on the device.

We received feedback from a number of developers that while the automatic install of resource packages is a great feature, they would like to acquire resource packages from within their app to light up some scenarios. For example a gamer that wants to download Japanese asset package just for that game but does not want to add Japanese as a OS language. Another example is a customer that is using a language learning app and wants to download new language learning material which is part of a language package, without adding this new language as his/ her OS language.

We are excited to announce that with SDK 10.0.17095.0, AddResourcePackageAsync API will allow developers to install a resource package for an app on demand!

How to use the API?

• AddResourcePackageAsync takes the PackageFamilyName of the application as well as the resource ID that uniquely identifies the resource package that you are trying to download. The resource ID corresponds to the ResourceId element in the AppxManifest.xml of your resource package. You can also find this information in your application's AppxBundleManifest.xml which describes all the packages that make up your .appxbundle package.
• Your application must be restarted to get a merged view of all resources that are available to your application, so the API offers the 'ForceTargetApplicationShutdown' option that you can pass to restart your application.
• If there is an update available for your application when you are trying to download the resource package, the API will fail as the older version of the app is no longer available. By passing in the 'ApplyUpdateIfAvailable' flag, the API will update the app as well as get the requested resource package as part of the same download!
• The API returns a progress for the download that you can display in your application. Also note that for Windows store applications, the resource package acquisition shows up in the Microsoft Store 'downloads and updates' page and shows up as an update to your application. The end user can choose to pause or cancel the download of the resource package from the Microsoft Store UX.

Here is a code snippet to explain the usage

 private async void DownloadGermanResourcePackage(object sender, RoutedEventArgs e)
{            
    // ResourceId that is unique to the resource package
    string resourceId = "split.language-de";
    // Warn user that application will need to restart.
    // To take update if available pass in the ApplyUpdateIfAvailable flag
    var packageCatalog = PackageCatalog.OpenForCurrentPackage();
    PackageCatalogAddResourcePackageResult result = await packageCatalog.AddResourcePackageAsync("29270depappf.CaffeMacchiato_gah1vdar1nn7a", resourceId, 
        AddResourcePackageOptions.ApplyUpdateIfAvailable | AddResourcePackageOptions.ForceTargetApplicationShutdown)
        .AsTask<PackageCatalogAddResourcePackageResult, PackageInstallProgress>(new Progress
        (progress =>;
        {
                // Draw progress
        }));

        if (result.ExtendedError != null)
        {
                //Display error or retry if needed
        }
}

Development Workflow

The API works for both Store installed as well as sideloaded applications. As a developer for local validation, you can create an .appxbundle (contains the main app + resource packages) and sideload this from your local drive, network share or webserver. When your app calls the AddResourcePackageAsync API, Windows will  acquire the resource package from the location where the original application was installed. This makes the validation simple. Once this works, you can proceed to submit your application to the Windows Store and without any code changes, the API will now fetch the resource packages from the Windows Store!

Removing resource packages

Normally resource packages that are acquired by the application or downloaded by the OS remain on the device until the application is uninstalled. However the App can choose to remove the resource package(s) it downloaded via the RemoveResourcePackageAsync API. You cannot remove a resource package that is applicable for the user or the device as a whole. For example, if French is an OS language for the user or the device, you cannot remove the French resource package using this API.

Here is a code snippet that shows the usage.

 private async void RemoveResourcePackage(object sender, RoutedEventArgs e)
{            
    var packageCatalog = PackageCatalog.OpenForCurrentPackage();
    List resourcePackagesToRemove = new List();
    resourcePackagesToRemove.Add("split.language-de");
    //Warn user that application will be restarted
    var removePackageResult = await packageCatalog.RemoveResourcePackagesAsync(resourcePackagesToRemove);
    if (removePackageResult.ExtendedError != null)
    {
        // display error
    }
}

Let us know what you think!

Cheers,
Sandeep George
Senior Program Manager