hybrid mobile apps for asp.net developersdownload.microsoft.com/download/8/7/c/87c46084-092a... ·...

30
Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael Serna & Josué Yeray Julián © Microsoft Corporation For the latest information, please see https://www.visualstudio.com/en-us/explore/cordova-vs

Upload: others

Post on 19-May-2020

13 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for

ASP.NET developers

Published: April 2015

Authors: Rafael Serna & Josué Yeray Julián

© Microsoft Corporation

For the latest information, please see

https://www.visualstudio.com/en-us/explore/cordova-vs

Page 2: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

1

Hybrid mobile apps for ASP.NET developers

Table of Contents

If you know web development, you know how to create mobile apps .......................................................................... 2

Introduction to the Apache Cordova application model ..................................................................................................... 4

Installation & Setup ........................................................................................................................................................................ 5

Cordova Project structure ............................................................................................................................................................. 6

Bower .................................................................................................................................................................................................... 8

Plugins ............................................................................................................................................................................................... 11

Creating a simple mobile application with Apache Cordova Tools for Visual Studio............................................ 12

Build & Deploy ................................................................................................................................................................................... 15

Android ............................................................................................................................................................................................. 15

iOS....................................................................................................................................................................................................... 19

Windows Phone............................................................................................................................................................................. 21

Windows ........................................................................................................................................................................................... 22

Debugging ........................................................................................................................................................................................... 23

Apache Ripple Emulator ............................................................................................................................................................. 23

Devices and emulators ........................................................................................................................................................... 25

Frequently Asked Questions ......................................................................................................................................................... 27

What is the difference between Apache Cordova and PhoneGap? Are they the same thing? ..................... 27

An error showed up while building for a platform for the first time? ..................................................................... 27

I just connected my Android Device to my machine and deployed to it. I got a “No Devices Found” error.

What happened? ........................................................................................................................................................................... 27

How do I get around Apache Ripple limitations? ............................................................................................................ 27

Ripple popped up an “I Haz Cheeseburger?!?!” message. What happened? ....................................................... 28

How can I get access to the native Xcode project used to build? How can I manually build for iOS or use

the emulator on a Mac? ............................................................................................................................................................. 28

Page 3: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

2

If you know web development, you know how to create mobile apps

There are several ways to approach the creation and display of a mobile application or website. Nowadays,

we can distinguish between responsive sites adapted to mobile viewing and applications developed directly

for such devices.

A responsive site allows you to have a single website that will automatically adjust to the screen size of the

device that is being used to view it. This is achieved by adapting the contents, design, navigation and

method of interacting with the user to provide the same level of convenience and ease of use for both

mobile and desktop users.

On the other hand, mobile applications are software specifically developed for each type of device. Users

must download the application from a store specific to the operating system.

Creating a website adapted for display on mobile devices is definitely the easiest option compared to

developing a mobile application. Basically, in most cases it’s enough to implement a redesign, conducting

occasional maintenance and coordinating updates if there are different versions for different environments.

Depending on the design of our web application or site, turning it into a responsive design normally requires

much less time than creating a native application. If we also want it to be accessible only from a browser, it

also requires less time to publish, since there are no publication processes or guidelines to follow, which do

exist in the different mobile application platforms.

However, even though responsive design optimization for the different systems and browsers is no simple

task, it is not the biggest problem that a developer must face. Even though a responsive website

optimizes experience, it does not include access to all the features that a Smartphone provides, such

as sensor management, the camera, push notifications, etc.

Another disadvantage of building a responsive website is navigation. On a website, navigation is typically

from top to bottom. This approach may be useful in some scenarios. However, many other applications are

more conveniently navigated from left to right. This navigation can be implemented by a responsive

website, but extra time and effort is required for its implementation. A mobile device has a user experience

that is completely different to that of a desktop device, so having a responsive website may harm said

experience for both platforms. If we try to please both worlds, we may end up not pleasing either.

