Adding typescript to ASP.NET 2 WebForms project

If you are burdened with the technical debt of an old ASP.NET 2 Webforms project, then the chances are that you might not have had the chance to stay up-to-date with JavaScript revolution. A lot has changed with JavaScript in the past few years, and keeping up is a significant effort. So what should you do?

tl;dr

There is no silver bullet. You’ll need to take some time out to update your skills if you want to make use of the new standards and frameworks but it is possible to start incrementally updating an older application without doing a complete rewrite.

So what do you need to understand?…

JavaScript Standards

If you do not know what ES5 or ES6 are – read this blog post first.

When you first created your ASP.NET 2 application you would have been targetting a JavaScript standard known as ES5 (you might not have even known that you were using JavaScript at the time, but it is baked into the WebForms framework for handling postbacks).

Important point: Different browsers support different versions of the JavaScript standards. Generally speaking ES5 is considered as supported everywhere.

If you want to check if a JS standard  is supported in a specific browser then use the compatibility tables, for example:

• ES5 – https://kangax.github.io/compat-table/es5/
• ES6 – https://kangax.github.io/compat-table/es6/
• ES2016+ – http://kangax.github.io/compat-table/es2016plus/

If you need to use a specific feature the you can make use of the website caniuse.com, for example:

• ES6 classes – https://caniuse.com/#search=classes
• let variable – https://caniuse.com/#search=let
• Service worker – https://caniuse.com/#search=service%20worker

So we now know that there are different versions of JavaScript and the more recent versions are “better” than the older versions, but also that the newer versions aren’t supported across the board.

This means that you can’t use the later versions if you still have users on older browsers. We already know that you are supporting an ASP.NET 2 application, which means that

• It is a legacy application, so there is a fair chance that means that it is still used by people on older browsers that don’t support ES6+.
• You are user driven and can’t force them to upgrade – perhaps they are corporate clients and pretty much dicate the terms.

This is where you need to learn about compilation and transpilation…

Compilers and Transpilers

Transpilers (or source-to-source compilers) take code in one language and convert it to another language. Fortunately for us there are plenty of compilers that can convert scripts between different versions of JavaScript. You are likely to have heard of the following:

Transpilers

• Babel – a transpiler best known for its ability to turn ES6 into ES5
• Webpack – a JS transpiler and CSS transpiler (LESS/SASS) and minifier

Which one should you use? A very opinionated area and seeing as we are developing ASP.NET then my opinion is to use the hidden third option – Visual Studio 2017. This will also transpile, bundle and minify CSS and JS. Unless you have need to use an alternative you may as well use the features within VS 2017 to keep life simple.

Supersets

• TypeScript – a strongly typed superset of JavaScript that compiles to JavaScript.
• CoffeeScript – a superset of JavaScript that compiles into JavaScript

Which one should you use? This is a very opinionated area and my opinion is that TypeScript is the way to go based on the following.

• TypeScript is managed by Microsoft (you are using ASP.NET WebForms so this should sit well with your current tech-stack)
• TypeScript is at the heart of Angular, so it is also embraced by Google and their tech-stack
• TypeScript is baked in to Visual Studio and VS Code – you don’t need to use Babel
• TypeScript is a compiler and a type checker (which Babel is not)
• Type checking capabilities are very important for large code bases
• TypeScript will compile to ES3, ES5, ES6, ES2016, ES2017 or ESNext

For more information on transpilation read this blog post.

Command line

Pretty much all modern frameworks and libraries are used via the command line (usually referred to as CLI – Command Line Interface).

It is a big shift in the way you normally work, but it is powerful and quick. By building CLI tooling developers are able to iterate (and deal with cross platform) much faster than if they had to supporing complex UI’s and multiple IDE’s.

Accept it. Learn it. Love it.

Upgrade steps

Depending on the exact details and structure of your application your steps might vary. The following is a guide to the steps that might be involved.

Update Visual Studio

Whilst I love VS Code for simple web apps, testing and proof of concept, Visual Studio is still my go-to editor for WebForms.

To get the latest support for TypeScript you will need to use the latest version of Visual Studio.

Update the solution

• Make sure you are starting from a firm foundation – build and check-in your code without any changes using your current IDE. This is your fallback if something goes wrong.
• Open the project in VS2017. Certain files will be updated (solution, project etc), so you’ll need to build and test again. Do this before making any further changes.

Install Web Essentials

If you don’t already have it, install the Web Essentials 2017 extensions into Visual Studio. This extension will deal with the JS tranpilation that you need.

For more information see the Web Essentials website.

Install Typescript 2.6 SDK

There are a few tricks getting Typescript checked / installed / updated.

Useful commands:

• tsc -v – what version of the TypeScript compiler is running
• where tsc – where are the installed versions of the TypeScript compiler
• npm install -g typescript – install / update TypeScript as a node module
• npm upgrade -g typescript – install / update TypeScript as a node module

TypeScript 2.6 and VS2017 will automatically infer the shared types between files – it is no longer necessary to use triple-slashreferences for types.

See https://docs.microsoft.com/en-us/visualstudio/ide/javascript-intellisense#Auto

After transpilation you will want to bundle your files. These can be done with a bundleconfig.json file.

NOTE: JS files are bundled in the order they are listed, so add base classes first.

Build, test & commit

At this point follow your usual process to build, test and commit your changes. This is a good point to fall back to if the something goes wrong in the subsequent steps.