Angular Build with Webpack from Scratch – Part 2

Angular Build with Webpack Hero

Derived from photo by Yann Caradec / flickr.com, CC BY-SA

This is the second post in a two-part series getting started with webpack from scratch. The first part covered how to configure the Angular-specific portion of a webpack build. This post walks through how to configure the HTML, CSS, and development server. It builds upon the configuration started in part one.

If you want to jump straight to the code, the completed demo is on GitHub.

Webpack Context

As webpack begins to handle more of the application, it becomes necessary to configure multiple entry points for the build. Part one configures the full path for the single entry file. You could follow the same pattern with any new entry files. You could instead set the context configuration property.

The context property sets a directory as the location where file paths resolve. Instead of combining the paths of each entry file, you configure the base path and then specify the individual file names. This is how part one configured the single entry for webpack:

const path = require('path');
const source = path.resolve(__dirname, 'src', 'index.ts');

module.exports = {
    entry: source,
    // ...
};

To prepare for multiple entries, refactor the entry to use the context property as well:

const path = require('path');
const source = path.resolve(__dirname, 'src');

module.exports = {
    context: source,
    entry: [
        './index.ts'
    ],
    // ...
};

Note: The __dirname variable is a string from Node.js providing the current module's directory.

Using the context property is optional but it helps to remove repetitive path combining logic from your configuration.

HTML Build

Single-page applications are named this way because they typically contain one HTML document that loads the scripts to bootstrap the application. Angular is no exception and there is a handy plugin for webpack called HtmlWebpackPlugin to dynamically configure the HTML page.

The initial configuration for HtmlWebpackPlugin is straightforward. Import the module from its npm package, html-webpack-plugin, and then add it to the plugins property of the webpack configuration.

const HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
    // ...
    plugins: [
        new HtmlWebpackPlugin()
    ]
};

By default, the plug-in gives you a boilerplate HTML file for your application. You can however, supply it with a template through the module's constructor arguments. Keep in mind that when using a template, the HtmlWebpackPlugin automatically adds a script element referencing the output of the webpack build so ensure you haven't added the script reference multiple times. This is how to specify the template for HtmlWebpackPlugin:

module.exports = {
    // ...
    plugins: [
        new HtmlWebpackPlugin({
            template: './index.html'
        })
    ]
};

Now you have a webpack build that includes the JavaScript and HTML for your application where the bundle is automatically referenced in the output index.html file. Try it by running npm run build at the command line and inspect the output in the dist directory. The HtmlWebpackPlugin has many great extensions. You can find some of them listed in the project's README file.

CSS Build

