ASP.NET 5 introduces a new runtime model for the .NET framework which allows us to employ a "pay-as-you-go" approach, building composable applications using only those framework components our application needs, without relying upon a central, monolithic library repository present on the host machine.
This new model also provides us with command line tools for managing our .NET version selection, library packages, and execution environment outside of Visual Studio. It is now possible to develop cross-platform ASP.NET applications using a text editor and command line (either CMD or Powershell on Windows) without ever opening Visual Studio.
Image by César Astudillo | Some Rights Reserved
Understanding the relationship between the .NET Version Manager (DNVM), the .NET Execution Environment (DNX) and .NET Development Utilities (DNU) is fundamental to developing with ASP.NET 5. In this post we will look at installing and using DNVM, DNX, and DNU on to work with ASP.NET from the command line.
DNVM is a version manager tool for the command line. As its name implies, DNVM provides the functionality needed to configure your .NET runtime. We can use DNVM to specify which version of the .NET Execution Environment to use at the process, user, or machine level.
What is this DNX, anyway? From the ASP.NET Documentation site:
The .NET Execution Environment (DNX) is a software development kit (SDK) and runtime environment that has everything you need to build and run .NET applications for Windows, Mac and Linux. It provides a host process, CLR hosting logic and managed entry point discovery. DNX was built for running cross-platform ASP.NET Web applications, but it can run other types of .NET applications, too, such as cross-platform console apps.
Broadly speaking, different DNX runtime versions are available which reflect which .NET framework version you want to use in your application. At a basic level, there are different versions for:
- .NET Framework - The familiar .NET framework we all know and love.
- .NET Core - A subset of the .NET Framework which includes a modular runtime and library implementation and is managed via Nuget. .NET Core is cross-platform, open source, and includes the Core libraries in CoreFX, and a Core runtime in CoreCLR.
- Mono - Using Mono, we can create ASP.NET application which compile and run on OSX and Linux machines.
We can use the .NET Version Manager to select which DNX version we want to use with our application.
DNU is a command-line tool which provides a variety of utility functions to assist with development in ASP.NET. Most commonly, we will use DNU to install and manage library packages in our application, and/or to package and publish our own application.
DNU uses Nuget behind the scenes for package management and deployment.
If you have installed Visual Studio 2015 (currently available as a Release Candidate HERE), you already have the .NET Version Manager installed.
UPDATE: According to the ASP.NET team (thanks Glenn!) DNX/DNVM isn't actually installed until you run File -> New after VS 2015 is installed, so if you have VS 2015 installed but have not cracked open a new file yet, you won't have it on your machine yet.
If you want to upgrade to the most recent version of DNVM, or if you want to work with ASP.NET, but don't want to install Visual Studio, you can download the DNVM script as follows from either the Windows Command prompt (CMD) or using Powershell:
Install or Upgrade DNVM Using CMD:
@powershell -NoProfile -ExecutionPolicy unrestricted -Command "&{$Branch='dev';iex ((new-object net.webclient).DownloadString('https://raw.githubusercontent.com/aspnet/Home/dev/dnvminstall.ps1'))}"
Install or Upgrade DNVM Using Powershell:
&{$Branch='dev';iex ((new-object net.webclient).DownloadString('https://raw.githubusercontent.com/aspnet/Home/dev/dnvminstall.ps1'))}
Once we have DNVM on our machine, we should be able to fire up the Windows command prompt, and get started.
At the command line (or Powershell prompt) run the following to see that DNVM is, in fact, installed on your machine:
Run DNVM without Arguments:
> dnvm
If all has gone well to this point, you should see the following (we're going to stick with CMD for this post, to keep things simple):
Console Output from Running DNVM without Arguments:
Now that we have DNVM installed and running, let's see which DNX versions we have available, and how to install DNX versions if we need.
To examine the runtime options available to us, we can run the following command from the Console:
List Available DNX Runtimes Using DNVM List:
> dnvm list
I had previously installed Visual Studio 2015 on my machine, which also installed a few DNX versions, so when I runt he above I see the following output:
Console Output from DNVM List:
Because I had installed Visual Studio 2015 already, there are DNX versions available for .NET Framework (the beta4 clr in the image above) and also .NET Core (the coreclr above) for both 32 and 64 bit architectures.
If you have NOT installed Visual Studio 2015, your list is very likely empty. Installing DNVM does not, in and of itself, install any DNX versions on your machine. No worries, we'll take care of that next.
If you just installed DNVM fresh, or if you want to get the latest version of a particular DNX implementation, we can use the the dnvm install command with some appropriate arguments:
By default, DNVM will work with the basic .NET framework, and assume the x86 architecture. For example, if we do the following:
DNVM Install Latest:
> dnvm install latest
DNVM will download and install the latest stable version of the regular .NET framework for the x86 architecture. If we run dnvm list again, we see the following:
Installed DNX Runtimes after Running DNVM Install Latest:
If we want to specify a different runtime (say, the CoreCLR instead of the .NET Framework, and/or specify the x64 version, we need to add the -r ( -runtime ) and/or -arch ( -architecture ) flags, and values:
DNVM Install Latest for Specific Runtime/Architecture:
> dnvm install latest -r coreclr -arch x64
Once the above is finished running, we have now added the latest version of the full .NET Framework for the x86 architecture, and CoreCLR for the x64 architecture to our available runtimes list:
Installed DNX Runtimes:
DNVM also has an upgrade command, which behaves just a little differently than Install.
DNVM Install fetches the specified version, and makes it active in the current Command process by adding it to the process PATH variable. The selection is "Active" is only for the duration of our terminal session. Once the current terminal session is closed, the active selection will revert to none, or whatever had been previously persisted in our User PATH variable as the default.
DNVM Upgrade does essentially the same thing, but also adds it to the User's PATH variable as the default active version, and updates the default alias. For example, if we used dnvm upgrade to install the latest 64 bit version of the .NET framework clr:
Upgrade .NET Framework CLR to Latest Version Using DNVM Upgrade:
> dnvm upgrade -r clr -arch x64
After running the above, our Console output tells us that the latest version of dnx-clr-win-x64 has been added not only to the current process PATH, but also to our User PATH. In addition, the "default" alias has been updated to point to the just-installed version:
Console Output from DNVM Upgrade:
Note that dnvm upgrade pulls down the latest stable release from Nuget. If you want to work on the bleeding edge with the latest unstable (development) release, you can use:
Upgrading to Latest Unstable (development) Runtime Releases:
> dnvm upgrade -u
In the above, you can specify runtime/architecture as previously using the -r and -arch flags.
5/17/2015 - NOTE: If you installed Visual Studio 2015, the system environment PATH variable likely points to C:\Program Files\Microsoft DNX\Dnvm\. As of this writing, the Visual Studio version of DNVM does not recognize the -u (-unstable ) flags. Even if you installed DNVM using the shell scripts at the beginning of this article, the Visual Studio variable will be found first. In order to use the -u flag, you will need to either change the order in which the PATH variables occur, or remove the Visual Studio PATH and add DNVM using one of the scripts above.
Notice in the previous section the asterisk that appears in the "Active" column of the console output once we started installing new DNX runtime versions. When we use dnvm Install, DNVM makes the just-installed version the default active version for the current process (in other words, for the current terminal session only).
As noted previously, when we run dnvm upgrade, DNVM makes the just-installed version the default active version not only for the current process, but also at the User level.
We can switch to a different DNX runtime by using the dnvm use command. By default, dnvm use changes the active selection for the current Command process. For example, given the current active runtime in the console output from the previous section (1.0.0-beta4-11566 clr x64), we could decide we want to switch to the latest 64 bit coreclr version for our current terminal session instead:
Select or Switch to a Different Runtime for the Current Process:
> dnvm use 1.0.0-beta4-11566 -r coreclr -arch x64
If we run the above command, and then run dnvm list again, we see our active version has changed:
New Active DNX Runtime Selected for Current Process:
If we look closely at the console output above though, we see that the new version was added to the process PATH, meaning, the selection will persist for the current Console process only. If we close the console window, and open another, the default set in our User PATH will be selected again.
If we want to set our user default, we could run the command just like we did previously, but instead we can add the -p ( -persistent) flag, which will cause the selection to be added to our user path instead of the process path:
Select or Switch to a New DNX Runtime Default for User PATH:
> dnvm use 1.0.0-beta4-11566 -r coreclr -arch x64 -p
Now, our selection will persist as the default between Command sessions. We can still select a different version per process just like we did previously, but until we make additional changes, the default active DNX runtime in a Command session will be the beta 4 CoreCLR from build 11566.
If we want to remove all runtime references from the process path (in other words, return to a state where no runtime is set as "Active" we can run:
Remove DNX Runtime References from Process PATH Variable:
> dnvm use none
If we want to remove any defaults we have set in our User PATH variable, we can add the -p flag:
Remove DNX Runtime References from User PATH Variable:
> dnvm use none -p
If you have been working through the examples so far, you may have noticed how painful it can be typing out the full, semantic version names each time you want to refer to a runtime version. DNVM affords us the ability to assign aliases to the different installed versions. We can do this during install or upgrade using the -a ( -alias ) flag, or we can set aliases for existing installed versions using the alias command.
For example, we already have an alias, default, which in my case was set up when I installed Visual Studio. It was originally assigned to the regular x86 .NET framework CLR, and then was re-assigned when we ran dnvm upgrade in the previous section. As of now, the alias default on my machine points to the latest (build 11566) x64 bit version of the .NET CLR.
I can set an alias for the latest x64 version of CoreCLR like so:
Assign an Alias to a DNX Runtime:
> dnvm alias core-64-latest 1.0.0-beta4-11566 -r coreclr -arch x64
Having done that, I can now refer to that particular runtime by its alias, for example:
Select or Switch to a new DNX Runtime Using an Alias:
> dnvm use core-64-latest
5/17/2015 - NOTE: There is currently a bug (see issue #175 / PR #248 at the DNVM Repo on Github) in which referring to a CoreClr runtime by alias does not work. As of this writing, the PR has not yet been merged, but things are supposed to work as described here. Until the issue is resolved, it is still necessary to refer to any CoreClr runtime by its full version name…
We can re-assign a previously set alias by simply using the dnvm alias command, and assigning the alias to a different DNX Runtime.
To get a feel for how DNVM, DNU, and DNX work together, we'll put together a very basic example project, using only the Windows Command Prompt and a text editor (for this post, I'm going to use Sublime Text 3, but we could just as easily use Visual Studio Code, or Notepad).
First, let's create a project directory, and then open the folder in Sublime Text:
Create a Project Directory and Navigate into the Directory using CMD:
C:\Users\John> mkdir dnx_demo
C:\Users\John> cd dnx_demo
Then, open the directory folder in Sublime text. First, we'll add a project.json file:
Add project.json File:
{
"version": "1.0.0-*",
"description": "Silly demo project",
"commands": {
"runme": "dnx_demo"
},
"frameworks": {
"dnx451": { },
"dnxcore50": {
"dependencies": {
"System.Console": "4.0.0-beta-22816",
"Microsoft.CSharp": "4.0.0-beta-22816"
}
}
}
}
In the above, note we have defined a command, "runme" which refers to the project name. We can invoke this command from the Command Line using dnx to run our project. Also note, we have specified both the traditional .NET Framework (dnx451) as well as the .NET Core (dnxcore50) as compilation targets, so our application wioll be cross-compiled for both DNX runtimes and frameworks.
Next, add a file named Program.cs and paste in the following code:
The Program.cs File:
using System;
namespace dnx_demo
{
public class Program
{
public void Main(string[] args)
{
Console.WriteLine("No Visual Studio Here!!");
Console.Read();
}
}
}
By simply adding these two files, we have (almost) everything we need to run a very basic, but complete, .NET Console application. Save the two files above, and return to the Command prompt.
Our project.json file specifies the target frameworks and dependencies our project requires. Note that for this project, there are no packages to be pulled down when we run against the standard .NET framework 4.5.1 - the required references are already present in the .NET framework itself.
We will need to restore packages before we can run against the .NET Core framework and CoreCLR. Remember, .NET Core is all about "pay as you go." In other words, We pull in only those libraries we need for our application to run, and leave out everything else.
We can restore library packages by simply running dnu restore from within our project directory:
Use DNU Restore to Restore Library Package Dependencies:
C:\Users\John\dnx_demo> dnu restore
With our package dependencies restored, we can run our application using DNX. We can now run the application, after we select which DNX runtime we want to use.
In my case, we set the default active runtime to the latest .NET Core CLR / x64 in a previous example, so we can run the application straight away from within our project directory:
Run the Example Application Using DNX:
C:\Users\John\dnx_demo> dnx . runme
Take a close look there. Since I am already in the project directory, I can simply type dnx, and use a period to indicate the current directory. DNX will parse the command, runme, we set up in our project.json file, and use that to run the project.
We could also simply reference the project by name:
Run the Example by Referencing the Project Directory Name:
C:\Users\John\dnx_demo> dnx . dnx_demo
Or, as long as we are in the project directory, we could keep it REAL SIMPLE and just use dnx . run
Run the Example Using dnx . run:
C:\Users\John\dnx_demo> dnx . run
Now, let's switch runtimes from .NET Core to the traditional .NET Framework. Recall, we had previously used dnvm upgrade to install the latest x64 binaries for the .NET framework, and when we did that, our default alias was assigned to that runtime:
Switch to the .NET Framework Runtime Using DNVM Use:
C:\Users\John\dnx_demo> dnvm use default
We can check to make sure we are now targeting the .NET CLR instead of CoreCLR, and then run our application again:
Running the Example Using the .NET Framework and Standard CLR:
So far, we've examined the basics of using the .NET Version Manager, the .NET Development Utility (DNU), and the .NET Execution Environment in order to get a basic application up and running in the new ASP.NET environment.
In our simple example above, we compiled and executed our project in memory. There is no generation of binaries as part of the dnx run process. DNX, and DNU offer a wealth of additional features, such outputting binaries as a part of the build process (dnu build), creating Nuget packages (dnu pack) and other useful commands.
DNU, DNX, and DNVM are currently in active development, and things are changing daily. Keep your eye on the ASP.NET 5 repo, and watch for updates here and elsewhere.
We will explore more in upcoming posts
John on GoogleCodeProject