A mobile application offers users the features and speed that cannot be achieved with a responsive website.

As the complexity of responsive websites increases, it is easy for user experience to begin to suffer. Inversely,

Page 4: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

3

mobile applications are not only able to use the low-level features available in the device’s hardware, but

they also have access to more user information and thus can offer a more customized experience.

When we develop a mobile application, we need to make one more decision: whether to develop it as a

native application or use tools that will help us make use of as much of the available code as possible and

then implement it on each of the platforms that we want.

Clearly, native development is the best option whenever possible. The problem is that each platform (iOS,

Android, Windows Phone) uses a different programming language and its own tools. In exchange, we obtain

maximum flexibility, total adaptation to the environment and maximum performance.

As the main disadvantage, we find ourselves in the need to master different languages and tools if we want

to have an application for each mobile platform, apart from having to create the application as many times

as the number of mobile platforms we want to support.

A great option to overcome the difficulty of making a multi-device application, is to create a hybrid app

with a common base code. This type of applications are developed in HTML, CSS and JavaScript and are

wrapped with a native layer for each platform in the form of an app, allowing them to be published in

the app stores and be used just like any other native application. From the HTML code, we will have access

to the hardware and most of the native features of the platform.

This way we have the best of both worlds: a common development made with standard widespread

technologies (HTML+CSS+JavaScript) and compilation as native process applications to be able to access

the hardware and to deploy them in the stores of each platform.

Page 5: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

4

Introduction to the Apache Cordova application model

Apache Cordova is a free and Open Source platform for building hybrid applications using HTML,

CSS and JavaScript.

Its main purpose is that it extends the ability of the mobile web browser to access the hardware of the

device. For this, Apache Cordova implements a set of APIs that allow access to the native capabilities

of mobile devices from the hybrid applications that are run within the container of each platform.

To develop an Apache Cordova application, a web application is created. This is just like any other web

application executed inside a mobile web browser. You can open other pages, either local or from a web

server hosted anywhere on the Internet. Everything that a developer can do with a website hosted in a

server can also be done inside an Apache Cordova application.

As we have noted, Apache Cordova adds a set of JavaScript APIs to that web application embedded in its

container. These APIs allow accessing the device’s capabilities outside the web context. In essence, these

APIs are implemented in two parts: a JavaScript library that exposes the native capabilities to the web

application and the corresponding native code operating in the container that implements the native part

of the API. In practice, this involves using in our application a common JavaScript library that will have

separate native implementations for each mobile platform supported (transparent for us as developers).

Since version 3.0 of the Apache Cordova platform, each of these APIs have progressively split into separate

plugins. Now we can add or take away plugins at will depending on the needs of our application.

Apache Cordova provides multiple tools to work with the platform on the different operating systems that

it supports. However, starting the tools, debugging and compiling the applications on each system, etc.

involves a lot of effort on the part of developers, and the process is prone to errors.

In order to make this job easier, Microsoft has created a free product, the Visual Studio tools for Apache

Cordova, that allow us to easily create, debug and distribute hybrid applications for iOS, Android and

Windows/Windows Phone. The Visual Studio tools for Apache Cordova provide great advantages when

developing with this multi-device platform.

The first is the easy and convenient installation of all the tools needed for developing with Apache

Cordova. Installing this platform would normally involve quite a lot of work for the installation and setup of

third party software, needed to support each of the native platforms. With the Visual Studio Tools for

Apache Cordova, all of this is achieved with a simple installer.

With Apache Cordova, code writing is also made easy with the usual advantages of Visual Studio:

IntelliSense, syntax highlighting, refactoring, method search and examination, etc., as well as the easy

management of Cordova plugins, all of which greatly helps development, as it already happens with

conventional web applications.

Page 6: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

5

Also, we can perform debugging tasks in a unified way for all the platforms. Multiplatform development

requires debugging both on physical devices and on emulators and simulators. With Visual Studio, you

