---

October 2015

Volume 30 Number 10

ASP.NET - ASP.NET 5 Anywhere with OmniSharp and Yeoman

By Sayed Ibrahim | October 2015

As development teams have become more diverse in their tooling choices, frameworks must also provide choice without friction. ASP.NET 5 has embraced cross-platform support, including development through open source tooling such as OmniSharp and hosting in Microsoft Azure using containers like Docker. In this article, we’ll show you how you can get started with ASP.NET 5 on the platform of your choice. We’ll cover all that you need to begin developing Web applications with ASP.NET 5.

Getting a project up and running can be difficult, as modern Web application development is also riddled with choice. As a Visual Studio user, you might’ve been almost spoiled by benefiting from the IDE, built-in templates and tooling such as Web Essentials to assist you in getting a new project off the ground. But developers not using Windows and a rich IDE, such as Visual Studio, have generally relied on command-line tooling such as Yeoman, Grunt or Gulp, or Node.js to construct and build Web applications. Now ASP.NET 5 has been rebuilt from the ground up with all platforms in mind, taking the “choice is king” approach for developer tooling. Now you can use it not only for your Windows projects, but also for Linux and OS X. Here’s a brief look at setting up and creating a project from a non-Windows OS perspective using ASP.NET 5.

Setting Up Your Environment

You’ll need a few pieces to get your environment set up, but the process is well-documented for both OS X and Linux. You’ll find step-by-step instructions at bit.ly/1Ljhj68. For this article, we’ll assume most of you are using OS X.

The first step is to install the tools we’ll use to build our ASP.NET 5 Web application. Eventually, CoreCLR (github.com/dotnet/coreclr) will be the base runtime for the framework. For now, however, ASP.NET 5 still requires the Mono runtime. To install Mono, use HomeBrew (brew.sh):

$ brew install mono

Next, install the .NET Version Manager (DNVM), a set of command-line utilities that lets you update and configure your .NET execution environment (DNX), which essentially enables cross-platform development using the .NET Core 5 (docs.asp.net/en/latest/dnx/). To install DNVM and DNX from your terminal, execute the following commands:

$ brew tap aspnet/dnx
$ brew update
$ brew install dnvm

Now you’ve installed the Mono runtime, plus DNVM and DNX. To check your DNVM version, type “$ dnvm” at the terminal, as shown in Figure 1. Note that if your shell doesn’t recognize the dnvm command, you might need to execute “source dnvm.sh” to load it.

Figure 1 Checking the DNVM Version

Choosing an Editor

If you’re using Windows, there’s not much debate; you’re going to use some version of Visual Studio. However, on OS X or Linux you have a number of choices, from a simple text editor like TextMate to a variety of popular editors such as Sublime, Atom, Emacs or Vim. But there’s a new addition to the list of cross-platform development editors—Visual Studio Code (code.visualstudio.com) from Microsoft—and it’s our editor of choice not just for ASP.NET 5, but also for AngularJS, Node.js and general JavaScript development (see Figure 2).

Figure 2 The Visual Studio Code Welcome Page

No matter which tool you decide to use, the key to lighting up the editor for ASP.NET 5 on OS X and Linux is OmniSharp (omnisharp.net). Visual Studio Code comes with OmniSharp built in; other editors have extension or “add-in” repositories where the component can be downloaded.

Starting Your First Project

Without the rich Visual Studio 2015 development environment, you’ll have to rely on a different approach for developing an ASP.NET 5 application on OS X. Enter Yeoman (yeoman.io) and the ASP.NET generator project (bit.ly/1MPe5KY). Yeoman is a scaffolding platform built on top of Node.js that allows you to build template-based generators for projects or code files. It’s a command-line utility and because it’s built on Node.js, there are a few dependencies you’ll need to take care of first.

To start, install Node.js and the node package manager (NPM) either via HomeBrew or directly from nodejs.org:

$ brew install node

When that’s complete, install the generators using npm:

$ npm install -g yo generator-aspnet

If you’re not already using Bower, Grunt or Gulp, grab those tools, as well. You’ll want to become familiar with these tools as part of the new, modern development stack (see the article “Modern Tools for Web Development: Bower” in this issue):

$ npm install -g bower grunt-cli gulp-cli

