Prepare ASP.NET Core projects to use TypeScript

Now a days many ASP.NET developers use TypeScript for their client side code. So, it's worth to add TypeScript in your web development skill-set. If you are a beginner new to TypeScript this multipart series consisting of articles and videos is just for you. In this series I am going to introduce you with the fundamentals of TypeScript language and how to integrate it in your ASP.NET Core apps. I am going to assume that you use Visual Studio 2019 as the IDE for your web development and you are familiar with the basics of JavaScript programming.

Before I go into the details of preparing your TypeScript development environment, let me quickly introduce you to TypeScript.

Simply put, TypeScript is a language that provides many additional features to the traditional JavaScript. In that sense TypeScript is a superset of JavaScript. This also means that you can use all JavaScript programming constructs in TypeScript. Although TypeScript offers plethora of features, a few of them are worth highlighting:

• TypeScript is a strongly typed language. This means you can declare variables to be of a specific data type such as integer, string or complex type.
• TypeScript brings object orientation to your JavaScript code. You can create classes and interfaces similar to other OO languages like C#.
• TypeScript is a compiled language. Your TypeScript code is not directly used by the browser. It is first compiled to produce JavaScript. The resultant JavaScript is then used by the browser. This compiled nature traps many errors at an early stage, before they reach the browser.
• TypeScript can be used with existing libraries and frameworks. For example, you can use jQuery library in TypeScript. Some frameworks such as Angular heavily rely on TypeScript for app development.
• TypeScript is an open source project backed by Microsoft.

Now that you have some idea about TypeScript and what it can do, lets proceed to configure Visual Studio IDE so that you can start your development in TypeScript.

First, you need to do download and install the latest TypeScript SDK on your development machine. You can download it here. Make sure to click on the Visual Studio 2019 link and download the SDK installer.

For example, the following figure shows the download page for TypeScript 3.7.2

Then open Visual Studio and create a new ASP.NET Core MVC project. The following figure shows the newly created project in the Solution Explorer. 

Then right click on the project in the Solution Explorer and open the Properties page. 

Notice the TypeScript Build tab on the Properties page. This tab allows you to configure various TypeScript related settings of Visual Studio. Especially notice the TypeScript version dropdown list at the top. Using this list you can specify the version of TypeScript compiler used for this project. You can have multiple installations of TypeScript SDK on your development machine. For example, the figure shows that SDKs for version 3.7 and 3.8 are installed. You can pick a specific version for your project. You can also pick "Use latest available" option to use the latest available version of the TypeScript compiler.

Once you pick a version the following configuration is added to the project file (.csproj):

<PropertyGroup>
  <TargetFramework>netcoreapp3.1</TargetFramework>
  <TypeScriptToolsVersion>Latest</TypeScriptToolsVersion>
</PropertyGroup>

Notice the <TypeScriptToolsVersion> element that specifies the TypeScript version (Latest in this case). 

There is another way to indicate the TypeScript version to be used. You can add Microsoft.TypeScript.MSBuild NuGet package in the project. This NuGet package adds an MSBuild task and TypeScript compiler to the project. Depending on the version of this NuGet package the matching version of TypeScript will be automatically used. Moreover, the editor experience is configured using the NuGet package rather than TypeScript SDK.

The above figure shows version 3.8 of Microsoft.TypeScript.MSBuild package and corresponds to version 3.8 of TypeScript compiler. After adding this NuGet package the Properties page will automatically reflect the presence of this NuGet package.

As you can see, the TypeScript version dropdown list is now disabled and shows 3.8 (NuGet) as the selection. This is due to the NuGet package you just added. As per the official documentation here adding NuGet package is the recommended way to add the MSBuild task and to indicate the TypeScript version number.

If you specify the TypeScript version using the NuGet package mentioned above, the <TypeScriptToolsVersion> element is not added to the project file.

If you build your ASP.NET Core projects from .NET CLI (using commands such as dotnet build) then you will find this NuGet package handy. The MSBuild task added by this NuGet package ensures that the TypeScript code from your project is also compiled when the project is built from the CLI.

So far so good.

Now, it's time to write some TypeScript code.

Add a new folder under wwwroot named TypeScript. Then open the Add New Item dialog and add a new TypeScript file called HelloWorld.ts into the TypeScript folder.

At this stage your TypeScript folder will look like this:

Now, write the following code in the HelloWorld.ts file:

function HelloWorld() {
    document.getElementById("msg")
   .innerHTML = "<h1>Hello World!</h1>";
}

The HelloWorld() is a simple JavaScript function that grabs an element whose ID is msg. This is done using the getElementById() method. Then innerHTML property of the element is set to the desired message.

Then save the TypeScript file. As you save the file you will find that automatically Visual Studio compiles it to produce HelloWorld.js

Next, add a new HTML file named Index.html in the TypeScript folder. And write the following markup into it.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title></title>
</head>
<body onload="HelloWorld()">
    <div id="msg"></div>
    <script src="/TypeScript/HelloWorld.js">
    </script>
</body>
</html>

Notice the markup shown in bold letters. The onload attribute of the <body> is set to HelloWorld() so that whenever the document is loaded in the browser it will call the HelloWorld() function. Inside, there is a <div> element with ID msg. Just before the </body> tag you add the <script> element that points to the HelloWorld.js file. Remember, you need to point to the .js file, not to the .ts file.

At this stage your TypeScript folder looks like this:

Save the Index.html file and run it in the browser. The following figure shows a sample output.

In the preceding example HelloWorld.js file got created in the same folder as that of HelloWorld.ts. What if you want to store the resultant .js files in a separate folder? To accomplish this task you need to tell the TypeScript compiler about your intention. Let's do that.

Add a new TypeScript JSON Configuration file in the TypeScript folder named tsconfig.json

The name of this file must be tsconfig.json and it contains TypeScript compiler settings.

Modify this file as shown below:

{
  "compilerOptions": {
    "noImplicitAny": false,
    "noEmitOnError": true,
    "removeComments": false,
    "sourceMap": true,
    "target": "es5",
    "outDir": "./Output"
  },
  "compileOnSave": true,
  "exclude": [
    "node_modules",
    "wwwroot"
  ]
}

Notice the outDir setting. This setting governs the output folder and is set to TypeScript > Output folder. Make sure to add the Output folder. Also notice that compileOnSave is set to true indicating that saving the .ts file will cause its compilation.

This time you will find that HelloWorld.js gets created under TypeScript > Out folder as shown below:

Before you run the Index.html file again make sure change the <script> element to reflect the correct path of .js file.

You can also watch the companion video of this article where I am showing the Visual Studio configuration and also developing the example discussed above.

That's it for now! Keep coding!!