will be able to debug your hybrid apps for all possible deployment destinations—including physical devices,

multiple Android, iOS and Windows/Windows Phone emulators and simulators, and even on the Mac

platform in the case of iOS applications.

Installation & Setup

We can install the Visual Studio tools for Apache Cordova in Visual Studio 2015 as another option of the

suite. We just need to select the option ‘Tools for Apache Cordova’ in the installation process:

Once having installed the Apache Cordova tools themselves, we will be required to install third-party

software dependencies. Most of these tools are open source software required for development on certain

platforms or by Apache Cordova itself:

Page 7: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

6

Among the third-party tools that we are asked to install are Joyent Node.js, Google Chrome, Apache Ant,

the Android SDK and SQLite. It could be the case that some of these tools are already installed on our

system or that we have to perform a manual installation of one of their dependencies.

Although this phase of installation may take up some time, it saves us a lot of manual installation and

configuration steps that we would need to follow ourselves if we were to install the Apache Cordova tools

independently.

Cordova Project structure

To begin to create an application with the Visual Studio tools for Apache Cordova, we need to create a

project with the Apache Cordova application template, under the JavaScript language:

Page 8: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

7

A project of this type is mainly organized into 5 sub-folders:

CSS, which includes the basic style sheets used by the template.

Images, the folder suggested to locate the images of our project.

Merges, where we find the files that add the code specific to each of the platforms. By default, the

template includes the code most commonly used for Windows and Android devices. In the case of

Windows devices, the code is used to enable support for a series of JavaScript libraries, which would

be blocked by the system’s security model if we wanted to use them directly, since they contain

code that is potentially unsafe. In the case of Android, there is support for features used on devices

with version 2.3 of the system or above.

Res is used to contain visual files for each of the platforms (icons, start screens), signing certificate

and custom configuration files.

Script is the default folder for the location of JavaScript or TypeScript files used to create the web

application on which the final application will be based.

Apart from these folders, in our project we will also find the file config.xml, which contains configuration

settings for our application, as well as all the HTML files that will make up our application, of course. In this

case, we will at least have an index.html file which is the default start screen of our app. Many times we will

encounter projects and examples where all the HTML code is located in a sixth folder of the project,

called www.

Page 9: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

8

Bower

Today, one of the most significant features of creating web applications is the use of all kinds of libraries

and frameworks to facilitate development. Remember that a hybrid application with Apache Cordova is

essentially a web application in a container. With Visual Studio 2015, we have the support of one of the

tools most commonly used nowadays for the installation and maintenance of Front-End packages: Bower.

Described as a package manager for the web, it allows us to install and restore utility packages and client-

side libraries.

In order to use Bower, the first thing we need to do is install the tool using the npm (Node Package

Manager). The best way to do this is to open the command-line console via the link provided by Visual

Studio 2015. The “Developer Command Prompt” has a set of paths configured by default in the path of the

system that will be helpful to facilitate access to certain tools.

In order to install Bower we will run the following command:

Page 10: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

9

This command tells the npm (the Node.js package manager) that it must install Bower at global level, so

that the package can be accessed from any location and only a single global version of it is installed.

Next we will install the client-end libraries that we want, using the newly installed package manager. For

this, we just need to use the command line to access the path where our project is found, and run Bower

with the command “install”.

For example, if we wanted to install “AngularJS”, in the project we should write the following command:

A much more convenient way to install packages via Bower is by creating a configuration file. Visual

Studio 2015 includes IntelliSense help for this type of files, so their creation is extremely straightforward.

We will create this file, called “bower.json”, in the root of our project, and we will specify that, for example,

the packages “AngularJS”, “Bootstrap” and “RequireJS” will be installed in it. For this, Visual Studio will help

us throughout the process of writing it, both with file nodes and subsequently when selecting packages…

…as well as when deciding which version to use:

Page 11: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

10

This would be the end result in our example:

