Performing OCR with Azure Cognitive Services and HTML5 Media Capture API

There are a few ways to access camera on mobile devices during application development. In our previous post, we used the getUserMedia API for camera access. Unfortunately, as of this writing, not all browsers support this API, so we should provide a fallback approach. On the other hand, HTML5 Media Capture API is backed by almost of all modern browsers, which we can utilise with ease. In this post, we’re going to use Vue.js, TypeScript and ASP.NET Core to build an SPA that performs OCR using Azure Cognitive Service and HTML Media Capture API.

The sample code used in this post can be found here.

Vision API – Azure Cognitive Services

Cognitive Services is an intelligence service provided by Azure and uses machine learning resources. Vision API is a part of Cognitive Services to analyse pictures and videos. It performs analysis of expressions, ages and so on from someone or something in pictures or videos. It even extracts texts from them, which is OCR feature. Previously it was known as Project Oxford, while it was renamed to Cognitive Services when it came out for public preview. Therefore, the NuGet package still has its title of ProjectOxford.

HTML Media Capture API

Media Capture API is one of HTML5 features. It enables us to access to camera or microphone on our mobile devices. According to the W3 document, this is just an extension of the existing input tag with the type="file" attribute. Hence, by adding both accept="image/*" and capture="camera" attributes to the input tag, we can use the Media Capture API straight away on our mobile devices.

Of course, this doesn’t interrupt on existing user experiences for desktop browsers. In fact, this link confirms how the Media Capture API works on either desktop or mobile browsers.

ASP.NET Core Web API

The image file passed from the front-end side is handled by the IFormFile interface in ASP.NET Core.

Well, theory is enough. Let’s make it!

Prerequisites

  • ASP.NET Core application from the previous post
  • Computer, tablet or smart phone having camera

Implementing Vue Component – Ocr.vue

First of all, we need a Vue component for OCR. This component is as simple as to have an input element, a button element, an img element, and a textarea element.

If we put the ref attribute on each element above, the Vue component can directly handle it. The button element binds the onclick event with the event handler, getText. Ocr.ts contains the actual logic to pass image data to the back-end server.

Like this previous post, in order to use dependency injection (DI), we create a Symbols instance and use it. axios is injected from the top-most component, App.vue, which will be touched later in this post.

We also create a FormData instance to pass the image file extracted from the input element, through an AJAX request. This image data then will be analysed by Azure Cognitive Services.

Updating Vue Component – Hello.vue

Ocr.vue is now combined with Hello.vue as a child component.

Dependency Injection – App.vue

The axios instance is provided at the top-most component, App.vue, which is consumed its child components. Let’s see how it’s implemented.

We use the symbol instance as a key and provide it as a dependency.

Everything on the front-end side is done. Let’s move onto the back-end side.

Subscribing Azure Cognitive Service

We need to firstly subscribe Azure Cognitive Service. This can be done through Azure Portal like:

At the time of this writing, Azure Cognitive Services are in public preview, which we only can choose the West US region. Choose Computer Vision API (preview) for API Type and F0 (free) for Pricing Tier. Make sure that we only can have ONE F0 tier in ONE subscription for ONE API type.

It takes about 10 minutes to activate the subscription key. In the meantime, let’s develop the actual logic.

Developing Web API – ProjectOxford Vision API

This is relatively easy. Just use the HttpClient class to directly call REST API. Alternatively, ProjectOxford – Vision API NuGet package even makes our lives easier to call the Vision API. Here’s the sample code.

The IFormFile instance takes the data passed from the front-end through the FormData instance. For some reason, if the IFormFile instance is null, the same data sitting in the Request.Form.Files also needs to be checked. Put the API key to access to the Vision API. The VisionServiceClient actually returns the image analysis result, which is included to the JSON response.

We’ve completed development on both front-end and back-end sides. Let’s run this app and access it from our mobile device. The following video clip shows how iPhone takes a photo, sends it to the app, and gets the result.

So far, we’ve briefly looked at Azure Cognitive Services – Vision API for OCR implementation. In fact, depending on the original source images, the analysis quality varies. In the video clip above, the result is very accurate. However, if there are outlines around the text, or contrast between text and its background is very low, the quality significantly drops. In addition to this, CAPTCHA-like images don’t return satisfactory results. Once after Cognitive Services performs enough learning with substantial number of sources, the quality becomes high. It’ll be just matter of time.

Dependency Injection in Vue.js App with TypeScript

Dependency management is one of critical points while developing applications. In the back-end world, there are many IoC container libraries that we can make use of, like Autofac, Ninject, etc. Similarly, many modern front-end frameworks also provide DI features. However, those features work way differently from how back-end libraries do. In this post, we’re going to use TypeScript and Vue.js for development and apply an IoC container library called InversifyJS that offers very similar development experiences to back-end application development.

The code samples used in this post can be found here.

provide/inject Pair in VueJs

According to the official document, vue@2.2.0 supports DI feature using the provide/inject pair. Here’s how DI works in VueJs. First of all, declare dependency, MyDependency in the parent component like:

Then its child component consumes the dependency like:

Maybe someone from the back-end development got a question. Child components only consumes dependencies that are declared from their parent component. In other words, in order for all components to consume all dependencies, this declaration MUST be done at the top-level component of its hierarchy. That’s the main difference between VueJs and other back-end IoC containers. There’s another question – VueJs doesn’t provide a solution for inter-dependency issue. This inter-dependency should be solved by a third-party library. But that’s fine. We’re going to use TypeScript anyway, which has a solution for the inter-dependency issue.

DI in VueJs and TypeScript

Evan You, the creator of VueJs, has recently left a comment about his design philosophy on VueJs framework.

While using a class-based API by default may make it more “friendly” to devs used to classes, it also makes it more hostile to a large group of users who use Vue without build tools or transpilers. When you are advocating your preference, you might be missing some nuance we have to take into account as a framework.

This is why we offer the object-based API as the baseline and the class-based API as an opt-in. This allows us to cater to both groups of users.

Therefore, we need to sort out either using the provide/inject pair or using another approach, ie. service locator pattern. In order to use the provide/inject pair, as we found above, we need to put an IoC container instance at the top-level of component. On the other hand, we can simply use the container as a service locator. Before applying either approach, let’s implement the IoC container.

Building IoC Container using InversifyJS

InversifyJS is a TypeScript library for IoC container, which is heavily influenced from Ninject. Therefore syntax is very similar to each other. Interface and class samples used here is merely modified from both libraries’ conventions – yeah, the ninja stuff!

Defining Interfaces

Let’s define Weapon and Warrior interfaces like below:

Defining Models

InversifyJS uses Symbol to resolve instances. This is a sample code to define multiple symbols in one object. This object contains multiple symbols for Warrior, Weapon and Container.

The @injectable decorator provided by InversifyJS defines classes that are bound into an IoC container.

The @inject decorator goes to constructor parameters. Make sure that those parameters require the Symbol objects defined earlier.

Make sure that we should use the same Symbol object defined earlier. If we simply use Symbol("Weapon") here, it wouldn’t be working as each Symbol object is immutable.

Implementing IoC Container

Let’s implement the IoC container using the interfaces and models above.

The last part of the code snippet above, container.bind(...).to(...), is very similar to how IoC container works in C#. Now we’re ready for use of this container.

Attaching Child Component

Unlike the Previous Posts, We’re adding a new child Vue component, Ninja.vue to Hello.vue for dependency injection.

Hello.vue has got the Ninja.vue component as its child. Let’s have a look at the Ninja.vue component.

Now, let’s apply both service locator and provide/inject pair.

Applying Service Locator

We’re updating the Ninja.vue to use service locator:

As we can see above, the IoC container instance, container is directly consumed within the Ninja.vue component. When we run the application, the result might be looking like:

As some of us might uncomfortable to use the service locator pattern, now we’re applying the built-in provide/inject pair.

Applying provide/inject Pair

As we identified above, in order to consume all dependencies at all Vue components, we should declare IoC container as a dependency at the top-level of the component, ie) App.vue.

We can see that the container instance is provided with the symbol, SERVICE_IDENTIFIER.CONTAINER defined earlier. Now let’s modify the Ninja.vue component:

The @Inject decorator takes care of injecting the container instance from the App.vue component. Make sure that the same symbol, SERVICE_IDENTIFIER.CONTAINER is used. All good! Now we can see the same result like the picture above.

So far, we’ve had an overview how to use DI in VueJs & TypeScript app in two different approaches – service locator or provide/inject pair. Which one to choose? It’s all up to you.

Accessing to Geolocation on Mobile Devices from ASP.NET Core Application in Vue.js and TypeScript

In the previous post, we used HTML5 getUserMedia() API to access camera on our mobile devices. In this post, we’re using geolocation data on our mobile devices.

The code samples used for this post can be found here.

navigator.geolocation API

Unlike getUserMedia() API, geolocation API has a great level of compatibility of almost all browsers.

Therefore, with a simple TypeScript code, we can easily use the geolocation data.

NOTE: In order to use the geolocation API, the device must be connected to the Internet. Also, each browser vendor uses its own mechanism to get geolocation data, which will cause different result even in the same device. This article gives us more details.

Prerequisites

  • ASP.NET Core App from the previous post
  • Computer or mobile devices that can access to the Internet through Wi-Fi or mobile network

NOTE 1: We use vue@2.2.2 and typescript@2.2.1 in this post. There are breaking changes on VueJs for TypeScript, so it’s always a good idea to check out the official guideline.

NOTE 2: Code samples used in this post were from the MDN document that was altered to fit in TypeScript.

Updating Hello.vue

In order to display latitude, longitude and altitude retrieved from the geolocation API, we need to update the Hello.vue file:

That’s pretty much self descriptive – clicking or tapping the Get Location button will display those geolocation data. Let’s move onto the logic side.

Updating Hello.ts

The Get Location button is bound with the getLocation() event, which needs to be implemented like below:

First of all, we need to declare properties for latitude, longitude and altitude, followed by the getLocation() method. Let’s dig into it.

  • First of all, we check the navigator.geolocation isntance if the web browser supports geolocation API or not.
  • Call getCurrentPosition() method to get the current position. This method then passes two callback methods and an option instance as its parameters.
  • Callback method, success(), passes the position instance containing current position details and binds co-ordinates to the browser.
  • error() callback handles error.
  • options instance provides options for the geolocation API.

