Build 2017 Videos for Angular Developers

Build 2017 Videos for Angular Developers

After watching approximately six hours of keynote videos from Microsoft's Build Conference 2017, it's clear that no single company produces more software for developers than Microsoft. There are tools for virtually every platform. There are SDKs for Windows, Xbox, and Office. You can even use Visual Studio to develop an extension for Visual Studio.

With so many developer products, how do you determine which is relevant to you? That question is the inspiration for this post.

The following is a categorized list of videos from Build 2017 that are most relevant to an Angular web developer. The usual suspects are here including TypeScript, Visual Studio 2017, Visual Studio Code, Progressive Web Apps (PWA), ASP.NET, and Node.js. Going further are newer technologies such as Azure Serverless products, brand-new Cosmos DB, Mixed Reality, Artificial Intelligence offerings, and the debut of Fluent Design.

For the full list of all 450 videos, visit the event page on Channel9. Also if you find a favorite video absent from the list, please leave a comment.

Angular and Front-End

Tooling

Visual Studio Code

Visual Studio 2017

More Tooling

ASP.NET

Node.js

Azure – Serverless

Keynotes

Mixed Reality

Azure – Cosmos DB

Microsoft Graph

Fluent Design

Artificial Intelligence (AI)

Bot Framework

Cognitive Services

More AI

Favorite Talks from ng-conf 2017

ng-conf 2017 Favorite Talks

In early April, Angular developers from around the world attended ng-conf 2017. It's arguably the biggest Angular event of the year and it's always loaded with the latest Angular technologies and techniques. Having gone through much of this year's videos, here are some favorites with notes to help you decide if a video is relevant to you.

Thank you to everyone who makes this event great every year and for sharing the experience with those who couldn't be there in person. Enjoy the videos!

It's All About the Angular Baby and Angular Router Authentication and Authorization Real LIVE LIVE LIVE LIVE LIVE
Shai Reznik

These videos are for straight comedic value. Shai Reznik is the creator of the infamous ng-wat video from ng-conf two years ago. While It's All About the Angular Baby is pure entertainment. However, Shai manages to teach you a few things while making you laugh in his authentication and authorization talk.

Everything is a plugin! Mastering webpack from the inside out
Sean Larkin

This is a must-watch if only for the fact that Sean Larkin walks you through how to debug a webpack build. The talk is divided into 3 parts. First, Sean explains the different pieces of a webpack build with a hand-drawn illustration. If you're looking to save time going through this two-hour video, consider skipping the second part which is answering questions and handing out shirts. A highlight during this part is that WebAssembly is apparently an important technology on webpack's roadmap.

Finally, the talk continues with a workshop on creating a webpack plugin. Grab your laptop. Sean walks through the process step-by-step, answering questions along the way (including how to get some Mac commands to work on Windows). A personal favorite, he demonstrates the important skill of debugging webpack. Visit this timestamp to skip ahead to the walkthrough. This talk is highly recommended.

I am one with Angular, Angular is one with me
John Papa

This is a relatively short, 20-minute talk on tooling. John walks through his favorite features of the Angular CLI, Visual Studio Code, and Angular v4 TypeScript Snippets. He also touches on the new language service plugin for Visual Studio Code which provides IntelliSense for template bindings.

The Angular CLI has so many features and John demonstrates the dry-run flag, lazy loading routes, and automatically providing newly-generated services. You also see how insanely productive he is using the Angular v4 TypeScript Snippets plug-in for Visual Studio Code. Watch this talk to level up your Angular-Fu!

Using the Angular Template Language Service
Chuck Jazdzewski

This is a great overview on the status of the Angular Language Service. This service works with TypeScript to provide IntelliSense and easy refactoring capabilities in your Angular markup. It promises to provide compile-time checking for template errors that are currently only detectable at runtime. Chuck covers everything, discussing the tooling's architecture, roadmap, and editor support.