Bower is a package manager for front-end Web development, and a repository for Web resources such as JavaScript and CSS. Grunt and Gulp are task-running libraries for performing build processes such as script and image minification and transpiling (TypeScript or CoffeeScript).

That’s it for setting up the tooling you need for development, regardless of the editor. Now, to kick off the new project type, execute “$ yo aspnet” to initialize the Yeoman generator and select the project you’d like to create. In this case, select “Web Application Basic [without Membership and Authorization].” as shown in Figure 3, then type your project name and press enter.

Figure 3 Selecting the Project Type in Yeoman

After the generator completes, you have the option of running the application using the Kestrel cross-platform Web server. First, however, you’ll need to install the npm, Bower and NuGet dependencies, so run the restore command to get these resources:

$ cd [projectname]
$ dnu restore

This command downloads all of the NuGet packages for the project referenced in the project.json file.

(We also run “$ npm install” and “$ bower install” to ensure the JavaScript and UI component resources are up-to-date, but this isn’t required.)

Next, run the command to start Kestrel:

$ dnx . kestrel

(Note that after ASP.NET 5 Beta 7 is released, this command will change to simply “dnx kestrel.”)

The word “Started” will appear in the terminal window and you’ll now be able to view the Web site by browsing to https://localhost:5000. At this point you’ve created the project, restored packages and run the site without Windows or Visual Studio. Next, you’ll open the code in Visual Studio Code.

Editing ASP.NET

As noted earlier, Visual Studio Code is a great editor for cross-platform development. Open the project either the usual way or by using the keyboard shortcut “code” from the project folder. (See bit.ly/1LwonPN for how to set up the “code” shortcut.)

Once you’ve opened the source folder in Visual Studio Code, you can start to develop the application. Figure 4 shows the result when you open the project in Code.

Figure 4 Opening a Project in the Visual Studio Code Editor

As you can see, you get the full syntax highlighting for C# files that you’d expect—in Mac OS X! If you look closely, you’ll see a light bulb near the cursor at line 2. The light bulb, just as in Visual Studio, can be used to perform quick actions that are contextual. In this case, Visual Studio Code offers the suggestion to Remove Unnecessary Usings. Now let’s add new files to your project.

To add a new file to your ASP.NET 5 project, you don’t need to do anything special. Just add a file to the directory and it will automatically be included. In Code you can use the Add File button in the tree view, or Ctrl+N to add a new blank file. If you’d like to get started with some initial content, you can use “yo aspnet.” To add files to existing ASP.NET 5 projects, you invoke a sub-generator using the following syntax:

$ yo aspnet:<Name> <options>

To demonstrate this, let’s add a new MVC controller and View for a new Admin page for the Web application. We’ll add the MVC controller first. When yo aspnet executes, it will add files to the current working directory, so you’ll want to cd into the correct directory before executing the commands. To add the MVC controller, execute the following command in the Controllers folder:

yo aspnet:MvcController AdminController

After executing the command, you’ll see a new file, Hello.cs, in the current working directory with the content shown in Figure 5.

Figure 5 Hello.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNet.Mvc;
// For more information on enabling MVC for empty projects, visit
// go.microsoft.com/fwlink/?LinkID=397860
namespace MyNamespace
{
  public class AdminController : Controller
  {
    // GET: /<controller>/
    public IActionResult Index()
    {
      return View();
    }
  }
}

The file looks the same as when you use File | New Item in Visual Studio and select MVC Controller, except that here the namespace name isn’t automatically updated; instead, it’s hardcoded as MyNamespace. For now you’ll need to update the namespace declaration to match what you expect, but this will be updated in a future version. The MvcController sub-generator is just one of many sub-generators available in yo aspnet. To see the full list of sub-generators, you can execute:

$ yo aspnet --help

The sub-generators in yo aspnet are equivalent to the item templates in Visual Studio when you use File | Add New Item. To add a view, use the MvcView sub-generator. To add the Admin view, execute the following command from the Views folder:

$ yo aspnet:MvcView Index

The resulting view, Index.cshtml, is pretty basic:

@*
  // For more information on
  // enabling MVC for empty projects,
  // visit bit.ly/1PBdyKc
*@
@{
  // ViewBag.Title = "Index Page";
}

Once again, the content generated using yo aspnet is equivalent to the Add New Item dialog in Visual Studio. In the Index.cshtml file you can add a header so you can browse to this page and verify that everything works:

<h1>Admin Page</h1>

Now let’s see what we need to do to build and run this application.

Previously we mentioned that you can use the command “dnx . kestrel” to run your application. If you’re using Code you can start the Web server using the command palette shown in Figure 6.

Figure 6 Starting a Web Server in Visual Studio Code

When you use Code, your project will build behind the scenes using OmniSharp whenever your source files change. To see any errors and warnings in Code, such as those shown in Figure 7, use the errors and warnings button in the status bar. As you can see, Code is indicating bad code at line 16.

Figure 7 Viewing Errors and Warnings in Visual Studio Code

You can also build your project from the command line. Let’s say your new AdminController class has a build error. To build the application on the command line, execute:

$ dnu build

This should give you the same errors and warnings that Code shows. Now that you’ve seen how to build and run your application, let’s move on to briefly discuss debugging and deployment.

Debugging

Currently, ASP.NET 5 debugging isn’t supported on any platform except Windows and Visual Studio, and that means you can’t debug an ASP.NET 5 application running on Mono for OS X or Linux. ASP.NET 5 applications are compiled using the Roslyn compiler, not the Mono compiler, and no debug information is emitted. Visual Studio Code doesn’t support debugging yet, but you can always use Visual Studio in a virtual machine on your Mac or Linux machine. Hopefully the Visual Studio Code team will be able to support debugging after the CoreCLR is released.

Deployment

You’ve learned how to develop your application locally; now let’s take a quick look at the hosting options. A detailed examination of this topic would require its own article, so we’ll just present a high-level overview and point you to some external resources. Visit bit.ly/1fvDQ41 for the latest information.

At a high level, here are the publishing options for ASP.NET 5:

• Command-line publishing using the “dnu publish” command-line utility
• Publishing to Azure Web Apps using Git
• Publishing to a Docker container running in Azure

The line dnu publish command is at the center of each publish method. It will package your application in a format that’s runnable on Web servers. Let’s take a closer look.

To get started and to to see the available command-line options, execute:

dnu publish –help

Figure 8 shows the result of executing this command.

Figure 8 Getting Help with the “dnu publish” Command

The most important command-line option is the --out (-o) argument, which lets you specify the folder to which your files should be published. But you’ll also want to explore the other options as needed.

Once you’ve published the application to a folder, you just need to copy that folder to your Web server. If you’re publishing to a Windows machine running IIS, you can configure your Web site just as you always have. For information about how to get your Web server configured on Linux, see bit.ly/1E8uebl.

If you’re publishing to Azure, ther’s some support you can use to get started. Azure supports ASP.NET 5 applications in Azure Web Apps, as well as in Docker containers. To deploy to Azure Web Apps from a non-Windows machine, you can use either FTP or Git. For the FTP case, you publish the results of dnu publish. See bit.ly/1LnFC2T for more information.

The Git-based publish model is easy to use and can support continuous deployment scenarios. To get started publishing to Azure Web Apps using Git, see bit.ly/1hQljS0. That’s all you need to know to get started developing and running ASP.NET 5 applications on the platform of your choice.

Wrapping Up

Developing Web applications with ASP.NET used to require that you use Windows and Visual Studio. Now you can use ASP.NET 5 and the related command-line utilities and tools on any platform. And this is just the beginning. To keep an eye on the latest news for ASP.NET 5, visit github.com/aspnet/Home. The yo aspnet project is completely community-driven. If you’re interested in helping out, please open an issue at bit.ly/1PvtcGX.

---

Shayne Boyer is an ASP.NET MVP, community speaker and a solutions architect in Orlando, Fla. He has been developing Microsoft-based solutions for the past 20 years. Over the past 10 years, he has worked on large-scale Web applications, with a focus on productivity and performance. You can reach Shayne on Twitter @spboyer and his Web site at tattoocoder.com.

Sayed Ibrahim Hashimi is a senior program manager at Microsoft on the Visual Studio Web team. He has written several books on Microsoft technologies and is the creator of SideWaffle and TemplateBuilder, as well as co-creator of OmniSharp. You can reach Sayed on Twitter at @SayedIHashimi and his blog sedodream.com.

Thanks to the following Microsoft technical expert for reviewing this article: Scott Hanselman