How to deploy and run an app for Windows Phone 8

  • Article

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

This topic describes how to deploy and run your app in Windows Phone Emulator or on a Windows Phone device connected to your development computer.

While you’re developing a Windows Phone app, you can use Windows Phone Emulator to deploy and test your app quickly. We recommend that you test your app on an actual Windows Phone device, however, before you publish your app in the Windows Phone Store. This lets you experience your app as users will experience it.

To learn how you can test your app’s behavior under real-world conditions, see Simulation Dashboard for Windows Phone 8. For general info about debugging, see Debugging apps for Windows Phone 8.

This topic contains the following sections.

About deploying and running apps in Windows Phone Emulator

When you run a Windows Phone app for the first time in Windows Phone Emulator, the following events occur:

  1. The emulator starts.

  2. The emulator loads the Windows Phone operating system.

  3. The emulator displays the Windows Phone Start screen.

  4. Your app is deployed to the emulator.

  5. Your app runs on the emulator.

If the selected Windows Phone emulator is already running, your app is deployed and started in the running emulator. Only one instance of each emulator can run at a time.

Tip

When you’re testing your app on the emulator, leave the emulator open between debugging sessions so you can run your app again quickly.

About deploying and running apps on a Windows Phone device

You have to meet the following prerequisites before you can deploy an app to a Windows Phone device:

  • You must be a registered developer. For info about registering as a developer, see Registration info.

  • The phone must be registered. For more info, see How to register your phone for development for Windows Phone 8.

  • The phone must be connected to the host computer with the USB cable, turned on, and the screen must be unlocked.

  • To test apps on a Windows Phone 8 device:

    • The Windows Phone IP over USB Transport service must be running. This service is installed and started when you install the Windows Phone SDK 8.0.

    • The computer must recognize the connected device. A Windows Phone 8 phone is listed as a drive in File Explorer.

  • To test apps on a Windows Phone OS 7.1 device:

    • The Zune software must be installed on the host computer. To download and install the Zune software, go to the Zune software download page.

    • The Zune software must be running. When you connect your phone to the host computer, Zune starts automatically. If Zune does not start, start it manually.

    • The Zune software must recognize the connected device.

To troubleshoot app deployment, see the section Troubleshooting app deployment to your phone in this topic.

You can deploy up to ten apps on a registered device. This limit does not apply to apps that you install from the Store.

If you have existing apps that target Windows Phone OS 7.1, we recommend that you test them on a Windows Phone 8 device to ensure compatibility. For more info about possible issues, see App platform compatibility for Windows Phone 8.

Deploying and running an app in Visual Studio

To deploy and run an app in Visual Studio

  1. If you’re deploying your app to a connected device, make sure that you have completed the prerequisites listed earlier in this topic.

  2. In Visual Studio, open a Windows Phone project.

  3. On the Standard toolbar, select a target.

    • To deploy your app to the emulator, select one of the emulator options.

    • To deploy your app to a connected device, select the Device option.

  4. To deploy and run your app with debugging, on the Debug menu, click Start Debugging, or press F5.

    To deploy and run your app without debugging, on the Debug menu, click Start without Debugging, or press Ctrl+F5.

    Your app is deployed and started.

    To deploy your app without running it, on the Build menu, click Deploy Solution.

To stop a running app

  • To stop a running app, do one of the following:

    • In Visual Studio, on the Debug menu, click Stop Debugging, or press Shift+F5.

    • In the emulator or on the phone, press the Back button to exit the app. If the active page of the app was not the app’s start page, you may have to press the Back button more than once.

    The app exits and the Start screen opens. This ends the current debugging session.

To restart an app without debugging

  1. In the emulator or on the phone, on the Start screen, swipe left to view the app list.

  2. In the app list, tap the app icon. The app restarts without debugging.

To deactivate a running app

  1. Before you run your app, in Visual Studio, right-click the project in Solution Explorer, and then select Properties to open Project Designer.

  2. In Project Designer, on the Debug page, leave the Tombstone upon deactivation while debugging check box unchecked if you want the app to go into a dormant state when deactivated. Check the check box if you want the app to be tombstoned when deactivated.

  3. On the Debug menu, click Start Debugging, or press F5 to run the app.

  4. In the emulator or on the phone, press the Start button. The Start screen appears and the app is deactivated. The app either goes into a dormant state or it is tombstoned, depending on the setting of the Tombstone upon deactivation while debugging check box.

