Windows Phone 8 Platform Guide using Cordova cross-platform Technology

This guide shows how to set up your SDK development environment to deploy Cordova apps for Windows Phone devices. It focuses on Windows Phone 8, but provides additional details on how to support Windows Phone 7.

It shows how to use either Windows Phone-specific shell tools to generate and build apps, or the cross-platform Cordova CLI discussed in The Command-Line Interface. (See the Overview for a comparison of these development  WORKFLOWS.) This section also shows how to open Cordova apps so that you can modify them within Visual Studio. Regardless of which approach you take, you need to install the Windows Phone SDK, as described below.

See the following for details specific to the Windows Phone platform:

·         Windows Phone 8 Plugins

·         Upgrading Windows Phone 8

For the Windows Phone 8 platform, the Cordova WebView relies on Internet Explorer 10 as its rendering engine, so as a practical matter you can use IE10's powerful debugger to test any web content that doesn't invoke Cordova APIs. The Windows Phone Developer Blog provides helpful guidance on how to support IE10 along with comparable WebKit browsers.

Requirements and Support

You need the following:

·         A 64-bit version of Windows 8 Pro, either an installation disk or an ISO disk image file. An evaluation version is available on the Microsoft Developer Network. The Pro version is necessary to run the device emulator.

·         The Windows Phone SDK.

·         In order to deploy via the command-line with the Windows Phone 8.0 SDK, the latest Visual Studio 2012 Update must be installed.

To develop Cordova apps for Windows Phone devices, you may use a PC running Windows, but you may also develop on a Mac, either by running a virtual machine environment or by using Boot Camp to dual-boot a Windows partition. Consult these resources to set up the required Windows development environment on a Mac:

·         VMWare Fusion: To set up the Windows 8 virtual machine, follow the instructions provided by the Microsoft Developer Network, then see Configuring VMWare Fusion for information on preparing the virtual environment to run the emulator bundled with the SDK.

·         Parallels Desktop: To set up the Windows 8 virtual machine, follow the instructions provided by the Microsoft Developer Network, then see Configuring Parallels Desktop for information on preparing the virtual environment to run the emulator bundled with the SDK.

·         Boot Camp: To set up the Windows 8 partition, follow the installation instructions provided by the Microsoft Developer Network.

If you are developing on a PC, its processor must support virtualization (VT-x on Intel) and Second Level Address Translation (SLAT). Consult Intel's list of supporting processors. Virtualization is typically disabled by default, so you need to enable it in your BIOS settings. The PC should have at least 6.5GB of free hard disk space, and 4GB of RAM.

Using Cordova Shell Tools

If you want to use Cordova's Windows Phone-centered shell tools in conjunction with the SDK, you have two basic options:

·         Access them locally from project code generated by the CLI. They are available in the platforms/wp8/cordovadirectory after you add the wp8 platform as described below.

·         Download them from a separate distribution at cordova.apache.org. The Cordova distribution contains separate archives for each platform. Be sure to expand the appropriate archive, cordova-wp8\wp8 in this case, within an empty directory. The relevant batch utilities are available in the top-level bin directory. (Consult the README file if necessary for more detailed directions.)

These shell tools allow you to create, build, and run Windows Phone apps. For information on the additional command-line interface that enables plugin features across all platforms, see Using Plugman to Manage Plugins. See Application Plugins for guidance on how to develop plugins, and Windows Phone 8 Plugins for details specific to the Windows Phone platform.

Install the SDK

Install the latest version of the Windows Phone SDK from the Downloads area of dev.windowsphone.com. You may also install more recent emulator update packages.

Create a New Project

At this point, to create a new project you can choose between the cross-platform CLI tool described in The Command-Line Interface, or the set of Windows Phone-specific shell tools. From within a source-code directory, here's the CLI approach:

    > cordova create hello com.example.hello HelloWorld
    > cd hello
    > cordova platform add wp8

Here's the corresponding lower-level shell-tool approach:

    C:\path\to\cordova-wp8\bin\create.bat C:\path\to\new\hello com.example.hello HelloWorld

Build the Project

If you are using the CLI in development, the project directory's top-level www directory contains the source files. Run either of these within the project directory to rebuild the app:

    > cordova build
    > cordova build wp8   # do not rebuild other platforms

If you are using the Windows Phone-specific shell tools in development, there is a different approach. Once you generate the project, the default app's source is available in the projects\wp8\www subdirectory. Subsequent commands are available in thecordova subdirectory at the same level.

The build command cleans project files and rebuilds the app. The first example generates debugging information, and the second signs the apps for release:

    C:\path\to\project\cordova\build.bat --debug        
    C:\path\to\project\cordova\build.bat --release

The clean command helps flush out directories in preparation for the next build:

    C:\path\to\project\cordova\clean.bat

Deploy to Emulator

At this point you can use the cordova CLI utility to deploy the application to the emulator from the command line:

    > cordova emulate wp8

Otherwise use the alternate shell interface:

    C:\path\to\project\cordova\run

By default, the run script invokes the emulator flag, and accepts additional build flags, for which --debug provides the default:

    C:\path\to\project\cordova\run --emulator --debug
    C:\path\to\project\cordova\run --emulator --release
    C:\path\to\project\cordova\run --emulator --nobuild