Tips and Tricks for Building for UWP and deploying to Xbox One

Update #1: Info on the new Xbox Dev Mode Companion (preview) app


We’ve been having some fun talking about the new ability to deploy a UWP app to Xbox One in the General Discussion forum.

@TheLorax asked for some help with the deployment steps so I’m starting this thread in what I believe is the appropriate support forum so I can provide some assistance.

I hope this post is useful. I will try to update it as the deploy process changes.

If something is unclear, or you have a follow-up question, please let me know.

First, the preliminaries. You will need:

  • A Dev PC running the latest build of (and updates for) Windows 10.

  • Visual Studio 2015 Update 2 with the latest version of the UWP SDK.

  • A Windows Dev Center Account. This is now a one time charge of approximately $19 USD. The price and terms may vary in your region. (Thanks @Steve-Tack )

  • An Xbox One.

  • Officially, the Xbox One and Dev PC need to be on a wired network. Unofficially, I did a test and was able to successfully deploy an app via WiFi. YMMV.

  • Install and run the “Dev Mode Activation” app on your Xbox One via the App Store.


    You will get an activation code that you need to enter in your Dev Center Account Portal.

    Once the code has been accepted, you exit the Dev Mode Activation app on your Xbox One and it will automatically start downloading and installing the “Insider” build of the Xbox One OS. When finished it will reboot into “Dev” mode.

  • After the Xbox One reboots, you will be prompted to sign into Xbox Live. Then, enter the “Dev Home” app you will see on the right side of the Home screen.

  • I’m not sure what minimum version of Unity is needed. I’ve done all my testing with Unity 5.3.4p1.

  • When you install Unity, you need to include the “Windows Store .NET Scripting Backend” component. (Thanks @tapticc )

  • The Known issues with UWP on Xbox One developer preview and System resources for UWP apps and games on Xbox One pages are both worth reading.

  • A note for those who have an actual XBox One Dev Kit (instead of a retail unit), you do not have to have the XDK installed on your PC to deploy UWP to your dev kit, but if you do, make sure it is the latest version. Older versions of the XDK have known deployment issues, especially with the il2cpp scripting backend. (Thanks @Snowed-In )

Ok, here’s how you build for UWP and deploy to Xbox One:

  • Create a project in Unity. Start with something simple. For the purposes of this write up I imported the free Particle Callbacks demo (via the asset store) into an empty project. I had to make a few, very minor, code tweaks to get it to run in Unity 5. Use one of the updated Unity 5.x demo assets if you want something that will work without tweaking. Or just create a simple “Hello World” type project. I also imported the Advanced FPS Counter asset because I like the device and memory status info it displays. Don’t worry if you don’t own this asset, it’s not required for a successful build. Note that the file path of your Unity project cannot have an ampersand. You will not be able to open your UWP project successfully if your Unity project has an ampersand in the file path. (Thanks @tapticc )

  • In Unity, go to File>Build Settings.
    2577904--180026--Unity Build Settings Screen.gif

(continued below so I can post more pictures)

4 Likes
  1. Select “Windows Store” in the “Platform” section. Click “Switch Platform”, wait for it to finish processing, then click “Player Settings…”

  2. In the “Publishing Settings” group, make sure you have a certificate specified. If not, click the “Create…” button to make one.

  3. Back to the Build Settings. Choose “Universal 10”. The other settings are documented elsewhere, you can use the settings in my screenshot (in the above post) to test the deploy process, then go back and research them to better understand your needs.

  4. Once you have the settings configured, click the “Build” button. You will be asked to select a folder. Once you do, the build will start and a Visual Studio Solution will be created in the indicated path. Note that the file path where your save your Build cannot have an ampersand. You will not be able to open your Build in Visual Studio if you have an ampersand in the file path of where you save your Build. (Thanks @tapticc )

  5. Start Visual Studio 2015 Update 2 and drag the .sln file over it to open the Solution (Or use “File>Open Project/Solution”).
    2577905--180028--A completed UWP Build.gif

  6. You will probably see a bunch of warnings and maybe a few errors after you first open the Solution. You can ignore them for now.

  7. (Optional) I like to do a test local deployment first. On the Standard toolbar, change the target to “Local Machine”, the configuration to “Master” and the platform to x64.
    2577905--180030--configuration for local test.gif

  8. (Important) Whenever you change the build settings, you need to “clean” the Solution. Select “Build>Clean Solution” or right click the Solution in “Solution Explorer” and select “Clean Solution”.