To reactivate a dormant or tombstoned app

  • In the emulator or on the phone, press the Back button to return to the app. If you navigated to other pages or opened another app, you may have to press the Back button more than once to reactivate the app.

    The debugging session resumes. If the debugger has detached from the app, you may have to press F5 to resume the debugging session. For more info about debugging and reactivation, see How to test app state changes for Windows Phone 8.

Deploying an app with the Application Deployment tool

You can also use the Windows Phone Application Deployment tool (XapDeploy.exe) to deploy your app. This tool is a stand-alone app that is installed when you install the Windows Phone SDK.

  • You can use the version of the Application Deployment tool installed in the folder C:\Program Files (x86)\Microsoft SDKs\Windows Phone\v8.0\Tools\XAP Deployment to deploy apps that target Windows Phone OS 8.0 or Windows Phone OS 7.1.

  • You can only use the version of the Application Deployment tool installed in the folder C:\Program Files (x86)\Microsoft SDKs\Windows Phone\v7.1\Tools\XAP Deployment to deploy apps that target Windows Phone OS 7.1.

To deploy an app with the Application Deployment tool

  1. Build your app. For more info, see How to build an app for Windows Phone 8.

  2. If you’re deploying your app to a connected device, make sure that you have completed the prerequisites listed earlier in this topic.

  3. From the Windows Start screen, launch the Application Deployment tool. You can find the Application Deployment tool by opening All apps view and locating it in the Windows Phone SDK 8.0 group, or by typing Application Deployment from the Start screen to search for it.

    You can also run the tool from the following location:

    C:\Program Files (x86)\Microsoft SDKs\Windows Phone\v8.0\Tools\XAP Deployment\XapDeploy.exe

    The application deployment tool starts, as shown below.

  4. In the Target drop-down box, select either Device or one of the emulator options.

  5. Click Browse and locate the XAP file that you want deploy.

  6. Click Deploy.

    If the deployment is successful, the Status field displays XAP Deployment Complete.

Deploying an app at the command prompt

You can also use the command-line version of the Application Deployment tool, XapDeployCmd.exe, to deploy an app. You can deploy an app from a script or from a custom app by calling this tool.

XapDeployCmd.exe is installed in the folder C:\Program Files (x86)\Microsoft SDKs\Windows Phone\v8.0\Tools\XAP Deployment.

XapDeployCmd.exe does not provide an option to deploy a new app without running it.

Important Note:

Command-line deployment for Windows Phone projects requires Visual Studio 2012 Update 2. XapDeployCmd.exe is not included in the version of Visual Studio 2012 that is installed by Windows Phone SDK 8.0.

To deploy an app at the command prompt

  1. Build your app. For more info, see How to build an app for Windows Phone 8.

  2. If you’re deploying your app to a connected device, make sure that you have completed the prerequisites listed earlier in this topic.

  3. Open a Command Prompt window. If your PATH environment variable doesn’t include the path to XapDeployCmd.exe, navigate to the folder C:\Program Files (x86)\Microsoft SDKs\Windows Phone\v8.0\Tools\XAP Deployment.

  4. Run XapDeployCmd.exe with one of the following options.

    • To deploy your app to the emulator, use the xd option.

    • To deploy your app to a connected device, use the de option.

Command-line deployment syntax and options

XapDeployCmd.exe has the following syntax:

XapDeployCmd.exe <cmd[:param]> <Product ID/Xap FileName> <targetdevice[:param]>

The following table describes the command-line options for XapDeployCmd.exe.

Option

Description

<cmd[:param]>

Specifies the command to run. This option has one of the following values:

OptionDescription
/installlaunchInstalls and runs the app on the device. This option requires the Xap FileName argument.
/updateUpdates the app already installed on the device. This option requires the Xap FileName argument.
/launchLaunches the app already installed on the device. This option requires the Product ID argument.
/uninstallUninstalls the app from the device. This option requires the Product ID argument.
/EnumerateDevicesLists the valid device targets and a numeric index for each device.

<Product ID>

Specifies the GUID of the app. This value is found in the app manifest file for the project, WMAppManifest.xml.

<Xap FileName>

Specifies the full path of the XAP to be installed or updated.

</targetdevice[:param]>

