Understanding the New Cross-Platform .NET, part 4 (demo walkthrough)

Tweet about this on TwitterShare on Facebook0Share on Google+0Share on LinkedIn0Share on Reddit0Email this to someone

We started this four-part series by taking the traditional monolithic .NET Framework, and comparing it to its new modular and cross-platform .NET Core sibling.  Microsoft .NET logoThen we dove into ASP.NET vNext, a family of open-source frameworks and build tools for deploying cross-platform apps.  In the third part we looked at the IDE’s and other tooling under the Visual Studio brand.

Now we will wrap everything up, with a walkthrough demonstrating how to create and deploy a new cross-platform app.  First, let’s have a quick recap of the main .NET concepts we’ve seen so far, and the Java concepts which they more or less match:

.NET conceptAnalogous Java concept
.NET implementation (i.e. Framework, Mono, or Core)JRE
.NET FrameworkOracle's proprietary Java binaries
.NET CoreUpcoming Java 9, with "Project Jigsaw" modular redesign
DNUMaven or Gradle
DNVMJava currently has no similar concept. However, this is comparable to RVM for Ruby, or virtualenv for Python.
ASP.NET vNextA mash-up of Spring/JEE, Hibernate/JPA, and a Spring Boot-like system for creating and deploying apps.

[1] Install .NET Version Manager (dnvm)

This tool is basically a PowerShell script on Windows, or a bash script on Linux and OS X.  For this example I’m working on a Windows machine, so I installed “dnvm” by opening a command-prompt window and running:

@powershell -NoProfile -ExecutionPolicy unrestricted -Command "&{$Branch='dev';iex ((new-object net.webclient).DownloadString('https://raw.githubusercontent.com/aspnet/Home/dev/dnvminstall.ps1'))}"

The process is somewhat different for OS X or Linux, although just as easy.  Check the main README page in the ASP.NET GitHub repo for current specifics.  Even on Windows, you should go there to confirm the above command in case it’s out-of-date (things are moving quickly right now!).

If everything succeeded, then you should be able to type “dnvm” from a command-prompt and see something like this:

You must specify a command!
   ___  _  ___   ____  ___
  / _ \/ |/ / | / /  |/  /
 / // /    /| |/ / /|_/ /
/____/_/|_/ |___/_/  /_/
.NET Version Manager v1.0.0-beta4-10356
By Microsoft Open Technologies, Inc.

usage: dnvm  []

    alias      Lists and manages aliases
    help       Displays a list of commands, and help for specific commands
    install    Installs a version of the runtime
    list       Lists available runtimes
    name       Gets the full name of a runtime
    setup      Installs the version manager into your User profile directory
    upgrade    Installs the latest version of the runtime and reassigns the specified alias to point at it
    use        Adds a runtime to the PATH environment variable for your current shell

[2] Update DNX Versions, and Make .NET Core Active

Get the latest DNX versions for your platform installed by executing:

dnvm upgrade

At the time of this writing, this currently isn’t working on OS X.  By default, “dnvm” downloads DNX versions from a “stable” feed.  “Stable” versions do not yet exist for non-Windows platforms.  You can override this, and download cutting-edge “unstable” versions by adding a “-u” argument.  Hopefully though, this might be a moot point by the time you read this.

You can now run:

dnvm list

… to see which DNX versions are installed on your machine.  The output should look like this:

C:\Users\Steve>dnvm list

Active Version           Runtime Architecture Location                     Alias
------ -------           ------- ------------ --------                     -----
       1.0.0-beta4       clr     x64          C:\Users\Steve\.dnx\runtimes
       1.0.0-beta4       clr     x86          C:\Users\Steve\.dnx\runtimes 
       1.0.0-beta4       coreclr x64          C:\Users\Steve\.dnx\runtimes 
       1.0.0-beta4       coreclr x86          C:\Users\Steve\.dnx\runtimes
  *    1.0.0-beta4-11566 clr     x86          C:\Users\Steve\.dnx\runtimes default

The “active” DNX version is the one currently loaded into your system PATH.  When you use “dnu.exe” or “dnx.exe” from the command-line, the executables from this installed version will be invoked.  Initially, the active instance is a full-fledged monolithic “.NET Framework” version.  We want to change this, so that we’re using “.NET Core” instead:

C:\Users\Steve\Desktop>dnvm use 1.0.0-beta4 -arch x64 -r coreclr -p

Adding C:\Users\Steve\.dnx\runtimes\dnx-coreclr-win-x64.1.0.0-beta4\bin to process PATH
Adding C:\Users\Steve\.dnx\runtimes\dnx-coreclr-win-x64.1.0.0-beta4\bin to user PATH

[3] Generate an ASP.NET Web Application with Yeoman

If you haven’t already installed Node.js and npm on your workstation, then do so now.  There are pre-built installers for Windows, OS X, and Linux available on the Node.js website, although OS X and Linux users might prefer to go through a package manager such as Homebrew or Apt.

With Node.js and npm present, install Yeoman and the ASP.NET generator like this:

C:\Users\Steve\Desktop>npm install -g yo grunt-cli generator-aspnet bower

Start the Yeoman ASP.NET generator with “yo aspnet“, and use the arrow keys to select the “Web Application” project type.  You can choose whatever name you like, but I’m just sticking with the “WebApplication” default:

