Use the Microsoft Emulator

Important

This article describes functionality and guidance that is in public preview and may be substantially modified before it's generally available. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Use the Microsoft Emulator with the Windows 10X Emulator Image Preview to test your app without a physical device. The emulator is integrated into your development environment and simulates postures, gestures, hinge angle, mimicking the seam between the two screens, and more.

Ways to debug your app

This document explains how you can get set up to run and debug applications using the Microsoft Emulator.

The Surface Neo and other Windows 10X devices are "develop-to" devices, meaning that you will develop on your desktop PC and then deploy to the device. You have two options for doing this: using the emulator, or using remote debugging. This document discusses the emulator.

For more information on remote debugging, see Remote Debugging in the Visual Studio documentation. There is also a short list of tips at the end of this document for remote debugging of apps that run in the Win32 container.

For information on the Window Device Portal, which provides many useful debugging features, see Windows Device Portal overview.

About the emulator

The Microsoft Emulator preview lets you test apps on your PC without using a physical Windows 10X device. The emulator integrates with Visual Studio and becomes a target device for debugging. When you run your app from Visual Studio, the emulator starts and your app is deployed to it.

Emulator toolbar

The emulator has volume and power buttons that work. The volume buttons will control the audio output. The power button lets you re-cycle the OS without restarting the emulator.

The emulator toolbar lets you to choose the various input modes supported by the device – mouse, touch, multi-touch, and ink. You can use the toolbar to quickly change the orientation of the emulator.

Microsoft emulator toolbar

Additional tools

The chevron at the bottom of the toolbar opens the Additional Tools window. This window contains tabs that provide support for various features of the emulator.

Diagnostics

The Diagnostics tab provides the IP address to use for the Windows Device Portal. You can click the IP address hyperlink to launch it. This tab also indicates whether or not the emulator detects a virtual GPU.

Additional tools diagnostics tab

Network

The Network tab provides the networking configuration, which is useful when diagnosing connection problems.

Additional tools network tab

Orientation

The Orientation tab provides a 3D model for you to see how your app and the OS behaves in many different orientations.

Additional tools orientation tab

Screenshot

The Screenshot tab lets you easily take a screen shot and save it to the host machine.

Additional tools screenshot tab

Microsoft Emulator Manager

The Emulator Manager is a developer tool that lists all the Microsoft Emulators installed on your machine. It allows you to see their status, and start a given emulator independent of Visual Studio. You can start the Emulator Manager from the Microsoft Emulator entry in the Start menu.

Additional tools network tab

You can also configure various settings for an emulator. Click the Edit button on the selected emulator image entry to open the Edit Emulator Device window. For Windows 10X, the images are pre-configured to use 4GB of ram. To improve the responsiveness of the emulator, we recommend increasing this as your memory allows.

Additional tools network tab

Uninstall the emulator and images

Each emulator image is several gigabytes. If you need to free up disk space, you can uninstall downloaded images in the Settings app, under Apps. Find Microsoft Emulator in the app list and click Advanced Options.

emulator app listing in settings

At the bottom of this advanced options page, you'll find your emulator images. Just click "Uninstall" under an image to remove it.

optional packages listed under emulator app

Debug UWP apps

Visual Studio 2019 Preview

After you’ve installed the Microsoft Emulator and Windows 10X Emulator Image, the latest Visual Studio 2019 Preview recognizes that the emulator is installed. You can target it from the Debugging target drop down menu. Visual Studio will then deploy the app to the emulator, launch it, and attach a debugger.

Visual Studio debug target drop down showing the emulator target

Earlier versions of Visual Studio

If you're using Visual Studio 2017 or 2019 (version 16.4 or earlier), select the emulator image in Microsoft Emulator Manager, click the "Add Visual Studio Integration" button, then restart Visual Studio. You'll need admin rights to do this. If you have trouble with the emulator drop-down in Visual Studio not behaving as expected, try clearing the drop-down from the Tools menu in Emulator Manager.

You can also target the emulator by targeting it as a remote device. This configuration is detailed in the MSIX packaged apps section.

Debug Win32 apps

MSIX packaged apps