Thoughtful Component Design
Jeremy Elbourn and Miles Malerba

This talk is presented by two members of the Angular Material team where they discuss their findings from building a component library. There are many useful topics discussed. How do you maintain native DOM behavior for elements like INPUT while providing enhanced functionality with Angular? How and when should you 'touch the DOM'? For anyone looking to improve their component API design, this talk delivers.

Packaging Angular
Jason Aden

This talk is critical to anyone using Angular across teams in a large organization. Jason discusses the best practices for sharing components in an npm package. What should you include? He goes over including AOT support, Type Definitions, metadata files and shows how to create and optimize these artifacts. He provides straight-forward advice such as using one NgModule per Component and discusses build optimizations using the Closure Compiler.

From Inactive to Reactive with ngrx
Brandon Roberts & Mike Ryan

This is an introduction to the ngrx library for state management. The talk covers the basics of the ngrx libraries as well as the concepts it leverages from redux. This is recommended for anyone new to ngrx or redux.

Keynote Day 3
Brad Green and Rob Wormald

This is really two talks in one. Brad gives a peek behind the curtain at Google's process for adopting new technologies and how that influences their decisions with Angular. While this doesn't necessarily affect most developers, it's an interesting story nonetheless.

In the second part of the talk, Rob Wormald discusses the importance of new features including platform-server (Angular Universal) and Angular Mobile which promise to provide increased performance and SEO capabilities to Angular applications.

Angular Pre-Rendering for SEO, Speed, and Happy Users
Jeff Cross

This is about platform-server (Angular Universal). This framework has now moved under development by the Angular team. It provides server-side rendering for Angular applications. This provides several benefits including improved performance, better scrape-ability for social scrapers, and better SEO for crawlers.

Jeff goes into many of the aspects of implementing these benefits and highlights some of the tradeoffs and considerations at play. If these benefits matter to your site, this is a very well done presentation.

Automatic Progressive Web Apps using the Angular Mobile Toolkit
Maxim Slanikov

This talk is all about the Angular Mobile framework which aims to provide out-of-the-box progressive web app (PWA) features for Angular developers. Many consider PWAs to be (at least part of) the future of delivering applications to devices. It appears that this framework is still in the preview stages and Maxim cautions about existing documentation. If PWAs are important to you, find out how to get started with this talk.

The Angular Compiler 4.0
Tobias Bosch

This is an inside look at the changes made to the compiler in Angular 4. Tobias explains how the Angular compiler works and what it produces. He further explains what was changed to improve performance as well as the test data proving the results.

Docker: What Every Angular Developer Should Know About It!
Dan Wahlin

As the title suggests, this talk is about Docker. Dan takes an application created with the Angular CLI and hosts it on Nginx inside of a Docker container. He goes through the main benefits and features of Docker relevant to web developers and demonstrates their implementation. Dan is a great speaker and if you are new to Docker, this is a great overview.

The Day I Met Steve
Alyssa Nicoll

This is a short soft-skills talk but one that's important. Alyssa looks at how and why developers get discouraged at work. She provides some useful tips on how to avoid this path ourselves and how to create an environment where everyone feels their contributions matter.

Whether you work with WordPress sites or not, Roy explains how and why you might want to start. WordPress claims to run 27% of the internet and there is a large community of support for this system. How can you leverage this support for your Angular applications? The answer is to use the WordPress REST API and this talk gives an overview of how it works. It also has a lot of cat pictures if you're into that kind of thing.

In Summary

There are over 60 videos posted from the conference and this is only a sampling. To watch more, check out the playlists on YouTube. If you have a favorite, please mention it in the comments below.

ASP.NET Core JavaScript Services with Webpack HMR

ASP.NET Core JavaScript Services with Webpack HMR Hero

Derived from photo by Alasdair / flickr.com, CC BY