C:\Users\Steve\Desktop>yo aspnet

    |       |    .--------------------------.
    |--(o)--|    |      Welcome to the      |
   `---------´   |   marvellous ASP.NET 5   |
    ( _´U`_ )    |        generator!        |
    /___A___\    '--------------------------'
     |  ~  |
 ´   `  |° ´ Y `

? What type of application do you want to create?
  Empty Application
  Console Application
> Web Application
  Web API Application
  Nancy ASP.NET Application
  Class Library

You will see a slew of information about files being created, followed by a success message like this:

Your project is now created, you can use the following commands to get going
    dnu restore
    dnu build
    dnx . run for console projects
    dnx . kestrel or dnx . web for web projects

You now have a perfectly functional ASP.NET web application!  I must again note that right now, this process only works on Windows.  The Yeoman generator on my Macbook Pro produces a broken application… and the success message talks about the older “kpm” and “k” command names, rather than their current “dnu” and “dnx” counterparts.  We’re still in very early days here, hopefully these issues will be worked out before long.

[4] Run the Web Application

Change into the directory that was just created, and you can run the commands suggested above.  “dnu restore” and “dnu build” work together like Maven, importing the project’s dependencies and building it respectively.  With the “dnx . kestrel” command, we can now test out the application on port 5001 with the embedded Kestrel web server:



[5] Build a Completely Self-Contained Bundle

Let’s now publish our application into a self-contained deliverable, which can be deployed even on machines without .NET present.  The documentation is still a bit confusing on how to go about this.  However, the ASP.NET team is very friendly and active on StackOverflow, and so I was able to work it out through a question posted there:

dnu publish --runtime active

This takes all of the content and dependencies our application needs, and dumps them under the “bin\output” directory:


If you look under “approot\packages“, you’ll see a subdirectory named “dnx-coreclr-win-x64.1.0.0-beta4” (or similar, depending on your DNX version number).  This contains the entire DNX runtime needed by your application!

The root directory of this bundle contains a batch file for every command in your project’s “project.json” file (e.g. “kestrel.cmd“).  These batch file invoke the DNX runtime that is embedded within your bundle:

@"%~dp0approot\packages\dnx-coreclr-win-x64.1.0.0-beta4\bin\dnx.exe" --appbase "%~dp0approot\src\WebApplication" Microsoft.Framework.ApplicationHost kestrel %*

This entire “output” directory compresses to a ZIP file 39 megabytes in size.  That’s not much larger than a Spring Boot executable JAR, and that still requires a 150-500 megabyte Java environment on the target machine!

I should note that while this source code is cross-platform, you are bundling DNX native executables that are specific to a particular platform.  That’s not such a big deal, though.  Since the source code is cross-platform, we can simply re-publish it for other platforms, like compiling Golang or Rust applications.


These four articles covered quite a lot of ground, and there are a million different directions you could go from here to learn more.  There are major open source and cross-platform changes drawing attention and hype to .NET platform right now.  Hopefully this series provides a helpful overview, for an audience of curious Java developers and other non-Microsoft programmers looking in from the outside.


Steve Perkins

I am an Atlanta-based software developer, and the author of the book 'Hibernate Search by Example' from Packt Publishing. I currently work as an architect at BetterCloud, developing security and analytics SaaS products for companies using Google Apps and Microsoft Office 365.

  • Pingback: Understanding the New Cross-Platform .NET, part 3 (Visual Studio) - StevePerkins.com()

  • Kevin

    Really cool, informative series. It’s been a few years since I’ve actively done .net development and I’ve only casually kept an eye on it since. It looks like it’s come a long way. Thanks for the write up.

  • Have you worked with Docker? What are your thoughts on Windows and Docker integration? I’m trying to wrap my head around all of it…it is a pretty shift.

    • Oh my, that’s an entirely different article for another time… probably another whole series of articles!

      Actually, I am currently working with Docker on a project under development, and it has indeed been a huge shift in thinking. Still a lot to learn there before I’ll be ready to write about it. Putting individual applications inside of Docker containers is one thing, but where it gets interesting is with “orchestration”… or making the various containers interact with each other!

      As far as Microsoft, I can’t really tell if Windows integration with Docker is for real, or sort of a P.R. thing to buy some time until the Windows containerization story is ready. At the end of the day, Docker **is** Linux. It’s really little more than taking multiple Linux userspace environments, and having them all share the same Linux kernel. But it’s Linux, Linux, Linux… all the way down.

      The Windows integration story right now basically amounts to running Linux in a VM on your Windows box. That works, but it’s still an extra layer that has little to no reason for being there. If you’re packaging all of this stuff up into Linux-based containers, then well… you might as well just be deploying them on straight Linux!

      The impression I got from a recent episode of “.NET Rocks” (a great podcast) is that Microsoft is working on a Windows-based equivalent to Docker… letting multiple Windows-based containers share a common Windows kernel. That would seem to make a lot more sense, if you want to use Windows rather than Linux as your server OS. But we’ll have to see what happens, and the same concepts from Docker should carry over either way.

  • Elvis Rocha

    Great articles!! Thanks for simplifying the .NET world for java devs.

  • Steve Perkins; I’ve really enjoyed these articles. Very helpful to understand ASP.NET vNext & DNX. Thanks for the info.

  • Girijesh Kaushik

    Very nicely written series. Thanks.