The recommended solution for developing Win32 apps on Windows 10X is the MSIX packaging format, which makes it easy to both debug and distribute your apps. MSIX packages support the same languages you already work with in Visual Studio, including C#, C++, and Visual Basic. For more info about the MSIX packaging format, see the MSIX documentation.

To debug applications deployed with the Windows Application Packaging project, you will need to treat the emulator as a remote debugging target.

  • First, get the IP Address from the Emulator Manager. You can select and copy this as normal text from the app.

emulator manager showing the IP address for the emulator

  • In the Project Properties of the packaging project:
    • Find the "Start options" section on the Debug tab.
    • Set the Target device to Remote Machine.
    • Enter the IP address of the emulator.
    • Set the Authentication Mode to Universal.

packaging project properties showing the 3 settings

  • Press F5 to deploy the application to a running emulator and hook up debugging without additional steps.

Non-packaged apps

If you're debugging an app that doesn't use MSIX packaging, you need to use the Visual Studio Remote Debugger. For info and download links, see the Remote Debugging page. Make sure to use the right remote debugger for your version of Visual Studio. The debugger needs to be installed in the emulator, not on your development machine.

Once you've installed the debugger in Windows 10X, launch it from the Start menu. Under Tools > Options, select No Authentication and check the box next to Allow any user to debug.

remote debugger properties showing anonymous configuration

You also need to configure Windows 10X to allow untrusted applications to run in the Win32 container. This setting is under Apps. Change the dropdown under Choose which apps to install from Verified and reputable apps to All apps (not recommended).

C++ projects

Non-packaged C++ projects should use the remote debugging feature built into the Visual Studio C++ project system. This config is supported on both Visual Studio 2017 and 2019.

  • Launch the emulator and open Windows Device Portal (WDP). The link to launch WDP is in the Diagnostics tab of the emulator's Additional Tools window.

  • Select File explorer from the navigation menu in WDP.

  • Click the folder named DevelopmentFiles. This is where your project is deployed for debugging.

  • Under Directory path, you'll see the full path of this folder. Copy and paste this value.

    wdp displaying full directory path

  • In your solution, right-click your C++ project and select Properties.

  • Under the Debugging section, set both Working Directory and Deployment Directory to the path you copied from WDP.

  • Set Remote Command to this path, plus the name of your executable.

  • Set Remote Server Name to the IP address of the running emulator.

Your configuration should look similar to this example:

c++ debug configuration example

  • Under C/C++ > Code Generation, set Runtime Library to Multi-threaded Debug (/MTd).
  • Press F5 to deploy your project to the remote debugger.
    (You won't see a Start menu icon for your app. Once your app has an installer, a Start icon will be created when the app is installed normally.)

.NET projects

Support for non-packaged .NET projects is coming soon. Stay tuned!

Tips

  • Leave the emulator up and running to avoid restart. The emulator preview takes a while to start on a desktop class machine.
  • Use the emulator's Windows Device Portal to:
    • Deploy content to your libraries and LocalAppData.
    • Manage running processes.
    • Remote debug apps in Win32 containers.
  • You can use the power button to "reboot" faster than restarting the emulator and you won't lose your state, such as things you've installed inside the emulator.
  • VisualStudio updates can lose the emulator – to restore it, delete the CoreCon cache in Visual Studio's local app data folder (C:\Users\<user>\AppData\Local\Microsoft\VisualStudio\{ad75a28f}\CoreCon).

Span your app in the emulator

To span your app in the emulator, drag the app from the title bar at the top of the app screen towards the middle of the device. When the background turns blurred across both screens, release the app.

Steps to span an app in the emulator

Submitting bugs and feedback

We need your feedback! If you run into bugs in Windows 10X while testing your apps, please file feedback from Feedback Hub in the emulator. This will ensure the appropriate logs and other troubleshooting data is collected. If you can't submit feedback directly from Windows 10X, just look under the Help menu in the emulator manager to jump to Feedback Hub on your Windows 10 desktop PC.

Note

The Microsoft Emulator and Windows 10X Emulator image are being provided as a public preview. This is an early release of the developer tools geared towards providing developers access to build, test, debug, and enhance their applications for Windows 10X and focus on feedback in these areas will be prioritized.