In this tutorial-like write-up, I hope to get people started quickly with an Angular 2 app with TypeScript and ASP.NET Core RC2 in Visual Studio 2015.
From the title I assume only people with Visual Studio 2015 will get here. In addition, we’re gonna need a few things to get going. We will list them and instructions to install them, so if you have a prerequisite already installed, skip the respective portions.
We will try to follow the Angular 2 with TypeScript 5 Minute Quickstart as closely as possible, so that the original page may serve as a reference. However, we will take some deviations, in order to work with Visual Studio 2015 and ASP.NET Core. These are easily identified.
I do not wish to copy-paste their explanations, so if you wish to have more explanations on what is what and why things are the way they are, I would advise you to read the explanations in the above-mentioned link. It is well-written. This guide is just about setting up an Angular 2 with TypeScript and ASP.NET Core in Visual Studio 2015.
Prerequisite: ASP.NET Core SDK
The SDK and the tools to develop ASP.NET Core applications
Head to Microsoft’s Core Downloads Page and follow the simple instructions there to make sure that your RC2 and tools are setup properly. The Visual Studio Installer is the option we’re looking for, and once it’s done, we can move on to the next step.
Prerequisite: Node.js and Node Package Manager (NPM)
If you don’t have node.js installed, head to the Node.js Downloads page and download and run the Windows installer.
If you already have node.js installed, you likely have the npm installed too. Let’s just make sure the versions are up to date. Open your command prompt, and type node -v and press Enter. This gets you the node version. Type npm -version to get the version of the npm installed. I recommend getting the highest versions (node.js v6.2.1 and npm v3.9.3 as of writing).
The build system that we need to get our current setup started
We are going to have to go through a few hoops with Visual Studio 2015 projects working a bit differently than how IDEs like Sublime Text or Visual Studio Code work, so we need Gulp.js. Gulp.js is a streaming build system. Now that we have npm installed, we can install gulp via npm as a global module. Open up command prompt and type npm install gulp -g and this should install gulp.
Creating an ASP.NET Core Web Application
The barebones scaffold project that will give us a kick-start
Let’s start by creating a new ASP.NET Core web application. If you have the SDK and the tools installed, when you select File -> New -> Project in Visual Studio 2015, you should see the following options in the Web section of the Installed Templates:
Select the ASP.NET Core Web Application (.NET Core) template, and give a suitable name for the project. You can see that I’ve chosen Angular2.TypeScript.QuickStart as the project and solution name. Once we click OK, we are taken to another screen where we can choose the templates. Let’s start with an Empty template that will create a barebones application scaffold for us to start with. Make sure the Authentication is set to “No Authentication” and the Microsoft Azure “Host in the cloud” checkbox is unchecked. Click OK to have the project created for us.
Serving static files in ASP.NET Core RC2
A Single Page Application (SPA) in Angular 2 on ASP.NET Core
Now that we have the project setup, we should have a project structure as shown here:
We need to add some basic configuration to make sure our setup works, and our angular project can pull its dependencies properly. ASP.NET Core projects are geared towards server-side MVC. But we are about to do a Single Page Application (SPA) with Angular 2 and TypeScript. So first we need to make the app use static files.
Head to Startup.cs in our project, and find the Configure method:
We need to configure the app to use static files. Change the Configure method as:
The methods cannot be found and Visual Studio will start showing errors. ASP.NET Core RC2 is highly modularized and this is a good thing. We can pick and choose the parts of functionality that we want in our applications that run on ASP.NET Core RC2. The functionality we are looking for is nestled away in the nuget package Microsoft.AspNetCore.StaticFiles v1.0.0-rc2-final.
Let’s add the nuget package as a dependency to our ASP.NET Core web application. Head to project.json and see the dependencies portion, and add the following line:
As soon as you add the line and save the file, the package will be downloaded and you will have no errors. Now that we have setup the project for .NET Core, we have to setup the project for Angular 2 and Typescript.
Setting up node package dependencies
Adding the npm configuration and pulling packages
Visual Studio 2015 installs a version of node.js and npm upon installation, and will attempt using the same versions, even if you have installed a more recent version. We have to fix this first. Head to Tools -> Options and in the dialog box that opens, select Projects and Solutions -> External Web Tools. On the right pane, make sure that the $(PATH) option is at the top. You might have to move it to the top if it is not already there.
We need to specify the node packages that our quickstart app depends upon, and package.json is the place to the do it. We need to add it to our project. Right-click our project, and in the context menu, select Add -> New Item… to have multiple options appear. Our aim is to select the npm Configuration File option in the .NET Core -> Client-Side section.
Selecting that option will add a package.json file for us to edit. Replace the contents of the file with the following:
The gulp 3.9.1 dependency is something that we added to enable us to jump through the hoops that I’ve been talking about. We’ll get to it soon enough. I just wanted to note here that it is a deviation from the tutorial mentioned above.
As soon as you hit Save, the npm dependencies will be installed by Visual Studio and we will have completed this step. The packages are actually installed in a folder named node_modules located in the project root.
NOTE: Visual Studio may show that the dependencies are not installed at this stage, we can safely ignore it for now.
Adding TypeScript Configuration and Definitions
Remember the Add -> New Item… dialog? We need to use it now, to add a TypeScript JSON Configuration File. It will add a tsconfig.json file for us to edit. Replace its contents with the following:
For TypeScript definitions, we need to add a JSON file to the project root, named typings.json with the following contents:
Now that we have added typescript configuration, we need to install the definitions mentioned in our typings.json. This is easily done by restoring npm packages again. Expand the Dependencies section in the project. Right-click the npm folder and select Restore Packages. The definitions should be restored, and now the folder structure should look like this:
Configuring dynamic module loading
Using SystemJS as a universal dynamic module loader
Creating the AppComponent
Angular 2 apps are made up of reusable components
Angular 2 apps are made up of components which are reusable, and we need a root component for an app. So let’s write a super simple Angular component.
Right-click the project, select Add -> New Folder and name the folder as app. Now right-click the newly created app folder, and add a new TypeScript File as before, named app.component.ts with the following contents:
Every Angular app has at least one root component, conventionally named AppComponent, that hosts the client user experience. Components are the basic building blocks of Angular applications. A component is like a widget, it controls a portion of the view through its template, which can be simple, or can include other components. For any more explanation, head to the wonderfully written 5 minute quickstart tutorial mentioned above.
Hooking up AppComponent to the application
Bootsrapping based on browsers and whatnot
Now that we have the root component named AppComponent, we need to tell Angular to load the AppComponent first. To do this, we use a main.ts file. Since we’ve already covered adding files to a particular folder, add a main.ts file to the app folder, and fill it up with the following contents:
Creating the Single Page Application (SPA)
The first page of the application is also the only page
Now that we have our dependencies downloaded, TypeScript configured, dynamic module loading configured, and our components ready and bootstrapped, it is time to create the first and only page of our Angular 2 SPA. Let’s create an index.html in wwwroot with the following contents:
NOTE: The styles are actually found at Angular’s GitHub Repo
The project structure should now look like this:
Jumping through the hoops to get things going
The hoops that I’ve been talking about for so long
This is actually where the excellent 5-minute quickstart I mentioned above ends. Ideally, everything should work. But remember the hoops that I mentioned before, many, many times? The reason we needed gulp.js, a dependency not specified in that tutorial?
Remember the Add -> New Item… dialog? It’s time to bring it up again for our project. This time, select Gulp Configuration File, and replace its contents with the following:
It’s time to build the project. When we build, the TypeScript is compiled, the gulp tasks are run, and the files are in their place. Run the project to see the output:
For your reference, this is how the project structure should look now:
Did this work for you? Could I have done something better? Have I missed something? Would you like more explanations of why stuff is done, instead of just pointers as to what is to be done? Anything else that you want to say? Please use comments to place your feedback, suggestions, whatever you feel like sharing.