(continued below so I can post more pictures)

4 Likes
  1. If you do not clean the solution you will most likely get errors when you compile.

  2. Use CTRL+F5 to start the project without debugging. The compile will take a few moments, You will see errors and warnings change as each project in the Solution compiles. If everything works correctly, you will see the game running in a Window.

  3. Close the running game.

  4. Change the build target to “Remote Machine”. You will be asked to specify a remote connection. I use the IP address that my router assigned to my Xbox One but you can probably enter “XboxOne” for the address, which is the default hostname set in the Dev Home app on your Xbox One. If you have more than one Xbox One, you should change the hostname for one of them.
    2577912--180034--remote connection properties.gif

  5. Clean the solution again!

  6. Use CTRL+F5 to rebuild and deploy the project without debugging. The compile stage will take a few moments. As it starts the deploy stage, if this is the first time you are deploying a UWP app to this Xbox One, you will be asked for a PIN code. On the Xbox One, in the Dev Home app, select “Pair with Visual Studio” to generate a PIN. Enter the PIN in Visual Studio. It took a few tries for me to get this right. Either I was mistyping the PIN or it was timing out. It worked after about 4 tries. You will only have to do this once.

(Sorry, I don’t have screenshots for this. It was a pain and I don’t want to redo it.)

  1. Once your Visual Studio installation is paired with your Xbox One, the app will continue to deploy (actually, sometimes you will have to start the process again but it will not ask to pair again). When finished deploying your app will automatically start running.

  2. That’s it. Enjoy!
    (continued so I can post more pictures)

5 Likes

Notes:

Troubleshooting:

  • When in doubt, clean your solution.
  • There is a known bug in the Dev Home app that will cause it to not show a correct list of your deployed apps. You can see and re-launch your deployed apps via the “My Stuff” app in the “Apps” section. Sometimes, your apps won’t launch. Try again. They will eventually.
  • I ran into an issue where none of my apps would successfully deploy. The deploy would always fail at the final step where it registers the app on the remote device. The Known Issue page (linked above, in the first post) suggests exiting Dev Mode, then rebooting into Dev Mode. This worked for me and allowed me to deploy apps again.
  • @stownend figured out an alternate deployment technique that seems to work around issues that some people have with deploying projects to their XboxOne. You can find his solution here.
1 Like

OR…

Create the Unity3D targeting Windows directly, use the win32 converter and you’re back to UWP ?

I think that converter is for targetting Windows PCs. I don’t think it will work for deployments to Xbox One.

The resulting app after the conversion will only work on desktop. The converter doesn’t magically make the program not call the APIs that are available on desktop only - it merely packages it up into an appx.

@schmosef : nice guide! Regarding the advice on cleaning solution: that shouldn’t be needed - I don’t ever do it. What kind of issues do you run into without cleaning it?

I get strange compile errors. It’s easy to reproduce. It happens every time I switch build settings. I switch build settings a lot because i have ARM based tablets and a phone, and remote touch screen PCs that I use for testing. The screenshot above shows an error that says multiple inheritance is not supported. It’s not always the same error. If i clean the solution, the compile error goes away. Maye this is a bug I should submit for review?

Yes please. I’d definitely consider it a bug. Include all the steps you do to build, which settings you change, etc - we’ll need it to be as detailed as possible to be able to reproduce it.

Ok, tomorrow I’ll write it up nicely and submit the Particle Callback demo project I used for the above guide. After I compiled and deployed locally in step 12, I could not compile and deploy remotely to the Xbox One without first cleaning the Solution in step 15.

Thanks.

@schmosef thanks for taking the time to document this, appreciated :slight_smile:

2 Likes

Just a quick tip if you get a message about WIndows Module Not Loaded or similar, I had to reinstall using the Windows Store .NET Scripting Backend ticked manually as this was not selected by default:

2 Likes

I have installed Visual Studio 2015 Release 2 and can create a new app on my Xbox following these instructions:

However when I open the Unity build project in Visual Studio, the project isn’t a Universal Windows project and the Project Properties window won’t appear to set it to remote (and no remote option on the Standard Toolbar)

Did you encounter this? No doubt I have missed something during setup, but the fact that a new Universal Windows solution in Visual Studio shows me the options makes me think I have installed all the pre-requisites

