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

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

Programming
Microsoft .NET logo

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.  Then 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
CLRJVM
.NET implementation (i.e. Framework, Mono, or Core)JRE
.NET FrameworkOracle’s proprietary Java binaries
MonoOpenJDK
.NET CoreUpcoming Java 9, with “Project Jigsaw” modular redesign
DNXJDK
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:

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

usage: dnvm  []

commands:
    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:

aspnet-webapp-screenshot-3
aspnet-webapp-screenshot

[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:

aspnet-webapp-screenshot-2

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.

Conclusion

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.