NOTE Each callback method has its return type, according to the type definition, which is not necessary. Therefore, we just return null

The options instance used above is actually an interface type of PositonOptions that needs to be implemented. Its implementation might be looking like below:

We completed the TypeScript part. Let’s run the app!

Results

When we use a web browser within our dev machine, it firstly asks us to get a permission to use our location data:

Click Allow and we’ll see the result.

This time, let’s do it on a mobile browser. This is taken from Chrome for iPhone. It also asks us a permission to use geolocation data.

Once tapping the OK button, we can see the result.

So far, we’ve briefly looked at the geolocation API to populate current location. That’s not that hard, isn’t it?

If we have more complex scenario, need more accurate location details, or need constant access to the location data even we’re not using the app, then native app might have to be considered. Here’s a good discussion regarding to these concerns. But using HTML5 geolocation API would be enough in majority of cases.

Accessing to Camera on Mobile Devices from ASP.NET Core Application in Vue.js and TypeScript

In the previous post, we built an ASP.NET Core application using Vue.js and TypeScript. As a working example, we’re building a mobile web application. Many modern web browsers supporting HTML5 can access to multimedia devices on users’ computer, smartphones or tablets, such as camera and microphone. The Navigator.getUserMedia() API enables us to access to those resources. In this post, we’re actually going to implement a feature for camera access on our computer and mobile devices, by writing codes in VueJs and TypeScript.

The code samples used for this post can be found here.

getUserMedia() API

Most modern web browsers support this getUserMedia() API, as long as they support HTML5. There are two different APIs around this method – one is Navigator.getUserMedia() that supports callback functions, while the other MediaDevices.getUserMedia(), that came up later, supports Promise so that we can avoid Callback Hell. However, not all browsers support the MediaDevices.getUserMedia(), so we need to support both anyway. For more details around getUserMedia(), we can find some practical samples in this MDN document.

Prerequisites

  • ASP.NET Core application from the previous post
  • Computer, tablet or smartphone having camera

NOTE 1: This post uses VueJs 2.2.1 and TypeScript 2.2.1. VueJs 2.2.1 introduced some breaking changes how it interacts with TypeScript. Please have a look at the official guide document.

NOTE 2: vue-webcam written by @smronju was referenced for camera access, and modified to fit in the TypeScript format.

Update Hello.vue

We need a placeholder for camera access and video streaming. Add the following HTML codes into the template section in Hello.vue.

  • video accepts the camera input. src, width, height and autoplay are bound with the component in Hello.ts. Additionally, we add the ref attribute for the component to recognise the video tag.
  • img is where the camera input is rendered. The photo field is used for data binding.
  • button raises the mouse click or finger tab event by invoking the takePhoto function.

The HTML bits are done. Let’s move on for TypeScript part.

Update Hello.ts

The existing Hello.ts was simple, while this time it’s grown up to handle the camera API. Here’s the bits:

We can see many extra data fields for two-way data binding between user input and application. Some of them comes with their default values so that we don’t have to worry about their initialisation too much.

  • The takePhoto() function creates a virtual DOM for canvas, converts the input signal from the video into an image, and sends it to the img tag to display snapshot.

  • The mounted() event function is invoked when this component, Hello.ts, is mounted to its parent. It uses the getUserMedia() API to bind streaming source to the video tag.
  • The video tag through this.$refs.video is the HTML element that has the ref attribute in Hello.vue. Without the ref attribute, VueJs cannot know where to access to the tag.

NOTE: The original type of the this.$refs instance is { [key: string]: Vue | Element | Vue[] | Element[] }, while we cast it to any. This is to avoid build failure due to the linting error caused by using the original type and accessing to the resource by referencing like this.$refs.video. If we don’t want to cast it to any, we can use this.$refs["video"] instead.

We’ve so far completed the coding part. Now, let’s build this up and run a local IIS Express, and access to the web app through http://localhost:port. It works fine.

This time, instead of localhost, use the IP address. If we want to remotely access to our local dev website, this post would help.

It says we can’t use the camera because of its insecure access. In order to use the getUserMedia() API, we should use HTTPS connection to prevent private data exposure. This only happens when we’re using Google Chrome, not FireFox or Edge. So, just change the connection to HTTPS.

Now we can use IP address for camera access. Once we allow it we can immediately see our face directly on the web like below (yeah, it’s me! lol).

Let’s try this from our mobile devices. The first one is taken from Android phone, followed by the one taken from Windows Phone, then the ones from iPhone. Thanks Boris for help take those pictures!

Errr… what happened on iPhone? The camera is not accessible from both Safari for iOS and Chrome for iOS!!

This is because not all mobile web browsers support the getUserMedia() API.

getUserMedia Browser Compatibility

Here’s the data sheet from http://mobilehtml5.org/.

Unfortunately, we can’t use the getUserMedia API on iOS for now. For iOS users, we have to provide alternative methods for their user experience. There’s another API called HTML Media Capture that is supported by all mobile web browsers. It uses the traditional input type="file" tag. With this, we can access to camera on our mobile devices.

In the next post, we’re going to figure out how to provide a fallback option, if getUserMedia() API is not available.

Remote Access to Local ASP.NET Core Applications from Mobile Devices

