Developing for Modern Windows

Tips, tricks, and guides for developing on modern Windows platforms

UWP on XBox Tips and Tricks

By now you will be aware that Microsoft is now allowing UWP apps into the XBox One store. As great as UWP is, you still need to do some work to get an app working well on the XBox console. I have been working on creating an XBox version of one of my apps, and found it quite difficult to get all the information I needed, so I’ve collected some tips that will help anyone wanting to develop UWP apps for the XBox One.

So in no particular order, here are the tips!

 

Tip #1: Microsoft’s UWP on XBox Page

A lot of the information in this post is from the following link. Microsoft will presumably update this page whenever things change, so it’s a good page to bookmark.

https://msdn.microsoft.com/en-us/windows/uwp/xbox-apps/index

Tip #2: Setup your XBox One Console

Any retail XBox One can be used for testing your UWP apps. To deploy a UWP app to an XBox, the XBox needs to be put in a special developer mode (while in this mode you cannot access your usual games and apps, and will need to exit dev mode to get to your games and apps).

The following link has the detailed steps:

https://msdn.microsoft.com/en-us/windows/uwp/xbox-apps/devkit-activation#activate-developer-mode-on-your-retail-xbox-one-console

In a nutshell, you install the Dev Mode Activation app and run it. You’ll get a code that you need to use in Visual Studio to pair with the XBox. The Dev Mode Activation app will reboot your XBox into dev mode, and from there you will be able to deploy and debug UWP.

To return your XBox to retail mode (so you can play your games and apps), you can exit dev mode and reboot from the Dev Home app.

NOTE: By default, your apps are uninstalled when you leave dev mode. Remember to untick the checkbox when leaving dev mode if you want to leave your apps on your console for the next time you go to dev mode (you can’t use your apps in retail mode).

Tip #3: Detect when your UWP App is Running on an XBox One

You may want to treat XBox a bit differently in your apps. To detect if your app is running on an XBox, you can use the following code:

public static bool RunningOnXbox
{
     get
     {
        return AnalyticsInfo.VersionInfo.DeviceFamily.ToLower().Contains("xbox");
     }
}

 

I put this static bool property in App.xaml.cs, and therefore I can access it from anywhere like this:

if(App.RunningOnXbox)

{

    // do stuff

}

 

Tip #4: Create an XBox Build Configuration to Test on a PC

Deploying and testing on an XBox console can be tedious – it is quite slow, you usually have the XBox in another room, or someone is playing games or watching Netflix, etc. By creating a build configuration in your solution to emulate XBox, you can test the app on your PC with the appropriate XBox code running.

Visit this link for instructions: https://msdn.microsoft.com/en-us/library/kwybya3w.aspx

I created a build configuration called ‘DebugXbox’, and added a compilation symbol ‘XBOX’. Then I could conditionally compile code for XBox, like so:

public static bool RunningOnXbox
{
     get
     {
#if XBOX
         return true;
#endif
         return AnalyticsInfo.VersionInfo.DeviceFamily.ToLower().Contains("xbox");
     }
}

 

In the above example, RunningOnXbox will return true when I am using the DebugXbox configuration. This makes it easy to quickly debug.

NOTE: You still need to test on a real XBox, but use this technique for faster work.

 

Tip #5: Use the XBox XAML Designer Setting

Visual Studio’s XAML designer has an XBox One setting, which mimics the correct scaling.

The XBox One uses a  1920×1080 resolution, but with a scaling of 200%, and therefore an effective resolution of 960×540.

Choosing the XBox setting in the designer will make sure what you see in the designer matches the end result on your TV.

 

Tip #6: Disable the Mouse Cursor

By default, your XBox app will have an annoying mouse cursor that the user moves with the controller (like the one you see if you’ve ever used Edge on the console). For many apps this is not required, so you can remove it with a simple piece of code.

Put this code in the App.xaml constructor:

this.RequiresPointerMode = Windows.UI.Xaml.ApplicationRequiresPointerMode.WhenRequested;

If Visual Studio doesn’t recognise this code, you probably need to upgrade your Windows 10 SDK to the Anniversary Update version.

 

Tip #7: Use D3D for Unity Games

If you are building a Unity game for the XBox One, choose D3D instead of XAML when you build from Unity. This will eliminate the huge overscan border and mouse cursor from your game.

 

Tip #8: Disable the Huge Overscan Area

By default, your XAML XBox UWP app will have a very large overscan area (to account for TVs that are a bit ‘zoomed in’. You can disable this with the following code:

Windows.UI.ViewManagement.ApplicationView.GetForCurrentView().SetDesiredBoundsMode(Windows.UI.ViewManagement.ApplicationViewBoundsMode.UseCoreWindow);

But use this carefully, as you might get content cut off for some users with badly setup TVs.

 

Tip #9: [Bug] Case-Sensitive File Names

A bug has been identified in UWP on XBox. For some reason, when you access files, the filenames are returned all in lowercase. This ‘MyAppData.XML’ is returned as ‘myappdata.xml’. Keep this in mind when dealing with files. The simplest workaround is to use all lowercase for any filenames, but to accommodate the bug in my app I added some code to take into account the different filenames on XBox. If you’re carefully handling your filenames you may not encounter this bug.

 

Tip #10: Connect an XBox Controller to your Development PC

You need to make sure your XBox apps work with a controller. When testing on your PC, you will benefit from connecting an XBox controller. You can buy a spare controller (an old XBox 360 controller will do), or you can connect an XBox One controller via a USB cable. Newer controllers have Bluetooth, which can connect to a PC.

 

Tip #11: Access Click Events to Detect XBox Button Taps

After a lot of frustration, I found that XBox controller buttons send the ‘Click’ event to the UI, not the Tapped event, which I was using for mouse and touch. So for all UI that needs to be activated with XBox buttons, make sure you add the Click event.

 

Tip #12: Publishing on XBox

You need to opt-in to XBox publication via Dev Center (it’s in the package management part of the submission process). If you are not able to select the XBox option for your package you probably need to change the Windows 10 version target to a higher version (e.g. the Anniversary Update).

Also note: you can’t publish UWP games for the XBox One without going through Microsoft’s ID@Xbox program, unfortunately. This is probably to ensure that Microsoft maintains high standards for games available on the XBox. You can still deploy and test your own games, of course.

Also note that Microsoft is apparently holding XBox apps to a higher standard than for Windows and phone. Make sure your app is polished.

 

Tip #13: Missing UWP Features

UWP on XBox has a few pieces of missing functionality. These are listed here: https://msdn.microsoft.com/library/windows/apps/mt693377 . Be sure your functionality is supported before spending time working on your app.

Leave a Reply

Your email address will not be published.