As you can see in the dependencies section, we are specifying each of the packages to be installed, as well

as their version. The version may be indicated in 3 different ways:

“1.3.2”. This means installing a specific version of the package.

“^3.3.2”. This means installing any package within the “major” version indicated, above or equal to

the one specified, i.e. >=3.3.2 and <4.0.0.

“~2.1.16”. This means installing any package within the “minor” version indicated, above or equal

to the one specified, i.e. >=2.1.16 and <2.2.0.

Once the bower.json configuration file is completed, we just need to go to the command prompt and run

the following command:

This command will install all the packages specified and the dependencies that said packages may have. In

this case, we have asked it to install “AngularJS”, “Bootstrap” and “RequireJS”. It has also installed “JQuery”

because it is a dependency of “Bootstrap”.

The files in each of the packages are automatically copied to separate folders within another folder called

“bower_components”:

Page 12: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

11

Plugins

As mentioned before, one of the features of Apache Cordova is that it provides access to native capabilities

of the mobile platforms from the web application that we run in the container. For this, we will use the

Apache Cordova plugins. A plugin is a multiplatform library of Apache Cordova, which can access the

native platform capabilities of the devices through a programming interface based on JavaScript.

Plugins also update each platform manifest, depending on the type in each case, to enable the capabilities

of the device.

To enable and manage the plugins to be used in our application we have the config.xml file, located in the

root of our project. We will edit this file using the configuration designer, as shown in the following

screenshot:

Page 13: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

12

We can add a plugin of the Apache Cordova core or a custom plugin. To do this, once we edit the

config.xml file with the configuration designer, we must click on the plugins tab and select the type of

plugin to enable for the application—core or custom.

In the case of core plugins, apart from the plugin ID and its version, the designer shows us the platforms on

which it is available. To add it to the project, we just need to click on “Add”.

On the other hand, if we want to add a custom plugin, it can be found via a local location or via a Git code

repository.

When adding any plugin, Visual Studio adds the corresponding folder to the project, as well as a series of

files. Inside this folder, a new one called “www” is created, where we find the JavaScript files that make up

the plugin, the file plugin.xml specifying which files the folder “www” contains and on which platform each

of them is used, and the file package.json specifying the configuration of the packages so that the npm

(remember—the package manager for Node.js) can perform the initial download of the whole plugin.

In the event that we want to remove a plugin, we will just need to locate it again in the designer and click

on “Remove”.

Updating a plugin is a task as simple as in previous cases. From the configuration designer we will be able

to update any plugin to a newer version.

Often, plugins have a set of associated parameters that have to be configured. For this, we must edit the

configuration file (config.xml) again, but in this case in an XML file editor. From Visual Studio we will right-

click on the configuration file and select the “view code” option in the context menu.

For example, in the above figure you can see the part of the config.xml file code corresponding to the

parametrization of Apache Cordova’s official plugin to access Facebook from our application. Here we must

configure the parameters needed for the plugin to work properly.

Creating a simple mobile application with Apache Cordova Tools for Visual Studio

In order to visually test everything covered up to this point, we are going to create an Apache Cordova

Project in Visual Studio 2015, which will be quite straightforward yet illustrative of the possibilities of these

tools. It will consist in a meteorology application that will show us the weather at our current position, based

<vs:plugin name="com.phonegap.plugins.facebookconnect" version="0.8.1">

<param name="APP_ID" value="123123" />

<param name="APP_NAME" value="The App Name" />

</vs:plugin>

Page 14: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

13

on the geographical location data returned by the mobile device and the OpenWeatherMap web service:

To create this application, we have added to our project the Apache Cordova Geolocation plugin, as well as

the “AngularJS”, “BootStrap”, “RequireJS” and “JQuery” packages (via Bower). As such, the structure of our

project is now as follows:

Page 15: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

14

The “app” directory of our “scripts” folder contains the development of our project in AngularJS.

