man thinking

Using Visual Studio Tools for Apache Cordova

Visual Studio Tools for Apache Cordova is a great solution if you want to build apps for non-Microsoft platforms, particularly for mobile devices. If you want the ultimate in speed to get up and running then I would still recommend a tool like Telerik AppBuilder (or others like it). Most of these do use Cordova anyway, and they can get you into the stores with the minimum effort.

But this comes at a cost, both financially and in terms of the amount of control you have. The only other option used to be to install all the Cordova tooling by hand. But this is a time consuming and involved process which requires a lot of technology that Microsoft developers are probably not familiar with. With the Visual Studio Tools for Apache Cordova add-in you get all the tooling integrated with your favourite software development IDE. But at the time of writing this is still a CTP (Community Technology Preview) which is a sort of beta. It's still a bit rough round the edges, and if you try to use it in anger you are going to encounter a few problems, particularly when it comes to deploying your apps to the various app stores. This article lists a few of those problems that I have encountered, and the solutions.

QuickCleanJob.jpg


Windows Phone

The Visual Studio Tools for Apache Cordova come from a division of Microsoft, admittedly one that operates somewhat at arm's length from the rest of the organization, called Microsoft Open Technology. So you might think the Windows Phone build process would be silky smooth. 

In fact it does not seem to be completely problem free, and in fairness a lot of people will probably choose to use the 'native' JavaScript project or the Universal project templates to build their Windows and Windows Phone versions. But I can think of a number of reasons for building the Windows Phone version from the Cordova project. Apart from the general consistency and code maintenance advantages, using Cordova also means you have access to the Cordova plug-ins which give you a consistent way of getting at hardware features across the different phone platforms. And in fact there are some hardware features, such as the camera, that are quite a pain to deal with because the JavaScript libraries didn't make it into the WinJS 8.1 release.

Another issue I found is that for some reason the Deploy build command doesn't work correctly when you are side-loading to a physical device for debugging purposes. You have to actually start a debug session on the device, and then it gets copied over. Of course once the app is installed it is possible to start the app on the phone from the Start menu if you need to.

Windows 8

Another bug, or rather a missing file, affects the Windows (Store) version. If you try to deploy to your local machine you will immediately encounter a certificate problem. To get a temporary certificate, Bingle for 'CordovaApp_TemporaryKey.pfx'. Once you have this file, go to Solution Explorer in your project and navigate to res/native. If you have already done a release build at some point there should be a 'windows' folder beneath this, otherwise you will need to create it. Drop your temporary certificate file into this folder. Your app should now deploy locally without problems.

When it is time to generate your Release package to upload to the store we hit another snag. As at CTP3 the process of generating the app manifest is buggy. This means that your package won't be recognised by the Windows store as valid. If you start digging around and look at the .appxmanifest file which the tooling has generated you will see things like '$username

where your company name should be. Oops: I think we can guess what might have happened here. Short of signing our package with our new company name of '$username , we're a bit stuck.

At this point, to understand how to work around the problem, you need to understand what the tooling is actually doing, and that turns out to be rather interesting. If you navigate to bld\\Release\\platforms\\windows beneath your project directory you find there is actually another Visual Studio solution called CordovaApp.sln! The tooling has generated this native app automatically, which contains both the Windows and Windows Phone projects as a Windows Universal App with a shared project. The interesting thing is that as you dig around the platforms directory you can also see the native Android build. Knowing where to find the native build directories gives an opportunity to take more control over the build process if we ever need to.

Now that we have our hands on the native Windows project we can use the Store package creation wizard. To do this, make sure your Windows project is selected in Solution Explorer and go to the context menu or the Project menu, choose Store and then "Create App Packages...". The Project menu leads you to a few more options where you can do things like reserve an app name if you have not already done so. Once you have started the Create App Packages wizard you should just need to go through the steps which include signing in to the store, including a rather irritating two-factor authentication step. The wizard will automatically synchronize all the app manifest details with whatever they need to be to get the app package successfully uploaded to the store. The wizard communicates with the Windows Store and will actually manage the upload process. This is a workaround of course, so it is not ideal and your changes will be expunged the next time you build the main Cordova solution, and no doubt this problem will be fixed in a future update. You can see a more detailed explanation here: http://stackoverflow.com/questions/27462133/appxmanifest-file-not-being-generated-correctly.


Android

