Loose File Deployed Stream-able App
A stream-able app can still be deployed as loose files (or F5 from Visual Studio). By default, all files are present and all content groups are staged. Through the debugging APIs, we can set the states of the content groups so that we can simulate environments where only certain content groups are present and test how apps behave. These APIs are designed to be used from outside of the targeted app and can only be used on a loose file deployed app. An AppxContentGroupMap.xml must be present when the app is registered in order for the APIs to work.
Instead of writing your own debugging app, you can also download and build our debugging app that implements these APIs. To use the debugging app, you can download the project and F5 from Visual Studio (or create a package and sideload yourself).
Using the Debugging APIs
Pre-requisites for Debugging APIs
To start using the debugging APIs, your debugging app must declare the packageManagement restricted capability (read more here). If you are working in Visual Studio, you can right click on your Package.appxmanifest -> Open with -> XML Editor and add
to <Package> and add
<rescap:Capability Name="packageManagement" />
Using the APIs, we can set “Level2” content group as NotStaged by:
var pm = new PackageManger(); var debug = pm.DebugSettings; var package = FindPackage(); //find your loose file stream-able app debug.SetContentGroupStateAsync(package, "Level2", PackageContentGroupState.NotStaged);
This will immediately set the state of the “Level2” content group state as NotStaged, even while the app is running. Setting the state of the content group doesn’t mean that the content group’s files are deleted (files in the “Level2” content group are still present and accessible), but when the app checks the state of the content group through GetContentGroupAsync, the app will get back whatever state was set using the debugging APIs (in this case, the app will get back NotStaged, making those “Level2” files inaccessible if all file access are preceded by the content group check).
We can also simulate the download of a content group using the APIs by:
debug.SetContentGroupStateAsync(package, "Level2", PackageContentGroupState.Staging, 50);
This will fire off the notification that the “Level2” content group has downloaded up to 50% (progress events only fire off per integer percentage here and in the real streaming install). And through setting the download percentages, you should be able to test and see how your download progress UI behaves.
Using the Streaming Install Debugging App
You need to first loose file deploy the stream-able app you’re testing. You can do this by F5ing from Visual Studio or from PowerShell:
Add-AppxPackage –Register C:\myapp\AppxManifest.xml
Where “C:\myapp\” is the directory where the app’s files are (not the package).
Then, after launching the debugging app, you should see the stream-able app you just deployed and its content groups in the “Content Group” list. By default, the debugging app will only show stream-able development mode packages in the “Stream-able Apps” list and will select the most recently deployed app. If you deployed your stream-able app after the debugging app has been launched, you can trigger another scan for apps clicking “Find Apps”.
To set a content group’s state, you can select a content group from the “Content Group”, set its “New State” (and the “Staging Percentage” if the state is Staging), and click on “Set Content Group State” to commit that change to the system to simulate how your app behaves when it is being streaming installed.
Also as a note, if you have deployed a stream-able app as loose files and go into the Settings app and clicked "Reset" for this app, the app will no longer see any information related to the automatic content groups. This behavior will not appear for stream-able apps deployed as packages or from the Store. You can just uninstall then redeploy the app to fix this if you accidently clicked "Reset" on it.
Sideloaded Stream-able App
A stream-able app can be sideloaded as a package with just the required content group installed. You can do this in PowerShell by:
Add-AppxPackage –Path C:\myapp.appx –RequiredContentGroupOnly
The –RequiredContentGroupOnly is the flag that will only stage the required content group. After the app has been installed, you can launch the app, walk through the minimal experience, and also attach a debugger.
With the debugger attached, you can install the automatic content groups by:
Add-AppxPackage –Path C:\myapp.appx
Which is the exact same command but without the flag (what happens is that the platform will see that the app is already installed and will only stage the files that are missing). If you are installing your app from a remote share (to mimic an actual streaming install from the Store), you can throttle your network during the install of the automatic content groups in order to make the staging go slower so that you can test if your app is properly displaying the correct UI and reprioritizing the correct content groups.
Follow the links below for more detailed information on building apps with streaming installation:
- Streaming Install Part 1: UWP Streaming App Installation Overview
- Streaming Install Part 2: Content Group Maps Overview
- Streaming Install Part 3: Content Group Maps Deep Dive
- Streaming Install Part 4: Support Streaming Install in the App
- Streaming Install Part 5: Testing and Debugging a Stream-able App
<more links coming soon>
Questions? Ask in the comments section below.
Andy Liu, Program Manager, Windows Developer Platform