You can download the example application with its code, plugins and components, as well as the completed

applications for each platform at http://aka.ms/txjxn8.

The details of how the web application is created are beyond the scope of this publication, but the most

noteworthy thing to highlight is the call to the Apache Cordova geolocation plugin from the application’s

JavaScript code:

As you can see, we make a call to the system API via navigator.geolocation.getCurrentPosition.

Because we have installed the geolocation plugin, for each platform Apache Cordova converts this call

to its respective code in order to make a geolocation request.

In this case, the call is asynchronous and therefore we pass it a callback function to receive the results when

they are ready. The object (which we have called result) that is passed to the callback function includes a set

of properties with information about the current position of the device. In order to make the call to the

OpenWeatherMap API later, we will use the properties corresponding to latitude and longitude. These

properties are found inside the coords object of the result.

We have several methods to test our application, depending on the platform where we want to do it. The

first thing that we need to select is to which specific platform we want to deploy to debug. For this, we

just need to look at the Visual Studio toolbar, where we will find a drop-down with all the available platforms:

navigator.geolocation.getCurrentPosition(

function (result) {

var latitude = result.coords.latitude;

var longitude = result.coords.longitude;

//Do something.

},

function (error) {

//Error detected;

}

);

Page 16: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

15

Once we select the platform, we get the option to choose the system on which to launch the application to

test it:

The following systems are available for the Android platform:

Physical device

New Visual Studio Android Emulator

Android Emulator, belonging to the Android SDK

Genymotion Emulator

Apache Ripple Emulator

For iOS:

Physical device

iOS Emulator

Apache Ripple Emulator

For Windows and Windows Phone:

Physical device

Visual Studio emulators for Windows Phone and Windows

Build & Deploy

Android

To test your application on a high-performance Android emulator, you will first need to configure the

Android HAXM driver.

Page 17: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

16

For this you will need to use the Android SDK Manager. In Windows, you can locate the “Android SDK

manager.exe” file at “C:\Program Files (x86)\Android\android-sdk”.

Once inside, expand the “Extras” branch and find the “Intel x86 Emulator Accelerator (HAXM installer)”

package:

This will download the HAXM driver installer to the path of the Android SDK:

“path_SDK\extras\intel\Hardware_Accelerated_Execution_Manager”.

You will need to go to this directory and execute the intelhaxm.exe file to complete the installation

process.

Once having done this, you will be able to use the high-performance Android emulator included with the

Android SDK. Open the Android Virtual Device (AVD) Manager, AVD manager.exe. Select “New” to create a

new device and configure the properties of the new emulator. The properties required are the following:

- AVD name

- Device

- Target CPU/ABI

- Skin

- Target

The following image shows the configuration done on a new emulator:

Page 18: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

17

If you have previously installed the high-performance HAXM driver, select an Intel CPU and tick the option

“Use host CPU” in the emulator options. Click OK to complete the creation of the new emulator. On the

main screen of AVD Manager, select the emulator you just created and click “Start” to start it.

Now, in Visual Studio, select Android among the platforms of the solution. Select the Android Emulator

from the list of devices:

Now you just need to click F5 for the application to start on the emulator with debugging, or shift + F5 if

you want to launch it without debugging. You must bear in mind that you need Android 4.4 or above for

debugging to work.

Note: If you get an “ANDROID_HOME is not set…” error message while compiling your Cordova app,

please make sure that you have a system environment variable called “ANDROID_HOME” that points to

your Android SDK folder (usually in “C:\Program Files(86)\Android\android-sdk”). You can set this variable

in the Advanced System Properties dialog (Windows Key + Pause) in your Windows computer.

Page 19: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

18

If you want to launch your application with the new high-performance Android Emulator included in

Visual Studio, you just need to select it from the list of available devices, where you will find 4 options:

VS emulator KitKat Phone

VS emulator KitKat Tablet

Vs emulator Lollipop Phone