Specifies the target device. This option has one of the following values:

ValueDescription
xdDefault emulator.
deWindows Phone device connected to the development computer.
nThe device at index n in the list of devices. To get the list of devices, run XapDeployCmd.exe /EnumerateDevices.

Command-line deployment examples

Here are some examples of command-line deployment. The following examples assume that the Product ID is f8ce6878-0aeb-497f-bcf4-65be961d4bba and the Xap FileName is D:\PhoneApp1.xap.

  • XapDeployCmd.exe /installlaunch D:\PhoneApp1.xap /targetdevice:xd
    Installs PhoneApp1 on the default emulator and then launches it.

  • XapDeployCmd.exe /launch f8ce6878-0aeb-497f-bcf4-65be961d4bba /targetdevice:de
    Launches the app with the specified Product ID on the connected device.

  • XapDeployCmd.exe /update D:\PhoneApp1.xap /targetdevice:2
    Updates PhoneApp1 already installed on the device specified by device index 2. To get the list of valid devices, use the /EnumerateDevices option.

  • XapDeployCmd.exe /uninstall f8ce6878-0aeb-497f-bcf4-65be961d4bba /targetdevice:xd
    Uninstalls the app with the specified Product ID from the default emulator.

  • XapDeployCmd.exe /EnumerateDevices
    Enumerates the list of valid device targets and a numeric index for each device.

Troubleshooting app deployment to your phone

Deploying an app to a Windows Phone 8 phone depends on the local service Windows Phone IP over USB Transport (IpOverUsbSvc). It also depends on the correct installation of your phone as a USB device on the development computer.

To troubleshoot connectivity by checking the IpOverUsbSvc service

  1. Connect the phone to your development computer with the USB cable, turn the phone on, and unlock the phone’s screen.

  2. Open a Command Prompt window and run the IpOverUsbEnum command-line tool. You can find this tool in the following folder:

    C:\Program Files (x86)\Common Files\Microsoft Shared\Phone Tools\CoreCon\11.0\Bin

  3. Examine the output of the tool.

    • If you see several lines of info about the phone and the services running on it, the deployment problem is probably not a problem with the IpOverUsb service.

    • If you see the message, RPC Server Unavailable. Is the proxy running?, this indicates that the IpOverUsb service is not running. Open the Services snap-in and start the Windows Phone IP over USB Transport (IpOverUsbSvc) service.

    • If you see the message No connected partners found, check the following things:

      • Is the phone connected to the development computer with the USB cable?

      • Is the phone turned on?

      • Is the phone’s screen unlocked?

      • In File Explorer, is the phone visible as a drive under Computer?

To troubleshoot connectivity by updating the driver

  1. Connect the phone to your development computer with the USB cable and unlock the phone’s screen.

  2. Open Device Manager. Under Portable Devices, locate the entry for the phone.

  3. Right-click the phone entry and then select Update Driver Software. Follow the steps to update the driver.

Important differences between the development and release environments

Networking capability

When you deploy an app to the emulator or to a phone from Visual Studio, the networking capability is automatically included. If your app requires networking, however, you still have to specify this capability explicitly in the app’s manifest file when you submit the app to the Store. If you don’t specify the networking capability, the app could fail when it’s installed on a user’s phone. For more info, see App capabilities and hardware requirements for Windows Phone 8.

Writing to the app’s installation directory

When you deploy an app to the emulator or to a phone from Visual Studio, the app can write to its installation directory. However an app deployed and published through the Store cannot write to its installation directory. If an app that was installed from the Store attempts to write to its installation directory, an exception is raised. If you include code in your app that writes to the app’s installation folder while you’re developing and testing the app, be sure to remove this functionality before you publish your app to the Store.

Testing Windows Phone OS 7.1 media APIs

When you test an app that targets Windows Phone OS 7.1 on a connected device, usually the Zune software is running. However, you can’t test apps that interact with media APIs while the Zune software is running, because it locks the local media database. To test apps that target Windows Phone OS 7.1 and use media APIs, you can use the Windows Phone Connect Tool to establish a serial or USB connection to the device without running the Zune software. For more info, see How to test apps that use the photo chooser or camera capture task for Windows Phone 8.

See Also

Other Resources

How to build an app for Windows Phone 8

Windows Phone Emulator for Windows Phone 8