One of the most popular tools for ASP.NET or ASP.NET Core application development is IIS Express. We can’t deny it. Unless we need specific requirements, IIS Express is a sort of de-facto web server for debugging on developers’ local machines. With IIS Express, we can easily access to our local web applications with no problem during the debugging time.

There are, however, always cases that we need to access to our locally running website from another web browsers like mobile devices. As we can see the picture above, localhost is the loopback address so we can’t use it outside our dev box. It’s not working by simply replacing the loopback address with a physical IP address. We need to adjust our dev box to allow this traffic. In this post, we’re going to solve this issue by looking at two different approaches.

At the time of writing this post, we’re using Visual Studio (VS) 2015, as VS 2017 will be launched on March 7, 2017.

Network Sharing Options and Windows Firewall

Please make sure that all screenshots for this section are taken from Windows 10. Open my current connected network (either wireless or wired).

Make sure that the “Make this PC discoverable” option is turned on.

This option enables our network in “Private” mode on Windows Firewall:

WARNING!!!: If our PC is currently connected to a public network, for our better security, we need to turn off the private network settings; otherwise our PC will get vulnerable from malicious attacks.

Update Windows Firewall Settings

In this example, the locally running web app uses the port number of 7314. Therefore, we need to register a new inbound firewall rule to allow access through the port number. Open “Windows Firewall with Advanced Security” through Control Panel and create a new rule with options below:

  • Rule Type: Port
  • Protocol: TCP
  • Port Number: 7314
  • Action: Allow the Connection
  • Profile: Private (Domain can also be selected if our PC is bound with domain controllers)
  • Name: Self-descriptive name of anything! eg) IIS Express Port Opener

Now, all traffic through this port number is allowed from now on. So far, we’ve completed the basic environment settings including firewalls. Let’s move onto the first option using IIS Express itself.

1. Updating IIS Express Configurations Directly

When we install VS, IIS Express is also installed at the same time. Its default configuration file is located at somewhere but each solution that VS 2015 creates has its own settings that overwriting the default one and it’s stored to the .vs folder like:

Open applicationhost.config for update.

Add another binding with my local IP address like:

We can easily find our local IP address by running the ipconfig command. We’re using 192.168.1.3 for now.

IIS Express has now been set. Let’s try our mobile web browser to access the local dev website by IP address.

All good! It seems to be working now. However, if we have more web applications running on our dev environment for our development work, every time we create a new web application project, we have to register the port number, allocated by IIS Express, to Windows Firewall. No good. Too repetitive. Is there any other convenient way? Of course there is.

2. Conveyor – Visual Studio Extension

Conveyor can sort out this hassle. At the time of this writing, its version is 1.3.2. After installing this extension, run the debugging mode by typing the F5 key again and we will be able to see a new window like:

The Remote URL is what we’re going to use. In general, the IP address would look like 192.168.xxx.xxx, if we’re in a small network (home, for example), or something different type of IP address type, if we’re in a corporate network. This is the IP address that the mobile devices use. Another important point is Conveyor uses the port number starting from 45455. Whatever port number IIS Express assigns the web application project, Conveyor forwards it to 45455. If 45455 is taken by others, it looks up one and one until a free port number exists. Due to this behaviour, we can easily predict the port number range, instead of the random nature of IIS Express. Therefore, we can register the port number range starting from 45455 to whatever we want, 45500 for example.

Now, we can access to our local dev website by using this port number pool like:

If we’re developing a web application using HTTPS connection, that wouldn’t be an issue. If no self-signed certificate is installed on our local dev machine, Conveyor will install one and that’s it. Visiting the website again through HTTPS connection will display the initial warning message and finally gets the page.

We’ve so far discussed how to remotely access to our local dev website using either IIS Express configuration or Conveyor. Conveyor gets rid of repetitive firewall registration, so it’s worth installing for our web app development.

Writing Vue.js Applications in TypeScript on ASP.NET Core

In the previous post, we’ve briefly walked through how to build Vue.js application on ASP.NET Core. Like other modern JavaScript framework, VueJs also supports TypeScript out-of-the-box. If we can get full benefits from TypeScript to build a VueJs app, it would be awesome! There are many resources referring to the combination of VueJs and TypeScript. However, they are not using the basic template that VueJs provides, which brings about less confidence to those developers who just started using VueJs. Even worse, due to the recent version up of Webpack to 2.x, we might need a new tutorial to build a VueJs application using TypeScript. In this post, our goal will be:

  • To use the basic template provided by VueJs,
  • To use Webpack version 2.x, and
  • To run the app on ASP.NET Core.

The sample code used in this post can be found at here.

Prerequisites

We have already built a VueJs application running on ASP.NET Core in the previous post. So we’re going to re-use that.

Update on March 6th, 2017: We updated the TypeScript version to 2.2.1 for this post.

Installing npm Packages

TypeScript

We can install TypeScript locally only for this application:

Or we can install it globally:

If TypeScript is installed globally, we should link it to this application:

ts-loader

ts-loader offers us to load .ts files to .js file without actually building them during the development time.

vue-class-component & vue-property-decorator

If we want to use .ts in our VueJs development, as the official document recommends, we should install the vue-class-component library for class decorators.

It may be necessary to install vue-property-decorator to extend vue-class-component. This is not relevant to this post, though.