VS emulator Lollipop Tablet

The former two use version 4.4 (KitKat) of Android, while the latter two use version 5.0 (Lollipop) of the

system.

Among other tools, the Visual Studio emulator for Android gives us the possibility of simulating the location

of the GPS, the movement of the accelerometer, the rotation of the screen, SD storage, network access, etc.

We can also use our computer’s webcam inside the emulator as if it were the webcam of the device. By

using Hyper-V as the virtualization base, we will achieve a performance equal to that of the Android native

emulators that use HAXM that we saw earlier.

If you prefer to use a Genymotion emulator, you will need to install it first from its website. Once you have

installed and configured a Genymotion emulator, you will be able to use it from Visual Studio by selecting

the “Device” option from the list of devices. The Android development tools see Genymotion emulators as

real devices.

Page 20: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

19

If you have a physical device with Android and you want to launch your application on it to test it, you will

need to follow these simple steps:

- You will have to install the driver from the manufacturer or from Google for USB communication

with the device.

- You need to make sure that your device is in development mode.

- Select “Device” from the list of devices in Visual Studio

- Click F5 or Shift + F5 to launch your application on the physical device.

- The first time, your device may ask you if you want to allow USB debugging. Accept and the process

will continue.

iOS

To deploy and test your application on iOS, you have the following options:

- iOS simulator

- iOS physical device

- Apache Ripple Emulator

For either option, you will need an Apple computer with Mac OS X installed. This is an unavoidable

requirement in any development for Apple platforms.

In your Mac, you will have to install the Visual Studio remote compilation agent. You will previously need

to have certain requirements installed:

- Mac OS X Mavericks or higher

- XCode 6

- XCode command line tools

- Node.JS

- An active iOS developer account

- A provisioning profile configured in XCode

- A signing identity configured in XCode

To view detailed information about the installation and setup of the remote compilation agent, go to this

MSDN page.

Once you have configured your Mac environment for remote compilation, in Visual Studio you need to

select iOS for the platform of the solution. In the list of devices you will be able to select the iOS emulator

that you want to start:

Page 21: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

20

Click F5 and the application will start on the simulator chosen if the remote agent is correctly configured:

If you prefer to test your application on a physical iOS device, you have two options: local device or remote

device. For both options, you will need to have installed on your device the provisioning profile that you

must first have configured in XCode and which must be ready to allow deploying applications.

Page 22: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

21

You will simply need to select either “local” or “remote” and click F5 to launch your application.

If you have selected the option of local device, iTunes will be launched on you PC and your application will

be added to your library. If it already exists, it will be replaced by the new version.

If you have selected a remote device, connecting your iPhone to a Mac, the application will be automatically

launched without opening iTunes.

Windows Phone

To test your application on Windows Phone, you have two options:

- Windows Phone Emulator

- Windows Phone physical device

You have a choice between several options to generate your package for Windows Phone:

- Windows Phone 8, which will generate a .xap package.

- Windows Phone Universal, which will create a .appx package.

To run your application on the Windows Phone emulator, you must first make sure that your operating

system has Hyper-V enabled. Once this is done, select Windows Phone 8 or Windows Phone Universal from

the list of platforms of the solution in Visual Studio.

Next you will need to select an emulator among those available:

Click F5 to start your application on the emulator with debugging, or shift + F5 if you want to start it without

debugging.

Page 23: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

22

On the other hand, if you want to test your application on a physical Windows Phone device, select the

“Device” option from the list of devices.

- You will need to ensure that your device is registered for development; otherwise you will not be

able to deploy an application from Visual Studio.

- Connect your device to your PC using a USB cable.

Now you just have to click F5 or shift + F5 to run the application with or without debugging on your physical

device.

Windows

To test your Cordova application on Windows, you have three options:

- Local machine, which will run the application on your PC.

- Simulator. A Windows simulator will open, which will allow you to emulate options such as

