Debugging Hybrid WebApps in VS2015

The biggest challenge when working with a C# app that invokes JavaScript functions is that the debugger by default will only attach to the C# code and show an unhandled exception that isn’t very helpful any time something goes wrong in JavaScript:

In Visual Studio 2015, the solution for this is to switch debugging modes so that instead of the debugger monitoring our managed C# code, it’s monitoring our JS context instead.

You can do this by setting the Application process under Debugger type to Script:

Now when you debug the app and run into a JS exception, the debugger will stop and you’ll have full code context:

This includes inspecting the values of variables, stepping into/out of code and doing basically anything you’d normally want to do with the debugger in a JS app.

Crafting Hybrid WebApps

A good Hybrid WebApp is one that feels more app than website and most importantly, presents a compelling reason to use the app instead of opening the website in a browser.

Lets avoid creating websites in a box, ok?

In order to become masters of our craft and create a great experience for our end users, we’ll need a solid understanding of the website the app will be based on.

As we don’t always have access to server-side code or an ability to customise the delivery of the website to better suit our app, this typically results in a trip to the DOM Inspector and Javascript console to:

  1. Decide which elements don’t make sense in our app. These typically include footers, links to download apps (we’re already in an app!), navigation items, etc
  2. Decide which features of a native app, such as secondary tile pinning, background audio, etc make sense to support
  3. Look for nice JavaScript objects that we can reuse as data sources for our app (ie: model objects)
  4. Look for nice JavaScript functions that we can call to perform tasks such as authentication

The way I typically do this is a combination of the IE dev tools:

And Visual Studio DOM Explorer:

For Windows Phone I tend to use the Visual Studio DOM explorer more as it loads the site in the emulator, if you weren’t aware you can debug a website in any of the Windows Phone emulators via:

Once we have an idea of our integration, start mocking it up live in the tools mentioned above (IE Dev tools, DOM Explorer).

In practice my environment looks something like this when I’m starting to work on a new Hybrid WebApp (although usually across multiple screens):

Then as I work out a new style change, I copy it over to app.css. Likewise for scripts, which end up in app.js.

Website in a box

Someone recently asked me to describe what I mean by:

“Website in a box”

Consider the following image:

It’s an old English post box.

If we think about the primary purpose of a post box, it’s to allow the general public to place letters (messages) inside a slot (message channel), while preventing any of those letters being retrieved by members of the general public once they’ve been placed into the slot.

Now imagine:

  1. Those letters are commands
  2. The post box is the native host app
  3. The website lives inside the post box

With this in mind from the developers perspective, we can only send commands to the website – the website has no real ability to respond.

As a result, this limits the interaction model between user and app, thus I effectively have a website in a box.

HybridWebApp Framework

After some work I did last year took me deep into the realm of merging website + app, I decided to take some of those learnings and build a reusable framework and imaginatively named it the HybridWebApp Framework.

Below is a little history on the problems the framework overcomes and some links so you can start building great Hybrid WebApps today 🙂

The problem

Most WebApps I saw being developed were little more than a website in a box – my challenge was to go beyond this in a significant way and create an app based on a website that really felt like an app as opposed to the typical 1 part WebView, 1 part CSS approach.

If we consider the interaction model between website and app in the most basic website in a box implementation, it looks something like this:

Unsurprisingly, this rarely results in a good end user experience as it is simply a recreation of the website with some minor tweaks, housed in a basic app. There is very little ability to interact with OS light up features under this model and even the most basic of tasks such as pinning secondary tiles is challenging.

This begs the question: Why would an end user want to use this type of app instead of the website when they offer largely the same experience?

The solution

From the above we can deduce that the website needs to be able to communicate easily back to the host app so that the host app can take advantage of the content!

This is already possible through the use of ScriptNotify, however there is one important caveat in Windows 8.1: the website and all of it’s content must be hosted over HTTPS, which isn’t always the case.

This is where the HybridWebApp Framework comes into play, creating a structured way for the website and the host to communicate bi-directionally, so our interaction model looks more like this:

In practice this means developers can write some JavaScript, executed on demand, that sends some data back to the host app.

With this in mind, lets imagine a recipe website as a hybrid app where we want to implement a secondary tile feature that pins the current recipe to the start screen of the device.

The implementation:

  1. The user taps the Pin icon in the app which invokes a JavaScript function app.pinRecipe()
  2. The app.pinRecipe() function reads the DOM, finds the title of the current recipe, the URI to the image and some other info that should be displayed on the tile
  3. The function then uses framework.scriptNotify to send a JSON object that contains this info to the host app which then converts the JSON into a C# model instance
  4. The host app takes that C# model and generates a secondary tile as usual.

Voila! Dynamically generated live tile is now on the start screen and user is happy.


The simplest way to use the HybridWebApp Framework and/or the Toolkit (Toolkit approach is strongly recommended) is to grab them from NuGet:


HybridWebApp.Toolkit (Recommended)

You can also reference the source directly, clone from the GitHub project located here:

Rather than regurgitating what is already posted on the Wiki, please see to get started building great Hybrid WebApps 🙂