This tutorial covers two aspects of the ASP.NET Core JavaScript Services library. First, MapSpaFallbackRoute, is a utility to help redirect client-side routes to the browser. Second is a utility for integrating webpack dev middleware as ASP.NET Core middleware. This provides webpack's hot module replacement (HMR) functionality integrated with the ASP.NET Core request pipeline. When this is enabled, the code in the browser automatically replaces the updated ES2015 module without a full application refresh. This is an incredibly productive development setup.

The tutorial uses Visual Studio Code as the editor. If you would like to go directly to the completed example, the code is on GitHub.

Initial Setup

  1. Follow the steps in this post to create an 'empty' Angular, ASP.NET Core project using the Angular and dotnet command line interfaces (CLI). The rest of the tutorial builds off this base project.
  2. Next, add the code for multiple components to the project's src/app directory. Upon completion, the files should be in this structure with the following contents:

    ├── src
    |   ├── app
    |   |   └── app.component.ts
    |   |   ├── app.module.ts
    |   |   ├── base.component.html
    |   |   ├── main.component.ts
    |   |   └── other.component.ts
    

    app.component.ts

    import { Component } from '@angular/core';
    
    // exported to use with webpack HMR
    export const rootElementTagName = 'app-root';
    
    @Component({
    selector: rootElementTagName,
    template: `
      <nav>
        <a routerLink="/main">main</a> |
        <a routerLink="/other">other</a>
      </nav>
      <router-outlet></router-outlet>
    `
    })
    export class AppComponent { }
    

    base.component.html

    <h1>
    {{title}}
    </h1>
    

    main.component.ts

    import { Component } from '@angular/core';
    
    @Component({
    selector: 'app-main',
    templateUrl: './base.component.html'
    })
    export class MainComponent {
    title = 'this is the main component';
    }
    

    other.component.ts

    import { Component } from '@angular/core';
    
    @Component({
    selector: 'app-other',
    templateUrl: './base.component.html'
    })
    export class OtherComponent {
    title = 'this is the other component';
    }
    
  3. Finally, configure components in the NgModule app.module.ts.

    app.module.ts

    import { BrowserModule } from '@angular/platform-browser';
    import { NgModule } from '@angular/core';
    import { FormsModule } from '@angular/forms';
    import { HttpModule } from '@angular/http';
    import { RouterModule, Routes } from '@angular/router';
    
    import { AppComponent, rootElementTagName } from './app.component';
    import { MainComponent } from './main.component';
    import { OtherComponent } from './other.component';
    
    const routes: Routes = [
    { path: '', redirectTo: '/main', pathMatch: 'full' },
    { path: 'main',  component: MainComponent },
    { path: 'other', component: OtherComponent },
    ];
    
    @NgModule({
    declarations: [
      AppComponent,
      MainComponent,
      OtherComponent
    ],
    imports: [
      BrowserModule,
      FormsModule,
      HttpModule,
      RouterModule.forRoot(routes)
    ],
    providers: [],
    bootstrap: [AppComponent]
    })
    export class AppModule { }
    
    export { rootElementTagName } from './app.component';
    

    Now run the application in Visual Studio Code using F5. The client-side routes are configured and you can switch between the main and other views.

Configure Server-Side Routing with MapSpaFallbackRoute

The ASP.NET Core JavaScript Services library includes a utility to configure single page application (SPA) routing. This enables the server to handle any requests intended for the Angular router by returning the Angular application to the browser. Once the browser loads the Angular application, Angular takes over the URL routing. For more information on how Angular and ASP.NET Core routes integrate, see this post.