vue-typescript-import-dts

TypeScript needs type definitions. vue-typescript-import-dts helps recognise .vue files as .ts.

All necessary npm packages are installed. Let’s move on.

Configurations for TypeScript

tsconfig.json

In order to use .ts, we firstly need tsconfig.json. In this post we just use the bare minimum settings to work. Further details about tsconfig.json can be found here.

Let me explain the configuration in-depth.

  • VueJs supports ECMAScript 5. Therefore, we need to target TypeScript to es5. It means that module should be CommonJs as well as lib should include dom, es2015 and es2015.promise.
  • types declares custom type definitions. As we’ve installed vue-typescript-import-dts, include it here so that the application can recognise .vue files as .ts files.
  • In order to use class decorators, we’ve installed vue-class-component. But this is not enough. We need to enable it by setting the experimentalDecorators value to be true.
  • Within the include property, we need to declare which directories are considered containing .ts files.

Update on March 6th, 2017 Due to the version update of VueJs to 2.2.x, tsconfig.json also needs to be updated. This is the recommended configuration from the official guide.

Also, please make sure that we create the template from vue-cli by running vue init webpack. It installs vue@2.2.1 and vue-router@2.2.0. If those versions are different, please update them.


.eslintignore

While developing apps in TypeScript, .js files are automatically compiled and generated. But it’s not guaranteed those files comply to linting process. Therefore, we can’t be sure if those generated .js files are ESLint compliant or not. Therefore, to avoid linting errors from those generated .js files, we just turn it off by adding a line, src/**/*.js, to .eslintignore.

We just completed basic configurations for TypeScript compiling. Let’s move on.

Converting JavaScript to TypeScript

It’s time to convert existing .js files in the src directory to .ts ones situated. We’ll only look after both build and src directories.

build/webpack.base.conf.js

As Webpack is the only service to refer this file, so it’s not necessary to change this to .ts. But we do need to modify it.

First of all, the entry point should be changed from main.js to main.ts:

Then we need to replace the babel-loader part with the ts-loader one:

Every .ts file is handled by this loader. Here’s an interesting option, appendTsSuffixTo. If we use this, .vue files can be treated as .ts ones. VueJs uses the Single File Component approach – all HTML section, JavaScript section, and CSS sections are put in one single file called .vue. Therefore we need to handle it to be a TypeScript file, particularly for the JavaScript section.

We’ve completed webpack configuration to enable TypeScript handling. Let’s really convert JavaScript files to TypeScript ones.

src/main.jssrc/main.ts

Change the existing JavaScript syntax to the one for TypeScript like:

Spot on the new Vue({ ... }) part. Instead of template and components, the render function is placed. Everything has been compiled before hitting this point, and each component needs more control by itself, so we just use the render function. For more details about the render function, please refer to the official document.


Updated on March 6th, 2017: Due to the version update of VueJs to 2.2.x, the import statements part needs to be updated like below:


src/router/index.jssrc/router/index.ts

We don’t have to worry about this. Just be cautious when using import ....


Updated on March 6th, 2017: Due to the version update of VueJs to 2.2.x, the import statements part needs to be updated like below:


src/App.vuesrc/App.ts

Instead of using one single .vue file, we’re separating the TypeScript part from each .vue. Why are we doing this, by the way? We can still use .vue indeed. But for better maintainability, we’d better to create a separate .ts file. Let’s have a look how we can implement App.ts that is extracted from App.vue.

@Component decorator contains the name declaration so that the router can easily recognise it. The script part in the original App.vue can be altered like this:

Make sure that we should include lang="ts" as an attribute of the script tag.


Updated on March 6th, 2017: Due to the version update of VueJs to 2.2.x, the import statements part needs to be updated like below:


src/components/Hello.vuesrc/components/Hello.ts

Now, we’re going to extract the script section from Hello.vue to Hello.ts. Let’s have a look.

Likewise, @Component contains the name declaration. Previously all two-way binding fields were defined within the data function. Using properties makes them more class-friendly. Functions became methods.

Maybe someone indicates a small change, comparing to the previous post. In order to use AJAX requests and responses, we used vue-resource. However, it’s changed to axios. According to the official VueJs blog post, vue-resource is no more supported as an official VueJs extension. Instead axios is recommended because of its richer features. In addition to this, axios provides TypeScript definitions, so there’s no reason not to use this. Its usage is almost identical to vue-resource.

Once Hello.ts is extracted, the original Hello.vue should now be changed to:


Updated on March 6th, 2017: Due to the version update of VueJs to 2.2.x, the import statements part needs to be updated like below:


All done for conversion from JavaScript to TypeScript! It seems that we’ve done fairly massive conversion. The basic template is optimised to JavaScript, so what we’ve done so far is basically the conversion job. From now on, we can write all logic using TypeScript!

Press F5 key on your Visual Studio to run the application and see the result.

The right-hand side of the window on the picture above is Vue.js devtools, which is a Chrome extension. When we install it, we can use it right away through Chrome’s Developer Tools.

One More Thing …

So far, we’ve done the conversion of VueJs to TypeScript. As this is for local development environment, we need one last modification for deployment. Here’s the overall process of building applications for deployment:

  1. To compile .ts files and generate corresponding .js ones.
  2. To modularise and build bundles through webpack.
  3. To build ASP.NET Core libraries.
  4. To generate an artifact for deployment to Azure or IIS.
  5. To deploy.