geolocation, screen size, rotation, etc.

- Remote machine, i.e. deploying the application on a remote PC or tablet through the network.

To run your application on the local machine or the simulator, select a Windows platform, such as Windows-

x86 or Windows-x64, among the platforms of the solution.

On the list of available devices, select “Local Machine” or “Simulator”.

Page 24: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

23

Click F5 or shift + F5 to launch your application with or without debugging:

If you prefer to test your application on a remote device, such as a tablet, you will need to complete a few

additional steps, such as configuring a remote deployment host. To view all the details about how to deploy

on remote devices, please refer to this page on the Windows development center.

Debugging

One of the most important phases of the development of a software application is debugging the code.

The Visual Studio 2015 tools for Apache Cordova facilitate this task significantly.

Apache Ripple Emulator

If you debug using the Apache Ripple emulator, you can set breakpoints in your code, use the DOM explorer

or send messages to the JavaScript console.

To set breakpoints you just need to indicate them in the code in the usual way (by clicking F9 or clicking on

the margin of the code), as shown in the following figure:

Page 25: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

24

When the code reaches the highlighted point, the application will stop running. We need to take into

account that in this case the code will not stop in the first execution of the screen. Once the Ripple emulator

has been launched, we need to refresh the browser for the breakpoint to work.

Another possibility that we have is sending messages to the JavaScript console. For this, we can use the

Console commands, which are all supported by Ripple. Among these, we can use the following:

console.assert

console.clear

console.count

console.debug

console.dir

console.dirxml

console.error

console.info

console.log

console.time

console.timeEnd

console.warn

Executing the same code that you find at the top, you can see the execution of two “console.info” commands,

which generate the following output in the console.

Page 26: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

25

Finally, we have the DOM explorer, which will make it easier to debug the HTML and CSS code. The DOM

explorer displays a view of the rendered page so we can modify the values and see the results immediately.

This allows us to test changes without having to stop and restart the debugger. The source code in our

project does not change when we interact with the page using this method, so once we find the desired

code corrections we will need to make the changes in the source code.

On the image below you can see how we select a DOM element of the main page and that element is

highlighted in the page rendering:

We can use the DOM explorer to:

Navigate the DOM tree,

Inspect the HTML, CSS and JavaScript code,

Dynamically edit CSS styles and attributes for rendered elements and view the resulting CSS

properties,

Inspect how the CSS styles have been applied to items of the page and traces of the rules that have

been applied.

Devices and emulators

We can also debug in the same way and with the same tools if we run our application on an emulator or

on a device.

If we debug on Android devices and emulators, we must be mindful of their version.

In the case of version 4.4 or above Android emulators or devices, we only have to launch the application

and use the DOM explorer, the JavaScript console or the breakpoints as we have seen. We just need to take

Page 27: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

26

into account that all these tools will be available when we run our application and execute

“window.location.reload()” on the JavaScript console.

Inversely, if we launch our application on Android emulator or device versions 2.3.3 to 4.3, we need the

jsHybugger plugin to be able to use any of the debugging methods. You can find more information about

this plugin on its website.

Installing this plugin is very easy—it is done as we have seen in previous sections. You just need to go to

the editor of the configuration file and go to the plugins section. In this case, we will install this plugin via

the “custom” tab, selecting the folder where we have unzipped the file after downloading it from its website:

Once we have installed it, we can then use all the above debugging methods on these versions of Android.

If we are going to run our application on an iOS emulator or device, we can debug it on versions 6, 7 or 8

of the iOS operating system.

If we debug on a physical iOS device, we have an additional requirement, which is to enable the system’s

“Web Inspector” option. We will be able to do this on our device, inside the “Configuration” app, in the

“Safari·Advanced options” section.

The debugging methods available are exactly the same as we saw for the case of Android: breakpoints,

DOM explorer and messages in the JavaScript console.

We need to take into account that to be able to debug applications on iOS emulators or devices, we must