Whenever you build your app for the Android target other than the Ripple emulator, a package is created in the form of a file with the .apk extension. It might not be obvious where it is so you will need to navigate from your project root directory down to bin\\Android\\. There you will find a file with the .apk extension which you can copy to a device and use to install the app in a side-loading fashion. This cannot be used to distribute your app through the Google Play store - for that you first need to create a Release build, whereupon a file will appear in Debug or bin\\Android\\Release. This still can't be used in the store though because it is an unsigned .apk file. There are some extra steps required to sign your app for distribution.

The easiest way to do this is from the console. Start a console app in the res/native/android directory of your project and create a 'key store':

$keytool -genkey -v -keystore release.keystore -alias android -keyalg RSA -keysize 2048 -validity 10000

The alias is a name you will use later to sign your app, so you may want to make it something appropriate. When you run this command you will be prompted for the Distinguished Name fields associated with your key and a password. The keystore file can be saved in source control, although if the repository is public you might prefer not to.

Now, in Visual Studio, go to the res/native/android folder in Solution Explorer and open the file ant.properties (or use some other editor). You will need to set values here so it will look something like:

key.store=release.keystore
key.alias=android
key.store.password=mysecretpassword
key.alias.password=mysecretpassword

Because we created the keystore in the res/native/android folder we don't need to figure out some complex relative path in the first line. Now the next time you build a release version of your app it will sign your .apk file with the credentials in the keystore.

iOS

I have yet to try deploying to iOS. Part of the problem is that you need to buy some extra hardware and install (although not necessarily directly use) software.

Firstly you require a build server that is running Mac OS X Mavericks (or later), XCode 6 (the Apple development environment), the XCode command-line tools and Node.js. Obviously this means acquiring an Apple Mac computer if you don't already have one. If you don't particularly want to use Apple hardware for anything else then the lowest cost route is to buy an Intel-based Mac Mini. The models from 2009 onwards are able to run OS X Mavericks.

You also need to have an active iOS Developer Program account which at the time of writing costs $99 per year. For a corporate account you need a DUNS number (Dunn and Bradstreet), and there is a verification process that takes about a week. The Developer Program allows you to download a provisioning profile certificate to install on your development machine.

Note that an alternative is to find a company that provides a build server for you, although the ones I checked seemed quite expensive. Once you have all this set up you can get Visual Studio to use your Mac computer as a remote build server.

You still need to jump through some hoops to get your app signed. This will require creating a provisioning profile for your app through the Apple Developer portal. You also need to go into Xcode (the Apple development environment) and configure your Apple ID. There is more information at: https://msdn.microsoft.com/en-us/library/dn757048.aspx.

Graphics Assets

When it comes to deploying to the various stores one of the most tedious tasks is to create the various assets such as icons and screenshots and text descriptions. For some reason the various stores require these in a seemingly endless variety of sizes and formats. To make matters worse, the assets that are created in the default project are incorrectly named in a lot of cases. I recommend making sure the file names and sizes match those listed on this page from the documentation which seem to be more accurate (although there are errors - the SplashScreenImage.png under screens/wp8 should in fact be SplashScreenImage.jpg and in JPEG format).

So to try and make this job a bit easier you can use this image generator.

This should work in most browsers (I recommend Chrome) and will generate all the image sizes you need, all running in the client - you don't need to upload anything to our servers. If you download the zip file the images are already organised into a "res" folder structure that matches the Visual Studio project structure, so you can just drop this onto your existing folder and replace all the default files and add any new ones that are needed. There's also an "assets" folder containing images ready for adding to the various stores. Over time the app store vendors will probably add some additional formats and I will try to keep the tool up-to-date, but you may find that you still have to do a bit of messing around in Paint.net to get everything they need.

Conclusions

Visual Studio Tools for Apache Cordova is still effectively a beta product at the time of writing. But it is such a time-saver when setting up your development environment that I would recommend using it if you have decided to build on the Apache Cordova hybrid cross-platform development framework. Even if you decide not to use the project template and use the Cordova command line instead, the tooling is still a great option to get everything you need installed.

Once you understand what this tooling is doing you can see how the native builds are created, so we don't need to be too worried about being 'locked in' to a particular tool chain. This is always a concern with some of the other cross-platform frameworks that 'automatically' generate packages for various platforms and you are not quite sure what they are doing.

By the time you read this, many of the issues mentioned above may have been resolved, particularly if it has reached 'RTM'. Perhaps 'released' is the wrong word, because one could imagine it could well continue to be supported as a community project backed by Microsoft rather than be incorporated as part of the Visual Studio product. We will have to wait and see.