By updating package.json and project.json we can easily achieve this goal.

package.json

Within package.json, the scripts was originally looking like:

We need to add another one for TypeScript compilation. Let’s change it like:

  • build:ts is to compile .ts files.
  • build:main is to be responsible for existing build.
  • build is to change to call both build:ts and build:main consecutively.
  • --no-deprecation flag may bring an attention. When compiling, ts-loader throws a deprecation warning. It’s OK but Visual Studio treats it as an error so build/deploy fails. By providing this flag will enable build/deploy through Visual Studio successfully.

project.json

Finally, open project.json to confirm the prepublish section.

All good now! After the deployment to Azure Web App, we can see the following screen:

Of course, if CI/CD is preferred, we can simply use dotnet publish feature.

We’ve so far had a quick look to write a VueJs application in TypeScript, bundle it on ASP.NET Core and deploy it to Azure. As mentioned earlier, the very first part is a bit complicating but it’s not that different from normal TypeScript development. Let’s build a real world application using VueJs and TypeScript!!

Running Vue.js on ASP.NET Core Applications

Vue.js has recently got many attentions as it is relatively easier to learn and lighter in size, comparing to other popular frameworks like Angular 1, Angular 2 or React. By providing a middleware, ASP.NET Core supports those front-end frameworks such as Angular2, Aurelia, React, Knockout, etc, while Vue has been excluded out-of-the-box. Even though we can find many good articles and code samples to integrate Vue and ASP.NET Core, as they don’t use the basic template that Vue is providing, it’s a little difficult for developers to apply at their first glance, who want to use both Vue and ASP.NET Core with minimum integration efforts. In this post, we are going to integrate Vue.js and ASP.NET Core using their basic templates, with minimum modification.

The code sample used in this post can be found at here.

Microsoft.AspNetCore.SpaServices

In order to support front-end development in ASP.NET Core, Visual Studio uses Bower. However, as we are already aware how fast front-end development environment changes, another option like Webpack helps developers work a lot easier by offering bundling, moduling and so forth. ASP.NET Core, of course supports Webpack as a separate extension. Microsoft.AspNetCore.SpaServices helps developers integrate front-end frameworks using Webpack with ease.

Prerequisites

Throughout this post, we need some preparations:

We can also use Visual Studio Code (VSC), but we’re assuming to use VS for this post.

Creating ASP.NET Core Web Application

Open Visual Studio and create a new ASP.NET Core web application project. As this web application likely uses .NET Core version 1.0.1, we need to update it to 1.1 by updating global.json:

Also, update project.json so that all NuGet packages in the web application can be complied to .NET Core 1.1:

As mentioned earlier, we’re using Webpack instead of Bower, so remove Bower-related configuration files as well as ASP.NET Core native bundling & minification setting files:

  • .bowerrc
  • bower.json
  • bundleconfig.json

And finally, all directories and files under the wwwroot directory need to be deleted. We’re all set now at the ASP.NET Core application side. Let’s add Vue.

Installing Vue.js

We can use Vue as a stand-alone library by simply including the script from CDN. However, if we want to use its powerful features especially for componentising, module bundlers like Webpack should be considered. In order to use Webpack for Vue.js, if node.js and npm have already been installed, install vue-cli:

Then, install the basic template by running the following command:

During installation, just leave all the question as default value and finally template gets installed. Now, run the following command to install all npm packages and run the Vue app:

Since Vue uses the port number of 8080, we can see the result as expected. However, this is just a Vue app running independently, not the one integrated with ASP.NET Core. Let’s move on.

UPDATE on March 6th, 2017: when we run vue-cli using the command vue init webpack, it installs vue@2.2.1. If the version of VueJs is earlier than that, please update as VueJs has some breaking changes on 2.2.x.

Integrating Vue.js with ASP.NET Core

This is the main part of this post. We need to touch configurations at both sides.

Configuring Vue.js

First things first. We need to install the npm package, aspnet-webpack, to enable communication between front-end framework and back-end application through Webpack:

Once installed, update config/index.js to setup the root directory:

And finally, create webpack.config.js and save it to the root directory of the ASP.NET Core project:

We now got Vue.js setup done. What’s next?

Configuring ASP.NET Core

aspnet-webpack corresponding package in the ASP.NET Core side is Microsoft.AspNetCore.SpaServices. Install it through NuGet package manager and register a middleware at Startup.cs:

We also need to add a routing configuration for SPA like above. Is the ASP.NET Core side relatively simple? Let’s punch the F5 key to run the app and see how it’s going.

We now can see a different port number that is handled by the ASP.NET Core app. So, technically we completed integration between Vue.js and ASP.NET Core! How can we ensure if they are actually working together? Let’s implement a basic AJAX call to see whether they get along with each other. Of course further modification is required. Who can stop us?

Handling AJAX Request/Response

As Vue.js core is lightweight, if we want to implement more sophisticated works like handling AJAX request/response, we need to install another npm extension called vue-resource.

Once installed, add it to the Vue instance for use. Update src/main.js like:

Now we need to implement AJAX request/response codes. Open /src/components/Hello.vue and modify it like:

What we can expect from this change is the message Welcome to Your Vue.js App will be replaced with the value from res.body.message. Now we need to implement the Web API. Here’s the Web API controller and action:

All good. Build the app, press the F5 key and confirm the result.

We can see Hello World, instead of the original message.

Side note: Another benefit of using Webpack is Hot Module Replacement (HMR). As long as the app is up and running on our local machine, we can instantly change something and check the result with no time, without reloading the page. Of course, if we install .NET Core Watcher tool, we don’t even need to rebuild and rerun the app itself either.

Deploying App to Azure

We’ve built an ASP.NET Core web application with Vue.js. Now it’s time for deployment. We don’t use View features provided by ASP.NET Core. Instead we just use a static(?) wwwroot/index.html. In our local development, we don’t really have to worry about that as our development environment automatically detects that. However, in a production environment, we have to specify we’re using the static index.html page; otherwise Azure web app can’t recognise it. To enable this feature, we need to update Startup.cs:

Make sure that the UseDefaultFiles() method must always come before the UseStaticFiles() method. Finally update deployment/publish related settings in project.json for Vue.js:

Everything is done! Deploy this web app to Azure and see the result. Can we see it as expected?

So far, we have installed Vue.js, integrated it with ASP.NET Core, implemented whether both are working together or not, and deployed the app to Azure web app instance. Some may think this looks too complicated, but actually, it’s not that tricky. Rather, we’ve got another option on ASP.NET Core application development using a different front-end framework. As long as a new front-end framework emerges and it supports Webpack, we can make it working like this approach. The next post will discuss how to write VueJs apps in TypeScript, running on ASP.NET Core.

Adding YAML Settings into ASP.NET Core Apps

Unlike traditional ASP.NET web apps using web.config for configuration, ASP.NET Core apps supports various file formats for it. When we actually see the source codes, configuration supports XML, JSON, INI, Azure Key Vault, in-memory collection, command line arguments and environment variables. However, another popular format, YAML is not officially supported in ASP.NET Core at the time of writing. In this post, we are going to walk through how we can import YAML settings file to support ASP.NET Core web application.

You can find sample codes used in this post at here

Analysis of ConfigurationBuilder

When we first create a new ASP.NET Core application project, no matter it is a web app or an API app, we can always see how ConfigurationBuilder is implemented.

As we can see above, appsettings.json is included as a default, followed by secret settings, if it’s a development mode, then environment variables. If we want, we can add an XML file by adding builder.AddXmlFile("appsettings.xml"); or an INI file by adding builder.AddIniFile("appsettings.ini");, or others from various sources. In this case, we MUST make sure that the order of adding settings is very important. The settings defined in the latter file always overwrite the settings previously defined. For example, if JSON settings is loaded first then XML settings is loaded later, if a same key exists in both settings files, the value from the XML settings will always be considered.

AddYamlSettings()

As YAML settings is not supported out-of-the-box, we need to implement an extension. As there’s already a NuGet package for this extension, we will just use it. Here are sample appsettings.json and appsettings.yml files:

Now, we’re modifying the existing Startup.cs file to load YAML settings.

The builder.AddYamlFile() method has been added right after the builder.AddJsonFile() method. Therefore, we are expecting the clientId value will be FROM appsettings.yml. Let’s check it out. First of all, we need to inject the settings into a controller. Here’s a code bits to deserialise the settings into a strongly-typed instance and inject into the built-in IoC container.

Now, we need to resolve that instance from the controller level, which is a typical DI stuff.

We’re all set. Let’s run the app and see how it’s going. Can we see the result like below?

Order is Important!

As we’ve dealt above, the latter settings takes precedence for the same key. Now, let’s change between JSON settings and YAML one the other way around like:

Then try the web app again. What can we expect?

So far we have looked how to import/load YAML settings into our ASP.NET Core web apps. Can we use YAML for our ASP.NET Core web app now? Yes, we can!

Implementing HTTP Request Handler on ASP.NET Core Applications

ASP.NET WebForm or MVC applications rely on global.asax to process HTTP request pipelines. Within global.asax, each HTTP request goes through declared HTTP modules and HTTP handlers based on events. On the other hands, ASP.NET Core applications use OWIN middlewares. Actually, those middlewares now take care of what HTTP modules and HTTP handlers do. In this post, we are going to implement an HTTP request handler on a ASP.NET Core application.

Why Does It Matter?

Single Page Applications (SPA) is now a trend of web application development. SPA only contains UI logics and all other business logics are processed by calling APIs. Calling APIs through AJAX is not a problem. For example, if we use jQuery, typical AJAX call will look like:

If we need an API key for the call, the AJAX call might look like:

We might be feeling agitated here because auth key and API key are exposed within the JavaScript block, which is not we want. In this case, we usually implement API proxy (or API facade or whatever we call) so that we hide that sensitive information from the UI side. Instead, the proxy takes care of those details. Well, how can we implement the proxy then? We can implement this proxy through MVC controllers or middlewares. The good thing with middlewares to handle this is that WE DON’T NEED CONTROLLERS AT ALL. Let’s have a look.

Middleware

The main differences between HTTP modules and HTTP handler are:

  • HTTP modules process requests and pass them to another modules.
  • HTTP handlers process requests and return their responses to browsers.

