Deploy and Run Your App Built with Visual Studio Tools for Apache Cordova

Article
05/22/2015

In Visual Studio 2013, the Cordova tools are released as a preview (CTP) version. Cordova tools will be released as part of Visual Studio 2015 and we recommend that you now use Visual Studio 2015 RC to develop apps using Visual Studio Tools for Apache Cordova. You can download Visual Studio from the Microsoft Download Center.

The articles in this section provide detailed information about deploying your app built with Visual Studio Tools for Apache Cordova to Android, iOS, Windows, and Windows Phone devices. Information provided here includes how to run your app on various simulators, emulators, and devices.

Show the Solution Platforms list

When you want to run your Cordova app from Visual Studio, you must first select your target platform. The first time you try to do this after installing the Visual Studio extension, you might need to make the Solution Platforms list visible.

To select your target platform

In Visual Studio, choose a platform from the Solution Platforms list. In the following example, we show Android selected.

If the Solution Platforms list isn’t showing, choose Solution Platforms from the Add/Remove Buttons list to display it.

For all other steps required to run your app, see the platform-specific topics for Android, iOS, Windows, and Windows Phone.

How the Cordova build process works in Visual Studio

The Cordova Command Line Interface (CLI) does most of the heavy lifting for Visual Studio when you build and run a Cordova app. To make the process of installing and managing Cordova native code plugins easy, the CLI uses plugman, another command line tool. The CLI requires a specific folder structure, shown here. This folder structure is not fully mirrored by Visual Studio.

Cordova project structure in Visual Studio

To leverage the CLI from the Visual Studio project structure, Visual Studio uses a CLI pre-processor called vs-tac, which is a Node.js (npm) package. The first time you build and run a project built using Visual Studio Tools for Apache Cordova, vs-tac installs Cordova, the Ripple Emulator, and other required dependencies. It is the job of vs-tac to accept a build, pre-process the Visual Studio project, execute the specified Cordova CLI build system command, and run (or emulate) the app.

Cordova build process in Visual Studio

When building, Visual Studio injects its own custom hooks into the project to enable features that the CLI does not support.

Visual Studio automates the process of adding platforms (using the cordova platform add command) and installation/uninstallation of Cordova plugins (using the cordova plugin add command) based on user selections in Visual Studio. Visual Studio uses the CLI to build for the requested platform for the selected configuration (for example, cordova build android debug).

CLI native platform projects and the Cordova CLI project itself are not intended for editing, so don’t add these projects to your source control. They are updated and edited by the build process. However, if you choose, you can use the generated native platform projects to get an exported copy of the project.

Following are a few platform-specific details on the build and deployment process.

Android

The CLI supports both building and running Android apps on Windows. To run the app on the Android emulator, Visual Studio runs the CLI command cordova emulate android. This command deploys the app to an already running emulator, or, if none are available, it starts up the last emulator that was created. To run the app on a connected Android device, Visual Studio runs the CLI command cordova run android. To configure your Android device or emulator, see Run Your Apache Cordova App on Android.

iOS

Because an iOS app cannot be built on Windows, a remote agent (vs-mda-remote) enables you to build and run your app on a remote Mac machine (it can also run locally if you are using Visual Studio inside Parallels on a Mac). To build for iOS, vs-tac prepares the CLI project in exactly the same way as it does for any platform, but for iOS it then transfers the contents over to vs-mda-remote on the Mac. The remote agent unzips the contents, adds the iOS platform (cordova platform add ios), compiles the iOS app (cordova build ios), and then transfers the resulting package (IPA) back to the Windows host machine. To configure the vs-mda-remote and host Visual Studio for iOS build, see Install tools for iOS.

To run apps on iOS, Visual Studio builds the app using the vs-mda-remote and then uses ios-sim to start up the simulator on the remote Mac machine. If you are running on an iOS device attached to your Mac, vs-mda-remote starts the app directly (HomeBrew must be installed). If you run the app on an iOS device attached to Windows, Visual Studio builds and then adds the app to iTunes so you can deploy it to your device from Windows.

Windows 8 and Windows Phone

When building for Windows 8, Cordova generates a Windows Runtime app (APPX) for Windows 8. When building for Windows Phone 8, it generates a Silverlight (XAP) WebView app. These apps are launched in the same way as a native Windows 8 or Windows Phone 8 project in Visual Studio. For more information, see Run Your Apache Cordova App on Windows and Run Your Apache Cordova App on Windows Phone.

Apache Ripple Emulator

To make the Ripple build process to be as fast as possible, the CLI is used to generate the needed plugin code, but otherwise, Visual Studio provides the web content directly (instead of providing content from the generated native project). When you run the app, the Ripple emulator is initialized, and Chrome is started using a Ripple URL (for example, https://localhost:4400/index.html?enableripple=cordova-3.0.0-Nexus7 for the Nexus7 tablet device). All Chrome settings are stored locally to your Visual Studio instance so that your normal browser experience is not affected. For more information, see Run Your Apache Cordova App on the Apache Ripple Emulator.

Download the tools Get the Visual Studio Tools for Apache Cordova or learn more