These steps configure server-side routing.

  1. Within the project directory, use the command dotnet add package Microsoft.AspNetCore.SpaServices to add the ASP.NET Core JavaScript Services library to the project. Restore the new package when Visual Studio Code displays the prompt or by using the command dotnet restore.

  2. In the Startup.cs file add the ASP.NET MVC service as well as the MapSpaFallbackRoute:

    Startup.cs

    using Microsoft.AspNetCore.Builder;
    using Microsoft.AspNetCore.Hosting;
    using Microsoft.AspNetCore.SpaServices.Webpack;
    using Microsoft.Extensions.DependencyInjection;
    using Microsoft.Extensions.Logging;
    
    namespace my_directory
    {
    public class Startup
    {
      // This method gets called by the runtime. Use this method to add services to the container.
      // For more information on how to configure your application, visit https://go.microsoft.com/fwlink/?LinkID=398940
      public void ConfigureServices(IServiceCollection services)
      {
        services.AddMvc();
      }
    
      // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
      public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
      {
        loggerFactory.AddConsole();
    
        if (env.IsDevelopment())
        {
          app.UseDeveloperExceptionPage();
        }       
    
        app.UseDefaultFiles();
        app.UseStaticFiles();     
    
        app.UseMvc(routes => {
          routes.MapSpaFallbackRoute(
            name: "spa-fallback",
            defaults: new { controller = "Home", action = "Index" });
        });
      }
    }
    }
    

    Note: Ensure that the namespace my-directory is replaced with the namespace of your application.

  3. The MapSpaFallbackRoute points to a HomeController. Create a Controllers directory and add this controller as a pass-through to simply return the Angular application for routes that should be addressed on the client.

    HomeController.cs

    using Microsoft.AspNetCore.Mvc;
    
    public class HomeController : ControllerBase
    {
      public IActionResult Index()
      {
          var fileName = "index.html";
          var contentType = "text/html";
    
          return File(fileName, contentType);
      }
    }
    

Run the application with F5. Go directly to the URL http://localhost:5000/other in the browser's address bar (not by linking from within the application) and see that the Angular application successfully loads the route.

Configure Hot Module Replacement

One of the more compelling features of webpack is its ability to apply code updates in the browser while the application is running so you can quickly see the resulting changes. This is webpack's Hot Module Replacement (HMR) feature and the JavaScript Services library includes the ability to integrate with this functionality using ASP.NET Core middleware.

  1. Type ng eject in the terminal to have Angular CLI switch the configuration to a webpack-based configuration. At this point any configuration changes that you want to make to the build must be done through the webpack configuration. The Angular CLI configuration no longer applies.

  2. Run npm install aspnet-webpack webpack-hot-middleware -D to download required Node.js packages. Also, run npm install to ensure all the new webpack package dependencies are downloaded.

  3. Configure the webpack middleware in the Startup.cs file. Add the webpack dev middleware configuration within the env.IsDevelopment() conditaion. By default, Visual Studio Code configures ASP.NET Core to run in Development mode so this condition evaluates to true.

    Startup.cs

    // ...
    public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
    {
    // ...
    if (env.IsDevelopment())
    {
      app.UseDeveloperExceptionPage();
      app.UseWebpackDevMiddleware(new WebpackDevMiddlewareOptions {
        HotModuleReplacement = true
      });
    }
    
    app.UseDefaultFiles();
    
    // ...
    }
    
  4. When running the project with webpack HMR, you do not need to build with webpack as part of the .csproj build. Update this configuration to avoid the extra processing at compile time. By default, the build runs with a 'Debug' configuration which will not trigger the webpack build.

    my-directory.csproj

    <Target Name="AngularBuild" AfterTargets="Build">
    <Exec Condition="'$(Configuration)' == 'Release'" Command="npm run build" />
    </Target>
    

    Note: Attentive readers may notice that the tutorial uses ASP.NET Core configuration for enabling the webpack dev middleware and alternatively a build configuration constant for enabling the non-HMR build. This tutorial focuses on improving the developer experience with webpack HMR. There are many options for synchronizing these configurations to be explored in future posts.

  5. Set "publicPath" to "/" in the webpack.config.js file under the "output" section.

    "output": {
    "path": path.join(process.cwd(), "wwwroot"),
    "filename": "[name].bundle.js",
    "publicPath": "/",
    "chunkFilename": "[id].chunk.js"
    },
    
  6. Finally, you must handle the HMR changes in the browser to refresh the Angular application with updated modules. Add a TypeScript file to the src directory named handleHotModule.ts and use it to handle the HMR changes during the Angular bootstrap process in main.ts.

    handleHotModule.ts

    import { Type, PlatformRef } from '@angular/core';
    
    interface HotModule extends NodeModule {
    hot?: HotModuleHandler;
    }
    
    interface HotModuleHandler {
    accept: () => void;
    dispose: (callback: () => void) => void;
    }
    
    export function handleHotModule(
    bootstrapModule: HotModule,
    rootElemTagName: string,
    platform: PlatformRef,
    bootFunction: (isModuleHot: boolean) => void
    )  : void {
    const isModuleHot = !!bootstrapModule.hot; 
    
    if (isModuleHot) {
      bootstrapModule.hot.accept();
      bootstrapModule.hot.dispose(() => {
        const oldRootElem = document.querySelector(rootElemTagName);
        const newRootElem = document.createElement(rootElemTagName);
        oldRootElem.parentNode.insertBefore(newRootElem, oldRootElem);
        platform.destroy();
      });
    }
    
    if (document.readyState === 'complete') {
      bootFunction(isModuleHot);
    } else {
      document.addEventListener('DOMContentLoaded', () => {
        bootFunction(isModuleHot);
      });
    }
    }
    

    main.ts

    import { enableProdMode } from '@angular/core';
    import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
    
    import { AppModule, rootElementTagName } from './app/app.module';
    import { environment } from './environments/environment';
    import { handleHotModule } from './handleHotModule';
    
    const platform = platformBrowserDynamic();
    
    handleHotModule(module, rootElementTagName, platform, isModuleHot => {
    if (environment.production && !isModuleHot) {
      enableProdMode();
    }
    
    platform.bootstrapModule(AppModule);
    });
    

    Now run the application. After the application loads, make a change to one of the components and save the file. Upon saving, you see the update appear in the browser almost immediately after you press save in the editor.