install and start the remote agent and configure Visual Studio to be able to connect to it. This is all explained

in detail on the following MSDN page.

To debug on Windows emulators and devices, the procedure is identical. In this case, it is not necessary

to perform any special configuration action. We simply need to specify a breakpoint and run the application.

We have the DOM explorer as in previous cases, as well as the messages in the JavaScript console.

Page 28: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

27

Frequently Asked Questions

What is the difference between Apache Cordova and PhoneGap? Are they the same thing?

Apache Cordova was born in September 2011. The company Nitobi decided to donate the source code of

their multiplatform mobile development framework, called PhoneGap, to the Apache Software Foundation.

That same year, Nitobi was purchased by Adobe Systems Inc., the PhoneGap name becoming a registered

trademark of it. To avoid legal problems after the acquisition, in February 2012 the Apache Foundation

decided to rename the product, which became known as Cordova.

Today, Apache Cordova and PhoneGap are identical tools, but they have different names and are

downloaded and supported from different websites. It could be said that PhoneGap is a distribution of

Apache Cordova. The only difference is that PhoneGap, being the property of Adobe Systems Inc., has

integration with the compilation services of said company. And at any time they might decide to extend the

product on their own and give it their own tools and features.

An error showed up while building for a platform for the first time?

EXEC : error : ENOENT, no such file or directory

'C:\Users\<username>\.cordova\lib\android\cordova\3.x.x\VERSION'

This seems to be a bug while installing the platform code. As a workaround, go to:

Tools->Options->Tools for Apache Cordova, and under the Cordova Tools menu, choose “Clear Cache”

I just connected my Android Device to my machine and deployed to it. I got a “No Devices Found” error. What happened?

To run on an Android physical device, you must also install the appropriate device-specific OEM driver or

the Google USB driver for Google Nexus devices.

Be sure to accept “Allow USB Debugging” when prompted.

How do I get around Apache Ripple limitations?

Ripple supports a subset of the total functionality available in Apache Cordova. Fortunately, this code can

be used to vary behavior and skip features that are not supported.

Page 29: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

Hybrid mobile apps for ASP.NET developers © 2015 Microsoft Corporation

28

if (typeof (window.tinyHippos) == "undefined") {

// not ripple

} else {

// ripple

}

Ripple popped up an “I Haz Cheeseburger?!?!” message. What happened?

You are using a Cordova plugin or feature that Ripple does not support. Fortunately, you can enter your

own expected API response to test your functionality. If you find the error annoying, use the Ripple

Limitation workaround above.

How can I get access to the native Xcode project used to build? How can I manually build for iOS or use the emulator on a Mac?

After building for a native (non-Ripple) target for any platform, the content of the bld/Debug (or bld/Release

if you did a release build) folder is a standard Cordova Command Line Interface (CLI) project. If you install

node.js and the Cordova CLI (sudo npm install -g [email protected]) on your Mac, you can

then use these tools from a Mac.

See “Exporting a Cordova CLI Project & Accessing Native Projects” at MSDN for additional details.

Page 30: Hybrid mobile apps for ASP.NET developersdownload.microsoft.com/download/8/7/C/87C46084-092A... · Hybrid mobile apps for ASP.NET developers Published: April 2015 Authors: Rafael

The information contained in this document represents the current view of Microsoft Corporation on the issues

discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should

not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of

any information presented after the date of publication.

This white paper is for informational purposes only. Microsoft makes no warranties, express or implied, in this

document.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under

copyright, no part of this document may be reproduced, stored in, or introduced into a retrieval system, or

transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for

any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights

covering subject matter in this document. Except as expressly provided in any written license agreement from

Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights,

or other intellectual property.

© 2015 Microsoft Corporation. All rights reserved.

Microsoft, list Microsoft trademarks used in your white paper alphabetically are either registered trademarks or

trademarks of Microsoft Corporation in the United States and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.