thanks :slight_smile:

Erm… oops I was opening the Unity solution file rather than the UWP Build solution file, both had the same name!

This is a good point.

Thanks for mentioning it.

I’ve updated the “preliminaries” section in my first post with this info.

1 Like

Did you have to install anything special to be able to build Master builds? I can build debug and release modes but get errors in Master mode.

1> Assembly-CSharp-firstpass → C:\Users\Craig\Desktop\Windows 10 UWP\UWP\Assembly-CSharp-firstpass\bin\x64\Master\Assembly-CSharp-firstpass.dll1>------ Build started: Project: Assembly-CSharp-firstpass, Configuration: Master x64 ------To prevent NuGet from restoring packages during build, open the Visual Studio Options dialog, click on the Package Manager node and uncheck 'Allow NuGet to download missing packages during build.'Restoring NuGet packages…Failed to resolve all project references for ‘Windows 10 UWP’. The package restore result for ‘C:\Users\Craig\Desktop\Windows 10 UWP\Build\Windows 10 UWP\Windows 10 UWP.csproj’ may be incomplete.



========== Deploy: 0 succeeded, 0 failed, 0 skipped ====================
Build: 2 succeeded, 1 failed, 0 up-to-date, 0 skipped ==========3>
C:\Program Files (x86)\MSBuild\Microsoft.NetNative\x64\ilc\IlcInternals.targets(887,5): error : Internal compiler error: Failed to parse 'UnityStandardAssets.Utility.DragRigidbody+d__8, Assembly-CSharp-firstpass, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null’3> Compiling interop code3> Generating serialization code3> Computing application closure and generating interop code3>C:\Program Files (x86)\MSBuild\Microsoft.NetNative\x64\ilc\IlcInternals.targets(887,5): warning : Invalid IL detected in method ‘System.Int64 UnityEngine.Internal.$MethodUtility.$Invoke2347(System.Int64, System.Int64*)’ at IL offset 0x12 referring to invalid Windows Runtime method ‘System.Void Windows.System.UserWatcher.remove_Updated(Windows.Foundation.EventRegistrationToken)’.3>C:\Program Files (x86)\MSBuild\Microsoft.NetNative\x64\ilc\IlcInternals.targets(887,5): warning : Invalid IL detected in method ‘System.Int64 UnityEngine.Internal.$MethodUtility.$Invoke2346(System.Int64, System.Int64*)’ at IL offset 0x12 referring to invalid Windows Runtime method ‘System.Void Windows.System.UserWatcher.remove_Stopped(Windows.Foundation.EventRegistrationToken)’.3>C:\Program Files (x86)\MSBuild\Microsoft.NetNative\x64\ilc\IlcInternals.targets(887,5): warning : Invalid IL detected in method ‘System.Int64 UnityEngine.Internal.$MethodUtility.$Invoke2345(System.Int64, System.Int64*)’ at IL offset 0x12 referring to invalid Windows Runtime method ‘System.Void Windows.System.UserWatcher.remove_Removed(Windows.Foundation.EventRegistrationToken)’.

There are loads of these errors, I have tried unticking allow Nuget to check for missing packages during build and tried unchecking Unity C# Projects within the Unity Build screen with no luck.

Any tips would be appreciated :slight_smile:

I see that “package restore incomplete” error all the time. I think it’s a red herring.

Have you tried cleaning your Solution? It’s item #10 in my steps above. That usually works for me when, all of a sudden, my Solution won’t build.

Yeah been trying for few hours now, will keep trying and share if i figure it out

Sometimes “clean” doesn’t work perfectly. Sometimes you have to manually delete the “obj” directory.

Exit Visual Studio and use File Explorer to delete the obj directories.

There are 3 obj folders, one for each project in the Solution.

  1. and 2) In the root of your Unity Project, there is a folder called “UWP”. In there are two sub folders. Each sub folder will contain an obj folder. Delete them both.

  2. Wherever you created your Unity project Build for UWP, there will be a sub folder named after your Unity project. In there will be a obj folder. Delete it.

Then reopen the Solution in Visual Studio, check your build settings and perform a “Rebuild Solution” from the Build menu.

Hopefully, you’ll get a clean build out of this and you can try to do a deploy.

Note that your deploy might fail, even if the build is successful. This is a known issue when changing build settings. See the link for possible workarounds.

1 Like