Your New Developer Experience

Welcome to your new developer experience with ASP.NET Core and Angular powered by webpack and ASP.NET Core JavaScript Services. The ASP.NET Core JavaScript Services library has so much more including server-side pre-rendering with Angular Universal and lower level utilities to interface with Node.js code.

Take some time to look at the respository on GitHub. There are additional details included there for your reference.

Give this setup a try and drop a comment about your experience. What other build configurations and developer features do you want to see featured on the blog?

Get Going with the Angular and ASP.NET CLIs

Angular and ASP.NET CLIs Header

When learning Angular and ASP.NET Core, it's oftentimes helpful to start with an empty project. However, there are some integration steps required to have Angular and ASP.NET Core work together.

This tutorial shows how to create an Angular, ASP.NET Core project using the command line interfaces (CLI) for both Angular and .NET Core. It demonstrates how to host and debug an ASP.NET Core project in Visual Studio Code.

Prerequisites

The following must be installed to complete this tutorial:

Note: The commands in this article work on a Windows machine with PowerShell. Other platforms may require modifications.

Configure Angular

  1. Install Angular CLI globally to make the commands available in any directory

    npm install -g @angular/cli
    
  2. Use the newly installed Angular CLI to scaffold a new project. This command creates a new directory to house your application. It may take a couple minutes to complete because the utility installs the npm packages for Angular, the build, and testing.

    ng new my-directory
    
  3. Navigate into the repository and verify the application by running it with the Angular CLI. Use the --open argument to open the application in the default browser.

    cd my-directory
    ng serve --open
    

    The Angular CLI runs the application on a Node.js web server and you will see the stub page.

    Angular CLI Stub Page

  4. Terminate the running web server with the key combination Ctrl + C to continue in the command window.