As middlewares in ASP.NET Core take care of both HTTP modules and HTTP handlers, implementation becomes a lot easier and simpler. Here’s a basic middleware looking like:

And, in order to easily use this middleware at Startup.cs, we can just create an extension method like:

And this extension method is placed into the Configure method of Startup.cs like:

Within the OWIN pipeline, middlewares are invoked by an order where they are declared. Therefore, MyMiddleware is invoked after the previous middleware then passes HttpContext instance to the next middleware for further processing. Here’s the clue. If we want to implement the middleware as an HTTP handler, we simply don’t run the this._next.Invoke(context) method so that all HTTP requests complete processing at this point. Let’s make a working example.

All codes used in this post here can be found at: https://github.com/devkimchi/ASP.NET-Core-HTTP-Request-Handler-Sample

HTTP Request Header Handler Middleware

We don’t need MVC controller for our ASP.NET Core application any more because the middleware takes all AJAX requests, put some additional header and pass the requests to API server. Therefore, we can simply remove MVC middleware from the Startup.cs and add HttpRequestHeaderHandlerMiddleware into it.

Then, implement HttpRequestHeaderHandlerMiddleware like:

As we can see above, it processes the request and sends HttpContext back with response. This perfectly works as API proxy, without needing controllers. Let’s go further.

Middleware with Options Pattern

The potential problem of HttpRequestHeaderHandlerMiddleware written above is that all custom headers are hard-coded. If we add/update/delete header values, we have to update the code. Fortunately, ASP.NET Core provides Options Pattern. This is basically for dependency injection for configuration values that are declared within appsettings.json or environment variables. We can use this pattern for our middleware implementation with additional extension methods.

We have HttpRequestHeaderHandlerMiddlewareOptons and this will be injected to HttpRequestHeaderHandlerMiddleware by calling Options.Create(options) method, which creates IOptions instance. Here’s another extension method to declare options with lambda expressions.

Once it’s done, the HttpRequestHeaderHandlerMiddleware needs to be updated to accept the options instance as a parameter.

Now we can use options within our middleware. Those options can be defined within appsettings.json file, populated as a strongly-typed instance and injected to the middleware like:

So far, we have implemented a middleware as an API proxy to capture all HTTP requests, put extra header information into it and process it. With this approach, our SPA backed by ASP.NET Core would be much simpler and light-weighted.

Long Path Error While Publishing ASP.NET Core Applications

If you are writing an ASP.NET Core application, there are chances to publish your app to either a Azure Website or another place, by right-mouse clicking in Visual Studio.

In most cases, it should be alright. However, if your app has a NuGet package with a long name, it would be an issue. You might be seeing an error like this:

DNU(0,0): Error : The specified path, file name, or both are too long. The fully qualified file name must be less than 260 characters, and the directory name must be less than 248 characters.

Yes, this is the notorious PathTooLongException that Windows OS has had. There’s no silver bullet for easy fix for it. In this post, I’ll show you a couple of options that you might consider.

Cause

While creating a package to publish, it uses the following path:

For example, I’m using Justin as my [USERNAME] and my project has a name of MyProject and its full length is 163 then, the package publish path will look like:

In addition to that, an ASP.NET Core application creates three different directories under that path – approot, logs and wwwroot. The approot path actually contains all NuGet packages and DNX runtime library. Here’s the issue arising. If any of NuGet package has a very long name, it can’t be fit into the temp folder. If any node_module has a deeper dependency, it will also throw an error for packaging.

Then, how can we solve the problem? I would suggest two approaches.

Update Environment Variables

There are two environment variables – TEMP and TMP. This determines your temp directory. Therefore, change it to a shorter ones like:

This is the easiest and quickest way to fix the issue. However, the biggest caveat of this approach is that all other applications using those temp folder will be affected and we might have unwanted side effects. We need to find another way that only impacts on my current web application project.

Update .xproj

Fortunately, when you open your .xproj file of your ASP.NET Core application, you will find the line almost at the bottom:

This provides us with a great clue! Let’s find out what we can to do with that Microsoft.DNX.targets file. First of all, open the Microsoft.DNX.targets that is located in C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\v14.0\DNX. It also points another file, $(_WebPublishTargetsPath)\Web\Microsoft.DNX.Publishing.targets that is located in the C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\v14.0\Web directory. Open the file.

Then, find the Global Properties section and you will find:

Here’s the magic property – PublishOutputPathNoTrailingSlash. This property is used at the bottom of that targets file like:

This Dnu node basically emulates the msdeploy.exe so the Out attribute defines the output folder where the package is published. Now, we know what needs to be changed. Within our .xproj file, we can add this PublishOutputPathNoTrailingSlash node like:

Once you add the property, save it and restart your Visual Studio to get this change applied to your ASP.NET Core application project. Run the Publish menu again and it will not fail. This is a better approach comparing to the first one, because it doesn’t impact on other applications on Windows.

Of course, if you use msdeploy by your hand, it wouldn’t be an issue as you can choose the -output value based on your preference.

So far, we have had a walkaround to fix the PathTooLongException issue during the deployment of your ASP.NET Core application. I hope that Microsoft will update Visual Studio that the publish path can be customised by individual project rather than sticking onto the default temp path.