The final portion of the Tour of Heroes to address is the global CSS. In the first part of this series, you configured webpack to load any CSS files that are referenced by Angular components. However, the application has global CSS defined in the styles.css file. This file includes style rules relevant to the overall look and feel of the application so it makes sense to keep this outside of the individual components` CSS.

The configuration already processes CSS for the components but this configuration won't work for the global CSS. The first thing is to define the boundary between when webpack should process CSS for components and when webpack should process the global CSS. Looking at the application, everything in the directory .\src\app\ needs to be configured for the angular2-template-loader where other CSS in the .\src\ directory should be bundled and included as a linkelement in the index.html file.

Define a variable for the .\src\app\ path and use the include property on the raw-loader configuration:

const source = path.resolve(__dirname, 'src');
const appDirectory = path.resolve(source, 'app');

module.exports = {
    // ...
    module: {
        rules: [
            // ...
            {
                test: /\.(css|html)$/, 
                include: appDirectory,
                loader: 'raw-loader'
            },
            // ...
        ]
    },
    // ...
};

To process the non-component CSS, use the ExtractTextPlugin. This plugin is essentially a wrapper that provides bundling functionality. It leverages other loaders' import logic to load the CSS content. In the end, you get a combined CSS file. Import the plugin from its npm package, extract-text-webpack-plugin. You also use the style-loader and css-loader npm packages for their respective CSS loaders.

Add the following to the rules array of the webpack configuration:

const ExtractTextPlugin = require('extract-text-webpack-plugin');

const source = path.resolve(__dirname, 'src');
const appDirectory = path.resolve(source, 'app');

module.exports = {
    // ...
    module: {
        rules: [
            // ...
            {
                test: /\.css$/,
                exclude: appDirectory,
                loader: ExtractTextPlugin.extract({ 
                    fallback: 'style-loader', 
                    use: 'css-loader?sourceMap' 
                })
            },
            // ...
        ]
    },
    // ...
};

You see this configuration loads files ending in the .css extension and excludes the appDirectory CSS. Remember, the appDirectory path contains your Angular code and undergoes a different build process than global styles.

The ExtractTextPlugin is configured as both a loader and a plug-in. To configure the plug-in portion of ExtractTextPlugin, add it to the plugins array. Provide a name for the final output bundle, for example styles.css.

module.exports = {
    // ...
    plugins: [
        // ...
        new ExtractTextPlugin('styles.css')
    ]    
};

Note: This tutorial uses styles.css as both the name of the input file and the output file. Feel free to customize this to help ensure you understand which piece of the configuration is related to inputs and which is related to outputs.

Finally, webpack needs to know about the existing Tour of Heroes styles.css file so add it as an entry in the configuration:

module.exports = {
    context: source,
    entry: [
        './index.ts',
        './styles.css'
    ],
    // ...
);

Now that the CSS is auto-generated, the HtmlWebpackPlugin and ExtractTextPlugin work together to add a link to the index.html template file. Remove any existing links to styles.css from the index.html file.

The ExtractTextPlugin has several different options and uses so it's worth taking a look at its documentation.

At this point, your webpack build is complete. Try it with npm run build to see the output. The final HTML template and webpack configuration should have the following contents:

<html>
<head>
  <base href="/">
  <title>Angular 2 Tour of Heroes</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
</head>

<body>
  <my-app>Loading...</my-app>
</body>

</html>
const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');
const ExtractTextPlugin = require('extract-text-webpack-plugin');

const source = path.resolve(__dirname, 'src');
const destination = path.resolve(__dirname, 'dist');
const appDirectory = path.resolve(source, 'app');

module.exports = {
    context: source,
    entry: [
        './index.ts',
        './styles.css'
    ],
    output: {
        filename: 'index.js',
        path: destination
    },
    resolve: {
        extensions: ['.ts', '.js']
    },
    module: {
        rules: [
            {
                test: /\.ts$/,
                loaders: [
                    'awesome-typescript-loader',
                    'angular2-template-loader'
                ]
            }, 
            {
                test: /\.ts$/,
                loader: 'webpack-replace',
                query: {
                    search: 'moduleId: module.id,',
                    replace: ''
                }
            },
            {
                test: /\.css$/,
                exclude: appDirectory,
                loader: ExtractTextPlugin.extract({ 
                    fallback: 'style-loader', 
                    use: 'css-loader?sourceMap' 
                })
            },
            {
                test: /\.(css|html)$/, 
                include: appDirectory,
                loader: 'raw-loader'
            },
        ]
    },
    plugins: [        
        new HtmlWebpackPlugin({
            template: './index.html'
        }),
        new ExtractTextPlugin('styles.css')
    ]
};

Development Server

The webpack development server integrates with webpack to provide many great features to aid your development. This functionality is installed with the webpack-dev-server npm package. The server automatically watches for changed files and refreshes the browser once a new compilation is complete. To improve performance, the webpack development server keeps the generated contents in memory as opposed to writing it to disk.

To setup a project for the webpack development server, create an npm script. For this tutorial, use the npm start command. There are several command line options available to configure the development server. Use the --open option to have the development server automatically open the default browser to the server's port on localhost:

"scripts": {
    "start": "webpack-dev-server --open",
    ...
}

While the development server has many configuration options, this tutorial covers two that are relevant to Angular developers: devtool and historyApiFallback. The devtool property specifies a source map type to aid in debugging at runtime. Go ahead and set the property to 'source-map'.

Then under the devTool configuration property, set the historyApiFallback property to true. This property tells the server to always return the index.html contents when a route is not available on the server. This is very useful when using client-side routing so that the server defers routing responsibility to Angular's router. Define these properties in your webpack configuration:

// ...
module.exports = {
    // ...
    devtool: 'source-map',
    devServer: {
        historyApiFallback: true,
    }
};

Save your configuration and type npm start at the command line to see webpack build and serve the application.

Final Thoughts

Now you have a starting point for your webpack build and more importantly, you understand how these pieces work together. Many of the more advanced webpack examples you see online use these pieces as their foundation so you can more easily add additional features to the build as you need them.

If you want to see this build in action, look at the repository on GitHub.

What are the next steps on your webpack journey? Which aspects of the build are still causing issues for you? Please sound off in the comments.

Philly.NET Code Camp 2017 Talk

Philly.NET Code Camp Header

I had the privilege to speak at the Philly.NET Code Camp this past weekend. I presented Angular, ASP.NET Core, and Visual Studio Code – Oh My! which proposes a roadmap for getting started with these technologies. The talk touches on a breadth of features and hones in on a specific set of steps for getting started.

With recent updates to both ASP.NET Core and Angular CLI, creating new projects has gotten easier. I'm making the slides available now to those interested and will write up a tutorial on the blog to match the demonstration I gave during the talk.

I attended this code camp for the first time nine years ago and always enjoy catching up with the friends I made along the way. I look forward to seeing you next year!

Angular Build with Webpack from Scratch

Angular Build with Webpack Hero

Derived from photo by Yann Caradec / flickr.com, CC BY-SA

This tutorial walks through creating a webpack-based build for the Angular Tour of Heroes sample application. By the end, you will have a basic build and development server with automatic refresh and source maps.

The tutorial is divided into two parts. In this first part, you setup the project and create the Angular-specific build. In part two, you process the other files of the application and setup the development server. Read part two here.

More importantly, you will understand what each piece of the webpack configuration does. Why is it important? How does it relate to other pieces of the build? This understanding is critical when you inevitably want to modify or add new webpack functionality.

Migrate Tour of Heroes

First, create a new directory for your project. Before copying any of the Tour of Heroes code into your repository, create a folder named src in the root of your project. This folder will house the source code related to the browser-based Angular web application. In contrast, the project's root directory is the place for configuration files for the build and overall project. These specific directory names and locations aren't required but consider partitioning your project's source code according to the application's concerns, e.g. client versus configuration.

Tip: Clone the Angular Tour of Heroes sample application locally to copy files easily.

Create the src directory within your project and copy the entire app directory, index.html, and styles.css files from Angular Tour of Heroes into the newly created src directory. Then, copy the tsconfig.json and package.json files into the project's root directory.

Your application structure should look like this:

├── src
|   ├── app
|   |   └── (...)
|   ├── index.html
|   └── styles.css
├── package.json
└── tsconfig.json

Now, make a couple modifications to the copied content. First, delete the src\app\main-aot.ts file. Ahead-of-Time (AOT) compilation is outside the scope of this tutorial and keeping this file causes a TypeScript compilation error.

Next, modify the packages in the package.json file. Since the entire build system is changing, replace the package list under devDependencies with this list:

"devDependencies": {
    "@types/node": "^6.0.45",
    "angular2-template-loader": "^0.6.0",
    "awesome-typescript-loader": "^3.0.3",
    "css-loader": "^0.26.1",
    "extract-text-webpack-plugin": "^2.0.0-beta.5",
    "html-loader": "^0.4.3",
    "html-webpack-plugin": "^2.16.1",
    "raw-loader": "^0.5.1",
    "rimraf": "^2.5.2",
    "style-loader": "^0.13.1",
    "typescript": "~2.0.10",
    "webpack": "2.2.0",
    "webpack-dev-server": "2.2.0-rc.0",
    "webpack-replace": "^1.0.0"
}

For now, don't worry about these packages as they are noted throughout the relevant sections of the tutorial.

Now that the list of packages is updated, run npm install from the terminal to install the required packages.

Finally, replace the existing npm scripts with a single script to invoke the webpack build:

"scripts": {    
    "build": "rimraf dist && webpack"
}

Note: If you attempt to run this script from a tasks.json file in Visual Studio Code, webpack might throw an error. To work around, run the npm script from the terminal instead.

This script calls the npm package utility rimraf to clear the contents of the dist directory and then calls webpack. The dist directory will be where webpack saves the build output.

Going forward, use the build script by invoking the command npm run build in the terminal to create the build. As you iterate your build configuration, use this command to verify the output.

TypeScript Build

In most cases, an Angular application consists of TypeScript files using ES2015 modules with HTML templates and styles defined either in line with components or in external files. The webpack build needs to understand how to process this structure and bundle it into a format the browser understands.

The Angular framework requires a couple polyfill scripts from core-js and zone.js. In Tour of Heroes, these scripts are included in the index.html file prior to loading the application. Being that the bundling process uses ES2015 import statements to create the bundle, move these script references to a new file called index.ts. Later, when processing the index.html file, the build will reference this new script. Place the index.ts file in the src directory with the rest of the Angular application and add this code:

// Polyfills
import 'core-js/es6';
import 'core-js/es7/reflect';
import 'zone.js/dist/zone';

// App
import './app/main.ts';

In addition to the polyfills, this file also imports the main.ts script to bootstrap the Angular application.

Now, it's time to create the webpack configuration. By default, webpack looks for a file at the root of the working directory named webpack.config.js. Go ahead and create this file and add the following contents:

const path = require('path');

const source = path.resolve(__dirname, 'src', 'index.ts');
const destination = path.resolve(__dirname, 'dist');

module.exports = {
    entry: source,
    output: {
        filename: 'index.js',
        path: destination
    },
    resolve: {
        extensions: ['.ts', '.js']
    },
    module: {
        rules: [
            {
                test: /\.ts$/,
                loaders: [
                    'awesome-typescript-loader'
                ]
            }
        ]
    }
};

At a high level, this file contains three variables: path, source, and destination. The path variable represents an imported npm module to assist in concatenating the required file and directory paths represented by source and destination.

The configuration also defines an object literal as the module's exports. The object literal is the webpack configuration and has the following properties: entry, output, resolve, and module. The entry property points to the file where webpack begins to construct the dependency tree, in this case, the index.ts file you created earlier. The output property defines the output file's name and path, in this case, dist\index.js.

The resolve property assists loading the TypeScript files. Because the import statements don't typically use a file extension, webpack uses the extensions defined in resolve.extensions to reconcile the imports. The compilation of the TypeScript files is ultimately handled by the awesome-typescript-loader. This loader is included in the project as an npm package defined in the package.json file.

The module.rules property is an array of objects that represent which tools load which files. In webpack, there is a concept of a loader. Loaders are an extension point which customize how code is processed by the webpack build. The defined loaders array is used only when an import matches the regular expression supplied in the test property.

The awesome-typescript-loader compiles TypeScript into JavaScript. The loader is used only for files that match the regular expression /\.ts$/ as defined in the test property.

With this configuration defined, test your build by typing npm run build in the terminal. Look at the newly created dist folder to see the result – one single JavaScript file index.js. Examine the contents and you will start to get a sense of how webpack packages the application dependencies.

Angular Component HTML and CSS

Compiling TypeScript to JavaScript is the first step in an Angular build. Now, you must include the contents of any external templates and styles. Components define these resources in the @Component decorator:

@Component({
    templateUrl: 'my-template.html',
    styleUrls: [ 'my-styles.css' ]
})
export class MyComponent { }

The angular2-template-loader is listed under defDependencies in the package.json file. It extends webpack to load these external files and place the contents in line with the component. The resulting code looks something like this:

@Component({
    template: '<h1>Hello World!</h1>',
    styles: ['h1 { color: blue }']
})
export class MyComponent { }

The angular2-template-loader requires that webpack understands how to load HTML and CSS files. Therefore, add another rule to the rules list to test for .css and .html files and use the raw-loader package. The raw-loader is a simple loader that emits the contents of a file as a string.

This is how the new rules configuration looks with these changes:

rules: [
    {
        test: /\.ts$/,
        loaders: [
            'awesome-typescript-loader',
            'angular2-template-loader'
        ]
    }, 
    {
        test: /\.(css|html)$/, 
        loader: 'raw-loader'
    },
]

Run the build again to test that the new configuration works. To verify that the HTML templates are included, perform a search in the emitted index.js file for a piece of code from one of the external templates such as {{hero.name}}.

The moduleId Problem

The Tour of Heroes application is designed to use SystemJS. Instead of combining the ES2015 modules into one bundle on the server, SystemJS dynamically loads all of the modules it needs when the application runs in the browser.

To assist the dynamic loading process, developers oftentimes configure the moduleId property like this:

@Component({
    moduleId: module.id,
    templateUrl: 'my-template.html',
    styleUrls: [ 'my-styles.css' ]
})
export class MyComponent { }

The value passed by module.id is populated at runtime by SystemJS. Since SystemJS is not there anymore to populate the property, it is not defined and Angular doesn't like this. It throws the error 'moduleId should be a string in "AppComponent".

One way to get around this is to manually change all of the files by removing the moduleId definitions. After all, who needs all of this boilerplate code anyway? However, you may not always have access to this code. You may be using code authored by a third party which hasn't in lined the templates as part of a build. They have moduleId defined so that consumers can use SystemJS if they choose.

For this tutorial, instead of manually removing the moduleId settings, webpack will do it for you. Use the webpack-replace loader (another npm package) to search for the moduleId settings and remove them.

The webpack rules configuration now looks like this:

rules: [
    {
        test: /\.ts$/,
        loaders: [
            'awesome-typescript-loader',
            'angular2-template-loader'
        ]
    }, 
    {
        test: /\.ts$/,
        loader: 'webpack-replace',
        query: {
            search: 'moduleId: module.id,',
            replace: ''
        }
    },
    {
        test: /\.(css|html)$/, 
        loader: 'raw-loader'
    }
]

Run your build again using npm run build and search in the output for moduleId: module – the search should return no results.

Finally, the webpack.config.js file looks like this:

const path = require('path');

const source = path.resolve(__dirname, 'src', 'index.ts');
const destination = path.resolve(__dirname, 'dist');

module.exports = {
    entry: source,
    output: {
        filename: 'index.js',
        path: destination
    },
    resolve: {
        extensions: ['.ts', '.js']
    },
    module: {
        rules: [
            {
                test: /\.ts$/,
                loaders: [
                    'awesome-typescript-loader',
                    'angular2-template-loader'
                ]
            }, 
            {
                test: /\.ts$/,
                loader: 'webpack-replace',
                query: {
                    search: 'moduleId: module.id,',
                    replace: ''
                }
            },
            {
                test: /\.(css|html)$/, 
                loader: 'raw-loader'
            }
        ]
    }
};

The working directory structure now looks like this:

├── dist
├── node_modules
├── src
|   ├── app
|   |   └── (...)
|   ├── index.html
|   ├── index.ts
|   └── styles.css
├── package.json
├── tsconfig.json
└── webpack.config.js

That's All for Now

This tutorial has taken you through the basics of building the Angular portion of the application. However, there are more pieces of the application that require processing. In part two, you handle the index.html and CSS portions of the application. In addition, you learn how to configure the webpack development server to run the application. Continue with part two here.

Angular and the Server

Angular and the Server Header

Derived from photo by jeanbaptisteparis / flickr.com, CC BY-SA

Coming from an ASP.NET background, developers are familiar with the File, New Project… experience. This is the process to setup a new project in Visual Studio – typically from a template to help you get started effectively.

These starter projects include everything in the box. They have UI rendering, authentication, sample data APIs, and more. And while they are great for getting started, they may not be the best design for the application you are building.

When it comes to building an Angular application, how should it integrate with the server-side application if at all? What design options are available to you and how do you know which is the right one? This is an often-overlooked topic in Angular-focused material. One the other end, server-side articles tend to encourage using server-side features without considering that you are using a very powerful front-end framework already.

This article details several application responsibilities and groups them in terms of their integration with the host application. For the purposes of this article, the host application is the server-side application that sits beneath your Angular application and serves it to the browser/client. (Spoiler alert, there might be NO application sitting beneath your Angular application.) The Angular application consists of the TypeScript and/or JavaScript you write against the Angular framework.

Level 0 – No Server Application

This level includes features that are configurable to have no server-side dependency. This means that when the application runs, Angular handles these features without requiring the server to process any of the logic. This configuration may be desirable especially when static file hosting is the preferred deployment option.

Even though there is no run-time server dependency, you can still leverage the power of a build to optimize your application. These are some of the features you can configure with no server-side backend.

Routing

The Angular router is optionally configured to use the hash URL style. In this configuration, each route is represented in the URL following the hash symbol, like example.com/#/about or example.com/#/products/1. The main benefit is that when someone enters this URL into the browser, they are going to the same endpoint each time, example.com. When the application loads, the router kicks in and navigates to the correct view.

Internationalization (i18n)

Angular includes utilities to internationalize applications. There are several phases to this process which you can read about in the documentation. At the end, you are left with multiple versions of your application that are deployed to their own directory as static files. At this point, there are several options for routing the user to the correct version of the application. The choice can be left to the user in the UI or the application can read the language settings in the browser to automatically route to the correct locale.

View Rendering

One of the first highlights of the Angular framework was its rendering. Being able to bind a JavaScript object to a template and see the data and events wire themselves up was almost magic. Angular accomplishes this in the browser and while server frameworks have their own rendering engines, you can generally rely on client-side rendering for your views when using Angular.

Level 1 – Host Application Integration

This level consists of functionality where the host application and the Angular application work together to produce the runtime functionality. While the server may not know intimately about the Angular application, both the server and client must be configured in a complimentary manner and make assumptions about the other's behavior.

Routing

As opposed to the hash style URL discussed earlier, the more common HTML 5 pushState style URL depends on server support. These URLs lack the hash symbol, for example example.com/about or example.com/products/1. The issue here is that when someone navigates to your application the first time using one of these URLs, the Angular application doesn't have a chance to handle the route. Instead, the server receives the request first and then returns the Angular application to the client to then complete the routing process. You can see an example with ASP.NET Core here.

Authentication

Sometimes, there are reasons to lock down your Angular application to only authorized users. While the Angular application could handle this based off of Web API authentication, you also have the option to authorize with the host application. For instance, the first time someone navigates to your web application, the server can return the 'not authorized' messaging without returning any of the Angular code to the browser.

View Rendering

As mentioned previously, Angular's rendering is more than capable of generating your application's UI. Generally, this rendering occurs in the browser. However, applications optimized for SEO and time-to-load performance, benefit from server-side rendering.

This is where Angular Universal fits in. Instead of using the server framework's view engine, Angular Universal renders Angular templates server-side. The browser receives the HTML and CSS to display the page immediately without client-side rendering. Subsequent views are loaded via AJAX and rendered on the client to reduce subsequent payload sizes. The framework supports both Node.js and ASP.NET Core backends.

Using Angular Universal does increase complexity and imposes certain restrictions in how you write your Angular application. Be sure that if you need this extra performance boost that you understand the trade-offs. Read more about it on GitHub.

Internationalization

Internationalization is an area where the host application may not have a direct role but may need to assist integrated routing, authentication, and/or rendering to provide the desired experience.

Logging

Logging also doesn't necessarily represent a tight integration between the host application and the Angular application. However, consider that as you increase the server's role with routing, authentication, and/or rendering, you should consider logging any errors resulting from this increased responsibility.

Level 2 – Web APIs

These dependencies are server-side dependencies. However, they do not have to live within the same web application hosting the Angular application. By keeping these dependencies in their own code base, there are many advantages. Builds and deployments are performed only for the applications that have changed. The APIs are built with whichever technology the team and/or company decide so long as it works over a common protocol – typically HTTPS. If you are familiar with the concepts of Web APIs and/or Microservices, this group encompasses those concepts.

Web APIs

Some examples of web API responsibilities that an application requires include data access, logging, and usage analytics. Interestingly, none of these concerns require any knowledge of the Angular application. In fact, they could serve many different front-end applications.

Authentication

Authentication at this level is typically handled directly between the Angular application client and the Web API server. There are many ways to do this but today's solutions generally use some form of JSON web tokens to maintain the user's identity.

Internationalization

At this level, any assets requiring i18n would be handled by the web API using server-side techniques. Again, this has no coupling to the Angular application beyond the API contract.

A Case for Bundling

Sometimes, applications are small and the API that they access is small. In this case, you may decide to keep this functionality together in the same application. They share the same build and the same deployment. Sometimes the effort to split these functions isn't greater than the payoff.

In this case, consider your development and design carefully as to avoid creating unnecessary coupling between the concerns. The web API may one day 'grow up' to need its own project so develop accordingly.

Final Thoughts

Every application is different. Hopefully by reading about how application concerns create dependencies between the server and the Angular application, you can apply these considerations to your own architecture.

One thing you might have noticed, there's no discussion of development tools that integrate with the server. This is a topic for a future post so stay tuned.

Ultimately, there is no one way to design an application. However, by knowing your options, you're better equipped to make lasting design decisions for your project.

What do you think? Is there functionality you prefer to run on the server? The client? Please share in the comments.

ASP.NET Core – Migrating to MSBuild

Migrating to MSBuild Header

This post continues the theme of exploring project structures for Angular and ASP.NET Core applications. The ASP.NET Core framework is in the midst of a transition to a new MSBuild-based project configuration. While there is material to help you start with MSBuild from scratch, many if not most of the published ASP.NET Core examples use the JSON-based project system. By learning how to migrate an existing application to the new MSBuild system, you can leverage the existing code and learn the new system – it's the best of both worlds.

There have been a couple high-profile posts recently around migrating from project.json to MSBuild from Nate McMaster and Scott Hanselman. This post is an overview of the MSBuild migration to help put these recent conversations in context. Why is Microsoft doing it? How can you migrate easily? The post covers these topics and includes links and tips to help with your own migration.

Moving to MSBuild

MSBuild, also known as the Microsoft Build Engine, is an XML-based project system for processing and building software. It's designed specifically for the .NET Framework and Visual Studio but is capable of processing other types of software and frameworks.

When .NET Core was introduced, ASP.NET Core was one of the first application targets available. To make the platform more attractive to open-source web developers, ASP.NET Core adopted a JSON-based project system defined in a project.json file. Looking at Node.js, everything is JSON-based as opposed to XML so this was a sensible design choice to attract new developers.

Prior to .NET Core, .NET projects were all based on MSBuild (or an MSBuild-like system). Typically, the developer didn't have to worry about this. Most projects started from built-in Visual Studio templates and Visual Studio automatically handled updates to project files (.csproj, .vbproj, etc.). Occassionally you had to resolve merge conflicts in the project file because it contained a list of each file in the project which was represented by its own XML node. If two developers independently modified the list of files in a project, this could result in a merge conflict but these issues were typically easy to resolve.

After .NET Core debuted, it quickly positioned itself as the framework for all .NET-based application targets including Universal Windows Platform (UWP) and Xamarin. Non-web developers didn't see the project.json file as an upgrade. They were used to using MSBuild and wanted to continue to use it. So for the greater good of the existing .NET community, Microsoft announced they are going to re-standardize on MSBuild as the build system for .NET Core.

Microsoft has added new capabilities to MSBuild. It went cross platform in 2015 and Microsoft announced enhancements for the build engine. Read more about them in Microsoft's blog post. The first MSBuild-based SDK 'alpha' was released in November, 2016.

New CLI Command, "dotnet migrate"

To aid in the transition to the MSBuild project system, the dotnet command-line interface (CLI) now includes the dotnet migrate command. This command takes a project using JSON-based configuration and converts it to a .csproj file. The command is available in dotnet CLI version 1.0.0-preview3-004056 or later.

The utility carries out several actions. First of all, it takes your existing project.json, global.json, and .xproj files and moves them to a folder named backup. If you are using source control, you can safely delete this folder.

The second thing the utility does is generate a new .csproj file from the contents of the project.json file. Before you delete the old file, consider taking a look at how the project.json and .csproj files compare.

Most of the contents of the project.json convert to PackageReference elements:

<PackageReference Include="Microsoft.AspNetCore.Mvc">
    <Version>1.1.0</Version>
</PackageReference>

There is a slight difference for tooling dependencies. They are added as DotNetCliToolReference elements.

<DotNetCliToolReference Include="Microsoft.DotNet.Watcher.Tools">
    <Version>1.0.0-msbuild1-final</Version>
</DotNetCliToolReference>

For executing npm scripts in your ASP.NET build to pre-process your TypeScript or Sass code, the new MSBuild script looks like this:

<Target Name="PrepublishScript" BeforeTargets="Publish">
    <Exec Command="npm install" />
    <Exec Command="npm run tsc" />
</Target>

If you are distraught over the project file moving from a concise JSON schema to a specialized XML-based schema like MSBuild, don't get too upset yet. First, you can continue to use project.json in the short-term by including a global.json file in your project. In the long term, Microsoft has stated they are looking at how to generate MSBuild-based configuration so that ideally you don't have to write it yourself. The dotnet migrate command is an important first step to this commitment. However, as an ASP.NET developer you will most-likely benefit from having a basic understanding of MSBuild.

Tips

There is a great post discussing the details of migrating from project.json to MSBuild in Nate McMaster's conversion guide. Also, take a look at the MSBuild documentation to gain a general understanding of the build system.

One important detail to note is that your global.json file must reference a version of the CLI that supports dotnet migrate (1.0.0-preview3-004056 or later). If you see the error No executable found matching command "dotnet-migrate", look to update the sdk in your global.json file.

This last tip is anecdotal. It did cost me time so hopefully describing it may help someone else. While not completely sure the reason yet, there was an issue executing commands, in this case npm scripts, before or after the "Publish" target. If you experience this issue, try using a different target such as Build.

<Target Name="NpmCommands" AfterTargets="Build">
    <Exec Command="npm install" />
    <Exec Command="npm run tsc" />
</Target>

Finally, look for more resources from Microsoft. They are working to deliver an "RTM quality" version of the SDK in early 2017 so expect many updates to documentation and templates leading up to the release.

Conclusion

The dotnet migrate tool is very helpful. I have found works well at least with smaller projects. This is a considerable shift in configuration and Microsoft has done commendable work to automate the process. Looking forward, it will be interesting to see how they make this configuration easier for web developers coming new to the platform.

Have you been working with the MSBuild project system in .NET Core? What have been your pitfalls or successes? Please share in the comments.

Great Angular, ASP.NET Core Starter Templates

Great Angular, ASP.NET Core Starter Templates Title

This post exists to provide hope. After the somewhat hesitant reaction to last week's webpack post, this post highlights two great Angular and ASP.NET Core starter templates. These starter projects not only contain configurations for webpack 1 and webpack 2, there are a ton of other Angular and ASP.NET features implemented for you.

ASP.NET Core Template Pack

ASP.NET Core Template Pack - Angular Starter

The first project template to note comes from the ASP.NET Core Template Pack by Mads Kristensen. The template pack is a Visual Studio Extension containing multiple templates for ASP.NET Core. The collection includes a helpful Angular template.

Key Features

The hallmark feature of the template is Angular Universal. This framework enables server-side Angular rendering when the application is initially requested from the server. Angular Universal decreases the initial page load time by rendering the first request on the server instead of requiring the client to wait for the application to download before rendering. Subsequent route changes are all rendered client-side. For any application that requires minimum load times, this framework is a must-see.

The template also uses webpack version 1. For anyone working on integrating webpack into their applications, every example helps. This template doesn't use the latest loaders that the folks on the Angular side of the community are using. It does however accomplish the primary goal by compiling combined scripts. And being that it's using Angular Universal, there are webpack configurations for both the client application and the server rendering portion.

The template also implements webpack's hot module replacement feature. This is a development feature where the client-side code is replaced in the browser via a WebSocket when the source module is edited on the file system. If you've ever used a development server with automatic refresh like Browser Link or Browsersync, then it's like that – except without the full page refresh. You should check out the template just to try out this feature – you may never go back.

The previously mentioned features are configured with the help of Steve Sanderson's ASP.NET Core JavaScript Services. This library is part of ASP.NET Core on GitHub and provides useful integrations for single-page application (SPA) frameworks including Angular. The template includes simple, foundational examples for routing and data access as well as Docker container configuration.

Gotchas

Currently, if you are looking for the very latest in front-end Angular features, this template doesn't have them. It's using webpack version 1 versus webpack version 2 and doesn't include all of the niceties that have been introduced with newer webpack loaders such as awesome-typecript-loader and angular2-template-loader.

Also, if you see an error like this when starting the template, it means you have to specify a prior version of ASP.NET using the global.json file.

Template Error

You can read more about the solution on GitHub.

Bottom Line

This is a stable template that highlights the main integration points between ASP.NET Core and Angular. For now, it might not have the most up-to-date client-side features but you can imagine these will come as the tooling comes to a final release (or when we all submit pull requests). Being a Visual Studio extension, it is optimized for the Visual Studio IDE and it provides a nice starting point.

To view the source for this template, check out its GitHub repository.

ASP.NET Core & Angular2 Universal Starter (Angular2Spa)

ASP.NET Core & Angular2 Universal Starter Diagram

This might be the best Angular on ASP.NET Core template available right now. It's actively developed by a member of the Angular Universal team, Mark Pieszak.

In fact during the course of writing this review, he fixed an issue that I was experiencing while working with the template for this article. The template contains some of the latest techniques and frameworks for building Angular applications on ASP.NET or otherwise.

Key Features

You can think of this project as a superset of the template currently in the ASP.NET Core Template Pack. It has the same base level of features and then adds on top of it. This template works in Visual Studio. It also contains configuration files to run in Visual Studio Code, complete with key bindings to initialize the dotnet build. It even uses the newer ASP.NET Core 1.1 assembly versions.

For the front-end tooling, the template uses webpack version 2 including many new loader patterns that you find in the Angular documentation. The example also makes use of an RxJS-based, Redux-like store via the NgRx library.

To help keep your code styles on par, this template uses codelyzer. Built on top of TSLint, codelyzer provides linting for TypeScript as well as the Angular Style Guide conventions.

Finally, this template configures unit testing with Karma and Jasmine integrated with webpack. It also includes end-to-end (E2E) tests using Protractor. These configurations alone can save you a dozen hours versus configuring yourself.

Gotchas

Certainly check out the README file for this project. It has a lot of great information on how to use Angular with or without this template and highlights areas where you may otherwise stumble. One other word of caution – this template leans on the bleeding edge so you may find some instability along the way. The maintainer so far seems to do a nice job keeping up with any logged issues.

Bottom Line

This is a must-see and must-watch starter template for ASP.NET developers using Angular. There is nothing more to say, take a look for yourself.

Final Thoughts

The Angular and ASP.NET frameworks are both evolving at a rapid pace and it can be difficult to keep current with the changes. These templates can help you start coding quickly and help you incorporate new technologies and patterns as they are published.

These are two of the best and more noteworthy starter templates for Angular and ASP.NET. Give them a try and share your thoughts below. If there are any other starter templates you find helpful, please let everyone know in the comments.

SystemJS to Webpack – Before You Begin

SystemJS to Webpack - Before You Begin Title

This is a primer discussing why to move from SystemJS to webpack in your Angular project. The post also describes some of the hurdles you may run into with this effort.

While it doesn't go into specific webpack configuration, this article aims to provide an overview for someone who has heard of webpack but doesn't quite understand why or how to get started. Specific details configuring webpack with ASP.NET Core are coming in future posts.

SystemJS – Starting Point

There are several posts on this blog with examples using SystemJS to mimic Node.js module resolution in the browser. While TypeScript understands how to resolve types by npm package name during development, SystemJS fills this need in the browser by mapping package names to specific script files within the npm packages. This is an effective and minimal way to setup an Angular 2 application to load its dependencies from npm and get going quickly.

After starting with SystemJS, applications (even small ones) quickly grow to contain hundreds of ES2015 modules that are then downloaded by the browser to execute the application. This is probably not a problem during development when the browser and the server are on the same machine.

At some point, however, you may want to host your application for others to see. The performance hit of loading this many modules becomes noticeable. This situation leads to creating some type of build combining these hundreds of requests into only a handful.

Whereas SystemJS manipulates the browser to understand node module resolution, webpack (and similar build tools) manipulate the code to accommodate the browser's needs. Whether SystemJS or webpack, you continue to code the way that makes you the most productive with as many ES2015 modules in as many files as make you happy. Unlike SystemJS, webpack provides the browser with a streamlined payload to load the application as efficiently as possible.

Destination Webpack

Webpack at its core is a JavaScript module bundler meaning it takes JavaScript modules from separate files and combines them into one file. Webpack can be extended, though, by using loaders which allow you to bundle other types of files. So, while webpack doesn't understand TypeScript natively, it processes .ts files by using a loader.

Webpack has another extensibility mechanism called plugins. Where loaders handle specific file types, plugins process the contents of the loaded files. Plugins, for example, are responsible for minifying code where variable names are shortened and whitespace is removed.

One aspect of webpack that is different from a tool such as grunt or gulp is that it is more declarative meaning you configure an object literal and that object defines what should happen when you run the webpack command. The declarative nature of webpack ideally requires less configuration code and should lead you into a build that is more optimized than if you had to wire the pieces up yourself.

There are two other npm packages that carry the webpack name but are not the bundler, itself. These packages work with the bundler to improve the development experience. They are webpack-dev-server and webpack-dev-middleware.

The webpack-dev-server npm package is a lightweight development server based on Node.js and Express. It has all the basic development server features and includes hot module replacement. Hot module replacement (HMR) is a process where the development server uses a WebSocket connection to replace the code of a given module in the browser when it has changed in the development environment. This does not require a full page refresh to reflect the updates making it seamless to view your changes in the browser during development.

The webpack-dev-middleware npm package is a little more esoteric. It runs as an in-memory store containing the build output as opposed to writing the output to disk. This can decrease the time between when you modify a file and when you can see the changes running in the browser.

Configuration Troubles

Currently in early 2017, webpack is moving from version 1 to version 2. This can lead to incompatibilities in the webpack tool chain. When configuring a webpack build yourself, expect to find out-of-date examples and see errors processing your build.

Not all loaders and plugins support both webpack 1 or webpack 2 and you may find yourself trying different versions of these npm packages with different versions of webpack. Throw in the fact that TypeScript is adding significant new features through all of this and it's a recipe for configuration troubles.

This isn't meant to scare you off, just be prepared. Expect to search through the GitHub issues of some of these frameworks looking for answers or expect to post issues yourself. It's not always clear which combination of settings are correct but the webpack community is by-and-large responsive and committed to this tooling.

This is an example of an issue you may find. While the TypeScript compiler allows comments in the tsconfig.json file as of version 1.8, some of the TypeScript webpack loaders will blow up if there are comments in this file. There is no helpful error message, it just throws an error that a property is not defined on a null reference.

It's likely these issues are resolved over time, but you should understand what you are up against.

Replacing SystemJS

Now that you know about webpack's advantages and potential pitfalls, what are the general steps required to replace SystemJS? This is a summary:

  • Move polyfill scripts from index.html into the webpack bundle
  • Compile and bundle the TypeScript files
  • Move any external component HTML templates and stylesheets inline
  • Add a reference to index.html for the new bundled resource

Move polyfill scripts from index.html into the webpack bundle

Many Angular tutorials instruct you to put polyfill dependencies directly in the index.html (or alternatively named default HTML) file. This approach works and will continue to work with webpack but you should consider moving these dependencies into the webpack configuration.

First, including these dependencies into a bundled request improves performance. Second, having all your script dependencies in one place decreases the time to find a given dependency – thus increasing maintainability. Third, webpack resolves dependencies through node module resolution meaning you add the package name to the configuration and you're done. Using SystemJS, you often must identify the correct script to load from within the npm package.

Compile and bundle the TypeScript files

While you could continue to compile TypeScript with the TypeScript compiler, the idea is to move everything into webpack. There are several loaders that handle TypeScript files and are generally straightforward to configure. A popular TypeScript loader in the Angular community now appears to be awesome-typescript-loader.

Move external component HTML templates and stylesheets inline

This one is Angular-specific. When you have components with external templates and/or stylesheets, Angular loads these files as separate requests. By using a loader like the angular2-template-loader, the build now can combine the contents of the external templates and stylesheets into the component script itself.

Note: Understand that by moving the templates and stylesheets inline, setting the @Component directive's moduleId property is unnecessary. Leaving the moduleId property set in the component can lead to issues. While the available tooling should most likely handle this, you may find you must account for this yourself by removing the settings manually or creating automation.

Add a reference to index.html for the new bundled resource

Finally, once you define the file(s) that webpack outputs, you must reference the new bundled file(s) in your main HTML file. As you may have guessed, there are even webpack plugins to handle this as well based off the webpack configuration (see html-webpack-plugin).

Additional Configuration

While the previous sections listed the necessary pieces of a basic webpack build. You have so many more options available to you to optimize your code. Some build steps to consider are: Ahead-of-time (AOT) compilation, using the wwwroot folder in ASP.NET Core, tree-shaking, running tests, and using the webpack development server with hot module replacement.

Tackling the Beast

So, you still want to get going with webpack? Where do you begin? There are many projects on Github and other sites that provide insight into how this tool works. It appears to still be hit or miss as far as quality. Looking at it from an ASP.NET developer's perspective, the guidance options are fewer. With that said, here are some links to get started:

None of these resources paint the full picture but they provide a good overview. In addition to these general resources, visit the documentation for the individual loaders and plugins to get details regarding compatibility with other packages.

You should consider creating your own webpack build from scratch. There are advantages to doing it this way. If you like knowing how these tools work, this is a rewarding way to learn, albeit a time-intensive one.

Focus on one piece of the build at a time. It's easier to identify which pieces of the build are failing and you can more easily investigate or replace that specific loader or plugin to compare results. Once you stabilize one part, move on to the next until you have the build that you want.

Start with the pieces outlined in the Replacing SystemJS section and continue from there.

More on the Way

You've learned why you should consider moving to webpack and the general approach to creating a webpack-based build. Again, this is just a primer. The plan is to ultimately provide you with a webpack configuration that works well with Angular and with ASP.NET Core. You will see more posts about webpack here soon.

For now, what are your favorite webpack resources? Did you build a template that others may find useful? Please share in the comments.

TypeScript String Enums

TypeScript String Enums Header

Derived from photo by Markus Spiske / raumrot.com, CC-BY

This post expands upon a popular issue/proposal in the TypeScript GitHub repository called 'String enums'. The proposal is to create an enum that uses string values as opposed to the currently used numeric values. After TypeScript 2.1 was released, user wallverb posted an interesting solution leveraging the new features – many thanks for the inspiration.

While the term pattern might be a bit of an oversell, this technique or trick will get you the intended result. Included is an example to demonstrate the usefulness of this solution. The article compares other TypeScript features that don't quite meet the mark and also discusses how the solution works to create the right combination of type checking and runtime behavior.

The TypeScript team might still make it easier to create 'string enums' in future versions of the language. Regardless, learning how this solution works will deepen your understanding of the new TypeScript 2.1 features.

Use Case

If you think about inputs such as dropdowns or radio buttons where the user must select a single value from multiple choices, the underlying values oftentimes map nicely to an enum data structure. For example, consider a selection of shirt sizes. You could easily define the shirt sizes with an enum:

enum Size {
    XLarge,
    Large,
    Medium,
    Small
}

This is a nice data structure with which to code. All of the related values are in one place and it's easy to access a value from the list.

To understand what TypeScript is doing, it compiles the enum to a data structure at runtime that looks like this:

var Size;
(function (Size) {
    Size[Size["XLarge"] = 0] = "XLarge";
    Size[Size["Large"] = 1] = "Large";
    Size[Size["Medium"] = 2] = "Medium";
    Size[Size["Small"] = 3] = "Small";
})(Size || (Size = {}));

While this structure is a bit hard to follow, it allows for the following runtime behavior:

    console.log(Size.XLarge); // 0
    console.log(Size.Medium); // 2
    console.log(Size[Size.Small]); // 'Small'

Looking at the first two lines, you see the underlying values for these enum choices are numbers. However in the last line, you see it is possible to get the enum selection as a string.

If you define a property that accepts one of the enum values as a string, the type of that property will be string which has no association with the enum from which you would like to get the value.

interface Shirt {
    size: string;
}

// all is right with the world
const shirt: Shirt = {
    size: Size[Size.Large] 
};

// what happened to the enum values??
const invalidShirt: Shirt = {
    size: 'ExtraMedium'
};

TypeScript, however does offer a way to limit string values but this is a separate type definition altogether:

 type SizeString = 'XLarge' | 'Large' | 'Medium' | 'Small';
 const good: SizeString = 'Large'; // compiles
 const bad: SizeString = '' // doesn't compile

Now think back to the multi-choice selections in HTML like the dropdown and radio buttons. The HTML elements define values using attributes which are strings. So wouldn't it be great if you could get the simplicity of an enum but with string values instead of numeric values?

The Code

The SizeSelectComponent demonstrates this use case. Its template contains a select element with several options defined, in this case it displays a range of shirt sizes. Notice the Size variable and the Size type defined. These declarations create the 'string enum' definition.

import { Component, Input } from '@angular/core';

const Size = {
  XLarge: 'xl' as 'xl',
  Large: 'l' as 'l',
  Medium: 'm' as 'm',
  Small: 's' as 's'
}
type Size = (typeof Size)[keyof typeof Size];
export { Size };

@Component({
    moduleId: module.id,
    selector: 'app-size-select',
    template: `
        <select [ngModel]="selectedSize">
            <option value="{{size.XLarge}}">Extra Large</option>
            <option value="{{size.Large}}">Large</option>
            <option value="{{size.Medium}}">Medium</option>
            <option value="{{size.Small}}">Small</option>
        </select>    
    `
})
export class SizeSelectComponent { 
    @Input() selectedSize: Size;

    // Bonus - see how the constants define 
    // the values in the markup above
    size = Size;
}

Furthermore, notice the selectedSize input property for this component. Notice it is of type Size. Now when consuming this component, you can set the selectedSize property using the Size variable properties.

import { Component, OnInit } from '@angular/core';

import { Size } from './app.size-select';

@Component({
  selector: 'my-app',
  template: `<app-size-select [selectedSize]="size"></app-size-select>`,
})
export class AppComponent implements OnInit {
    size: Size;

    ngOnInit() {
        // Looks like an enum, but the value is a string
        this.size = Size.Small;
    }
 }

That's the scenario. It looks very similar to an enum but an enum used in this way would pass an integer value. This provides a string value.

Note: Because this example uses the ngModel directive, be sure to import the FormsModule into the NgModule for these components.

What's Going On?

Take a look at the Size declarations again:

const Size = {
  XLarge: 'xl' as 'xl',
  Large: 'l' as 'l',
  Medium: 'm' as 'm',
  Small: 's' as 's'
}
type Size = (typeof Size)[keyof typeof Size];

The first thing to note is that there are two declarations. The first is the variable declaration which assigns all of the string values to a simple object literal. There is one added compile-time feature here where the properties are defined with their respective string literal type. By adding the as 'xl' type when setting the property XLarge: 'xl' as 'xl', TypeScript performs a compile-time check to prevent overwriting Size.XLarge with a different string value.

The second declaration is the type declaration:

type Size = (typeof Size)[keyof typeof Size];

This declaration is easier to read rewritten into two statements:

type SizeLiteral = typeof Size;
type Size = SizeLiteral[keyof SizeLiteral];

The only thing that has changed is that typeof Size is assigned to its own type called SizeLiteral which is then re-used in the Size type declaration. TypeScript uses the typeof operator to create a type from the Size object definition.

The second line introduces the keyof T operator. TypeScript uses keyof T known as the index type query operator to create a string literal type from the properties of an existing type. For instance keyof SizeLiteral is equivalent to the string literal type 'XLarge' | 'Large' | 'Medium' | 'Small'. This is nice but it isn't going to provide the right type for this scenario, so the next level to this is called the indexed access operator.

Whereas the index type query operator pulls the string literals type from the properties of a given type, the indexed access operator, also represented as T[K], pulls the underlying types of those properties. So remember how you used string literals to define the types of the Size declaration such as XLarge: 'xl' as 'xl'? The Size type is equivalent to the string literal type 'xl' | 'l' | 'm' | 's' because those are the types of the Size type's properties.

Now to return to the initial implementation, SizeLiteral is removed in place of typeof Size and wrapped in parentheses to represent T in the T[K], index type query operator:

type Size = (typeof Size)[keyof typeof Size];

Finally, both the variable and type are exported as Size so that the parent component can consume this interface:

export { Size };

Wrapping Up

You saw how to leverage the new TypeScript 2.1 features to create a type that makes working with string literals much like working with an enum. Don't worry if you don't understand this the first time. There is a lot here so you may consider reading the post again and trying it out yourself. For more information on advanced types in TypeScript, take a look at the documentation.

Do you find this technique useful? In what other scenarios would you consider using this solution? Please leave a note in the comments.

Your First Angular 2, ASP.NET Core Project in Visual Studio Code – Part 6

Angular2, ASP.NET Core, Visual Studio Code, Part 6

Derived from photo by Markus Spiske / raumrot.com, CC-BY

This is the last in a series of posts teaching you how to create your first Angular 2 application with ASP.NET Core in Visual Studio Code. Here is the list of posts:

This article discusses an important part of the integration between client and server – routing. Angular 2 has its own router and so does ASP.NET Core. In the following sections you learn to setup routing in Angular 2 and then how to support the Angular 2 routing with ASP.NET Core.

This post addresses the high-level concerns of integrating these two routing systems. For more information on the individual routing features for each framework, read about Angular 2 routing here and ASP.NET Core routing here.

.NET Core SDK Preview 3: This tutorial uses .NET Core SDK Preview 3 which is available on GitHub. This version includes 'alpha' support for MSBuild-based projects that use .csproj configuration instead of project.json configuration. Microsoft announced that MSBuild is the common project configuration for .NET Core based projects going forward. By using MSBuild, the goal is to better prepare you for future versions of the tooling.

If you would like to jump straight to the code, it's all on GitHub.

Refactor to Multiple Components

In order to implement routing for Angular 2, you need to have multiple components in the project.

Move the contents of AppComponent to a new component called PairingComponent which is responsible for pairing Sriracha with foods.

import { Component } from '@angular/core';

@Component({
    moduleId: module.id,
    selector: 'my-pairing',    
    template: `
        <h2>Pairing</h2>
        <input type="text" [value]="food" (input)="foodInput($event)"/>        
        <p>Sriracha sauce is great with {{ food }}</p>
    `,
})
export class PairingComponent { 
    food = 'kielbasa';

    foodInput(event: Event) {
        const target = event.target as HTMLInputElement;
        this.food = target.value;
    }
}

The AppComponent becomes the application shell including the navigation. For now, the PairingComponent is rendered directly in the AppComponent template.

import { Component } from '@angular/core';

@Component({
    moduleId: module.id,
    selector: 'my-app',    
    template: `
        <nav>
            <a href="/pairing">Pairing</a> | 
            <a href="/about">About</a>            
        </nav>
        <my-pairing></my-pairing>
    `,
})
export class AppComponent { }

Also, create a third component called AboutComponent which serves as a second view.

import { Component } from '@angular/core';

@Component({
    moduleId: module.id,
    selector: 'my-about',    
    template: `
        <h2>About Sriracha</h2>

        <p>This is what Wikipedia says about <a href="https://en.wikipedia.org/wiki/Sriracha_sauce_%28Huy_Fong_Foods%29">Sriracha sauce</a>:</p>

        <blockquote>It can be recognized by its bright red color and its packaging: a clear plastic bottle with a green cap, text in Vietnamese, English, Chinese, French, and Spanish, and the rooster logo. David Tran was born in 1945, the Year of the Rooster...<blockquote>
    `,
})
export class AboutComponent { }

Finally, you declare all of these components in the AppModule.

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

import { AppComponent } from './app.component';
import { PairingComponent } from './pairing.component';
import { AboutComponent } from './about.component';

@NgModule({
    bootstrap: [ AppComponent ],
    imports: [ 
        BrowserModule,
    ],
    declarations: [ 
        AppComponent, 
        PairingComponent, 
        AboutComponent, 
    ],
})
export class AppModule { }

The app directory now looks like this:

component folder structure

Run your application to see the new navigation.

Navigation Screenshot

Configure the Angular 2 Router

To configure the AppModule routes, import RouterModule and Routes from @angular/router. The Routes type is an array of Route objects used to define the routes.

When navigating to http://localhost:5000/pairing the application should show the PairingComponent. When navigation to http://localhost:5000/about the application should show the AboutComponent. There is also a third scenario. When navigating to the root of the application, http://localhost:5000/, the application should redirect to http://localhost:5000/pairing as the default.

This is what the Routes array looks like:

const routes: Routes = [
  { path: '', redirectTo: '/pairing', pathMatch: 'full' },
  { path: 'pairing',  component: PairingComponent },
  { path: 'about', component: AboutComponent },
];

The pathMatch property must be set for all redirects. In this case, the value 'full' denotes that the redirect should occur when the path is at the application root or is otherwise empty ('').

Next, register these routes with the RouterModule and register the RouterModule with the AppModule.

This is the final code for the AppModule:

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { RouterModule, Routes } from '@angular/router';

import { AppComponent } from './app.component';
import { PairingComponent } from './pairing.component';
import { AboutComponent } from './about.component';

const routes: Routes = [
  { path: '', redirectTo: '/pairing', pathMatch: 'full' },
  { path: 'pairing',  component: PairingComponent },
  { path: 'about', component: AboutComponent },
];

@NgModule({
    bootstrap: [ AppComponent ],
    imports: [ 
        BrowserModule,
        RouterModule.forRoot(routes),
    ],
    declarations: [ 
        AppComponent, 
        PairingComponent, 
        AboutComponent, 
    ],
})
export class AppModule { }

Finally, the Angular router depends on a base element with href defined. You add this in the head of index.html so that Angular can update the browser's address bar correctly. This is the updated index.html code:

<!DOCTYPE html>
<html>

<head>
    <title>Angular 2, ASP.NET Core Starter</title>
    <base href="/">
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <!-- Polyfill(s) for older browsers -->
    <script src="node_modules/core-js/client/shim.min.js"></script>

    <script src="node_modules/zone.js/dist/zone.js"></script>
    <script src="node_modules/reflect-metadata/Reflect.js"></script>
    <script src="node_modules/systemjs/dist/system.src.js"></script>

    <script src="systemjs.config.js"></script>
    <script>
        System.import('app').catch(function(err){ console.error(err); });
    </script>
</head>

<body>
    <my-app>Loading...</my-app>
</body>

</html>

Configure the Navigation

The last step to configure the Angular routing is to configure the navigation to utilize the routes. To accomplish this, you modify the AppComponent template in two significant ways.

First, instead of including the my-pairing element in the AppComponent template, replace it with the router-outlet element. This is a placeholder where the router renders the component matching the current route.

Finally, you replace the href attribute with the routerLink attribute. This is a directive instructing Angular to register the click with the router instead of the default href behavior.

The final code for the AppComponent looks like this:

import { Component } from '@angular/core';

@Component({
    moduleId: module.id,
    selector: 'my-app',    
    template: `
        <nav>
            <a routerLink="/pairing">Pairing</a> | 
            <a routerLink="/about">About</a>            
        </nav>
        <router-outlet></router-outlet>
    `,
})
export class AppComponent { }

At this point, run the application using Ctrl+Shift+B and start the browser using npm run chrome which you configured in part 5. Notice how the application defaults to the /pairing URL. Clicking on the link loads the appropriate component for that specific URL.

Working Angular 2 Routes

There's still one problem. When you go directly to a route URL like http://localhost:5000/about from the browser's address bar, you see a 404 error. This is a result of the fact that even though Angular knows how to reconcile this URL, the server does not.

In the next section, you configure the ASP.NET MVC routes to return the Angular application when it doesn't recognize the route.

Add ASP.NET Routing

In order to configure ASP.NET routing, you must install the ASP.NET MVC package. Add this PackageReference to the .csproj file and then run dotnet restore from the terminal.

<PackageReference Include="Microsoft.AspNetCore.Mvc">
    <Version>1.1.0</Version>
</PackageReference>

Once the package is installed, create a directory at the root of your project called Controllers. Inside this directory, create a file called HomeController.cs. In this file, create a HomeController class which inherits Controller. This is the code.

using System.IO;
using Microsoft.AspNetCore.Mvc;

public class HomeController : Controller
{
    public IActionResult Index()
    {
        var fileName = "index.html";
        var contentType = "text/html";

        string filePath = Path.Combine(Directory.GetCurrentDirectory(), fileName);
        string fileContents = System.IO.File.ReadAllText(filePath);

        return Content(fileContents, contentType);
    }
}

In ASP.NET MVC, controllers are where a request is processed and a response is constructed. In this controller, the Index method reads the index.html file containing the Angular application and returns the file contents as a text/html response to the browser. This is essentially the same response that the browser receives when requesting index.html directly. Once the application is loaded into the browser, the Angular router takes over.

In order for the HomeController to do its thing, you must configure the ASP.NET MVC router to direct all of the incoming requests to the Index method.

In the Startup.cs file, you have to add a couple new configurations. First, ASP.NET MVC is configured as a service which requires the Startup class to implement a ConfigureServices method. Also, you configure the routes in the existing Configure method. The new Startup.cs code looks like this:

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc();
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseDefaultFiles();
        app.UseStaticFiles();

        app.UseMvc(routes =>
        {
            routes.MapRoute(
                name: "default",
                template: "{*url}",
                defaults: new { controller = "Home", action = "Index" });
        });
    }
}

The MapRoute method takes a configuration object. The template field defines the URL pattern that matches the route. Because there is only one variable defined in the template and it uses the asterisk, this route essentially handles all requests that haven't already been handled by the UseDefaultFiles or UseStaticFiles middleware. Furthermore, the defaults field directs all of these requests to the HomeController and it's Index action method.

At this point, run your application. In the browser, go directly to http://localhost:5000/about and you will see that the application loads from the server. Once the Angular application loads, it applies the correct route on the client.

Routing Integration

The End

This brings the final part of this Angular 2, ASP.NET Core, and Visual Studio Code journey to a close. You have learned a lot about configuring these frameworks and tools to work together. You've learned your way around Visual Studio code. You configured an Angular 2 and ASP.NET Core application so that both frameworks play well together. You created a basic Angular 2 application and automated tasks with npm and Visual Studio Code.

But you have only scratched the surface. This is just the beginning. What was your favorite discovery? Which topics are you most interested in learning about more? Leave a comment below and have fun with your new tools!

Your First Angular 2, ASP.NET Core Project in Visual Studio Code – Part 5

Angular2, ASP.NET Core, Visual Studio Code, Part 5

Derived from photo by Markus Spiske / raumrot.com, CC-BY

This is part five in a series of posts teaching you how to create your first Angular 2 application with ASP.NET Core in Visual Studio Code. Here is the list of posts:

This post is all about automating common development tasks with npm scripts and Visual Studio Code. You learn how to install and clean dependencies, launch browsers, automatically rebuild your .NET code, and setup a build task in Visual Studio Code.

Mac and Linux Users: The commands in this article related to cleaning dependencies and launching browsers are specific to Windows. You can still use npm scripts on Mac and Linux by replacing the Windows commands with those for your environment. Details for specific commands are found readily through your favorite search engine.

.NET Core SDK Preview 3: This tutorial uses .NET Core SDK Preview 3 which is available on GitHub. This version includes 'alpha' support for MSBuild-based projects that use .csproj configuration instead of project.json configuration. Microsoft announced that MSBuild is the common project configuration for .NET Core based projects going forward. By using MSBuild, the goal is to better prepare you for future versions of the tooling.

If you would like to jump straight to the code, it's all on GitHub.

Note: If you have been following along with the series from the beginning, you might have noticed that this post was previously listed as being about Browser Link. Unfortunately, this feature still appears to be heavily tied to the full Visual Studio IDE. The tooling story for ASP.NET Core and Visual Studio Code continues to develop and you can expect more posts on these topics as additional tooling becomes available.

NPM Scripts

For this walkthrough, you are continuing from the npm script you built in part 3. While Visual Studio Code supports a variety of automation tooling, npm scripts are a discoverable and simple way to automate tasks for your project.

The scripts are all located in the package.json file under the "scripts" property. At this point in the walkthrough, this is the current version:

"scripts" : {
    "start": "tsc && concurrently \"tsc -w\" \"dotnet run\" "
},

This script compiles the TypeScript files and then runs the TypeScript compiler in watch mode alongside running the ASP.NET application. You invoke it by entering npm start in the terminal.

Notably, npm has built-in commands as well as custom scripts. For instance, start is a built-in command. You invoke it by entering npm start. However, if you take the same script and call it gyro, it would not be recognized by entering npm gyro because it is not a built-in command. You instead enter npm run gyro into the command line to invoke that script.

It's important to understand that the built-in commands sometimes have special behavior. You can see the full list supported by your version of npm by entering npm -h in the terminal and you can read more about these commands in the documentation.

Installing Dependencies

Part 3 of this series describes how to setup a package.json file and shows how to use npm install to download the dependencies from npm. In part 2, it similarly describes using dotnet restore to do the same thing for .NET Core dependencies. Instead of using these two commands, what if you only had to remember one to install all the dependencies in your project?

The npm install command is one of the npm commands with special behavior. You configure an npm script named install but the commands get executed after the default npm install command has finished. The is the perfect place to call dotnet restore. Add the following to the scripts property:

"scripts" : {
    // ... 
    "install": "dotnet restore"
},

Now when you enter npm install in the terminal, the dotnet dependencies install as well.

Cleaning the Project

In addition to installing dependencies, you should be able to easily delete out-of-date dependencies. Essentially, you need a set of scripts to delete the downloaded packages and build artifacts from the project directory. These commands work well on Windows for this purpose:

"scripts" : {
    // ... 
    "clean": "npm run clean:dotnet && npm run clean:npm",
    "clean:dotnet": "npm run clean:bin && npm run clean:obj",
    "clean:bin": "del /q .\\bin\\*.* && for /d %i in (.\\bin\\*.*) do @rmdir /s /q \"%i\" ",
    "clean:obj": "del /q .\\obj\\*.* && for /d %i in (.\\obj\\*.*) do @rmdir /s /q \"%i\" ",
    "clean:npm": "del /q .\\node_modules\\*.* && for /d %i in (.\\node_modules\\*.*) do @rmdir /s /q \"%i\" "
},

Notice the clean script is composed of multiple npm scripts. When calling multiple commands, concatenate them with two ampersands (&&). The bulk of the work is done with the clean:bin, clean:obj, and clean:npm scripts which delete the contents of the bin, obj, and node_modules folders respectively. Because these commands delete only the contents, they can be called repeatedly without throwing an error.

Also notice that calling these scripts requires the run command. For instance, to call the clean script you type npm run clean in the terminal.

With these scripts, whenever you get an updated version of the repository, type npm run clean follow by npm install in the terminal and you have a fresh copy of the required npm and .NET dependencies. You might even decide to create a new script that calls them both.

Launching the Browser

Another important development task is opening the browser, sometimes multiple browsers, to test your application. This too, is an automation candidate. Here are three commands for launching different browsers to the application URL:

"scripts" : {
    // ... 
    "edge": "start microsoft-edge:http://localhost:5000",
    "chrome": "start chrome http://localhost:5000",
    "firefox": "start firefox http://localhost:5000"
},

Once added, type npm run chrome in the terminal to startup Google Chrome at the development URL.

Watching ASP.NET Code Changes

If you look at the start script, tsc -w initializes the file watcher for the TypeScript compiler. This command watches the file system for any TypeScript file changes and automatically re-runs the TypeScript build. To duplicate this functionality for C# code, use the dotnet watch command.

The dotnet watch command is a dotnet CLI extension. You reference the tool by putting the following in the project's .csproj file:

<ItemGroup>
    <DotNetCliToolReference Include="Microsoft.DotNet.Watcher.Tools" Version="1.0.0-msbuild2-final"/>
</ItemGroup>

You can now use your new npm install script to restore the .NET dependency or simply run dotnet restore to download the package. Once it's installed, modify the build script to use dotnet watch run instead of dotnet run. This is the full scripts property in the package.json file including the dotnet watch change:

"scripts": {
    "start": "tsc && concurrently \"tsc -w\" \"dotnet watch run\" ",
    "install": "dotnet restore",
    "clean": "npm run clean:dotnet && npm run clean:npm",
    "clean:dotnet": "npm run clean:bin && npm run clean:obj",
    "clean:bin": "del /q .\\bin\\*.* && for /d %i in (.\\bin\\*.*) do @rmdir /s /q \"%i\" ",
    "clean:obj": "del /q .\\obj\\*.* && for /d %i in (.\\obj\\*.*) do @rmdir /s /q \"%i\" ",
    "clean:npm": "del /q .\\node_modules\\*.* && for /d %i in (.\\node_modules\\*.*) do @rmdir /s /q \"%i\" ",
    "edge": "start microsoft-edge:http://localhost:5000",
    "chrome": "start chrome http://localhost:5000",
    "firefox": "start firefox http://localhost:5000"
},

Now you can make changes to your C# code while the application is running and when you save the file, the .NET project rebuilds without any developer intervention.

Key Binding for NPM Start

While npm scripts are already easily accessible through the built-in terminal, Visual Studio Code offers a way to map a build task to a keyboard shortcut.

The default build task key binding is Ctrl+Shift+B and it is configurable. To map the npm start command to this task, begin by pressing Ctrl+Shift+B from anywhere in Visual Studio Code. At this point, Visual Studio Code sees that you are using npm scripts and prompts you to create a tasks.json file within the .vscode directory. Press the Configure Task Runner button to create the file.

Configure Task Runner

Now that the file is created, modify the tasks property to map the npm start script. In addition, set the task's isBuildCommand property to true to associate the task with the build command key binding, Ctrl+Shift+B.

{
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "0.1.0",
    "command": "npm",
    "isShellCommand": true,
    "showOutput": "always",
    "suppressTaskName": true,
    "tasks": [
        {
            "isBuildCommand": true,
            "taskName": "start",
            "args": ["start"],
            "isWatching": true            
        }
    ]
}

Save the file and try out the new functionality by pressing Ctrl+Shift+B. You should see the application starting in the terminal. To terminate the task, press F1 and find the command to Terminate Running Task.

Terminate Running Task

You can create additional tasks out of the other npm scripts but Visual Studio Code limits you to having one task running at a time. Furthermore because this build task runs in watch mode, it may be running most of the time you are in the editor. Therefore, it makes sense to continue running your other npm scripts from the terminal.

Build Succeeded

You are now equipped to zip through your development workflow using npm scripts and Visual Studio Code tasks. If you're coming from the Visual Studio IDE, this gives you an idea of how to accomplish some of what the full-fledged IDE provides and hopefully further inspires you to customize the tasks that Visual Studio Code enables.

Now that you have gotten a glimpse at what is possible, what other automated functionality would you like to see? How have you configured Visual Studio Code to help you be more productive? Let everyone know in the comments.