Configure ASP.NET Core

  1. In the repository, use the .NET Core CLI to scaffold an empty ASP.NET Core project.

    dotnet new web
    

    Note: The dotnet new command scaffolds the .NET project within the current working directory whereas the Angular CLI command ng new creates a new directory to contain the generated Angular code.

  2. Install the ASP.NET static file support middleware.

    dotnet add package Microsoft.AspNetCore.StaticFiles
    
  3. Open the repository in Visual Studio Code

    code .
    
  4. Visual Studio Code prompts you to configure the application and to restore .NET packages. Press Yes and Restore respectively. The editor generates a .vscode folder containing configuration files and downloads the .NET Core dependencies.

    .NET Core Configuration Prompt

    Tip: If the prompt doesn't appear initially, open a C# file in the editor.

  5. Configure the Angular CLI to output the Angular build to the wwwroot folder. Open the .angular-cli.json configuration file and change "outDir": "dist" to "outDir": "wwwroot".

    {
    // ...
    "apps": [
     {
        "root": "src",
        "outDir": "wwwroot",
        // ...
    }
    }
    
  6. Configure static file support in the Startup.cs file. The Configure method should have the following code.

    public void Configure(IApplicationBuilder app,
      IHostingEnvironment env, ILoggerFactory loggerFactory)
    {
      loggerFactory.AddConsole();
    
      if (env.IsDevelopment())
      {
          app.UseDeveloperExceptionPage();
      }
    
      app.UseDefaultFiles();
      app.UseStaticFiles();
    }
    
  7. Add a build step to the .csproj file to build the Angular application with the Angular CLI.

    <Target Name="AngularBuild" AfterTargets="Build">
      <Exec Command="npm run build" />
    </Target>
    
  8. Press the F5 key to run the ASP.NET application with Visual Studio Code's debugger. The Angular application is now hosted from ASP.NET Core instead of Node.js. Notice how ASP.NET Core uses port 5000 by default as opposed to 4200 with the Angular CLI.

    Angular CLI Stub Page on ASP.NET Core

    Completed Startup.cs Code:

    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Threading.Tasks;
    using Microsoft.AspNetCore.Builder;
    using Microsoft.AspNetCore.Hosting;
    using Microsoft.AspNetCore.Http;
    using Microsoft.Extensions.DependencyInjection;
    using Microsoft.Extensions.Logging;
    
    namespace my_directory
    {
      public class Startup
      {
          // This method gets called by the runtime. Use this method to add  services to the container.
          // For more information on how to configure your application, visit  https://go.microsoft.com/fwlink/?LinkID=398940
          public void ConfigureServices(IServiceCollection services)
          {
          }
    
          // This method gets called by the runtime. Use this method to  configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app,
            IHostingEnvironment env, ILoggerFactory loggerFactory)
        {
            loggerFactory.AddConsole();
    
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
    
            app.UseDefaultFiles();
            app.UseStaticFiles();
        }
      }
    }
    

    Completed my-directory.csproj Code:

    <Project Sdk="Microsoft.NET.Sdk.Web">
    <PropertyGroup>
      <TargetFramework>netcoreapp1.1</TargetFramework>
    </PropertyGroup>
    
    <ItemGroup>
      <Folder Include="wwwroot\" />
    </ItemGroup>
    
    <ItemGroup>
      <PackageReference Include="Microsoft.AspNetCore" Version="1.1.1" />
      <PackageReference Include="Microsoft.AspNetCore.StaticFiles"  Version="1.1.1" />
    </ItemGroup>
    
    <Target Name="AngularBuild" AfterTargets="Build">
      <Exec Command="npm run build" />
    </Target>
    </Project>
    

Conclusion

The tooling has finally come together for both Angular and ASP.NET so that anyone can easily create an application using the command line.

Use the steps here to build the foundation and then move to integrate other features like routing and authentication. In fact, learn to integrate routing right here.

Have you been using the CLI for Angular or ASP.NET Core? What do you like or dislike about them? Please leave a note in the comments.

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.