Getting to the CRUX of DNVM, DNU and DNX in ASP.NET 5

 

 

INDEX

 

1. Introduction

2. Installing the DNVM

3. Installing the CoreCLR runtime versions

3.1 DNVM Install

3.2 DNVM upgrade

4. Difference between DNVM Upgrade and DNVM Install

5. DNVM list

6. DNVM use

7. Where DNVM

8. Remove Runtime References from PATH Variables

9. Aliases to the rescue!!

10. Understanding the Basics of DNU & DNX

10.1 What is DNU ?

10.2 What is DNX ?

10.3 How does DNU work ?

10.4 What does project.json contain ?

11. DNU restore

12. DNX web

 

 

1. Introduction

 

ASP.NET 5 is a new open-source and cross-platform framework for building modern cloud-based Web applications using .NET. We built it from the ground up to provide an optimized development framework for apps that are either deployed to the cloud or run on-premises. It consists of modular components with minimal overhead, so you retain flexibility while constructing your solutions. You can develop and run your ASP.NET 5 applications cross-platform on Windows, Mac and Linux.

 

ASP.NET 5 brings with it a lot of command line tools for managing our .NET version selection, library packages, and execution environment outside of Visual Studio.

 

Using these command line utilities, we can develop rich develop cross-platform ASP.NET applications using a simple text editor (like notepad) and command line (either CMD or Powershell on Windows) without even opening Visual Studio.

 

These commands that have been introduced in ASP.NET 5 are DNVM, DNU and DNX. The scope of this blog post is to get a fair idea on the installing and configuring the CoreCLR runtime for your ASP.NET 5 website.

 

2. Installing the DNVM :

 

What is DNVM ?

This stands for Dot( . )Net Version Manager. This utility is the .NET SDK Manager, which provides a set of command line options to update / configure your .NET runtime (DNX).

 

If you have installed Visual Studio 2015 from the below location, then you already have the DNVM installed in your box.

 

https://www.visualstudio.com/downloads/download-visual-studio-vs

 

If you don’t want to install the VS 2015 OR If you would like to upgrade the already existing version of DNVM to the most recent version and continue developing your application then proceed further with this article.

 

 Firstly, we need to install the DNVM using the below command from an elevated CMD prompt:

 

 

 

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

 

 

 

 

Alternatively, you can also use the below PowerShell script to install the DNVM:

 

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

 

 

 

The above command downloads the DNVM utility from the github and places the 2 files dnvm.cmd and dnvm.ps1 under the user profile C:\users\****\.dnx\bin location.

 

 

 

So you will get the below directory structure:

 

 

 

Once you have successfully installed the DNVM, Open an elevated CMD prompt and run the command dnvmwithout arguments:

 

3.  Installing the CoreCLR runtime versions:

 

You can use the DNVM utility to install the required version of the CoreCLR runtime using the below command syntax.

 

Any arguments with DNVM is passed to the dnvm.ps1 file by dnvm.cmd.

 

 

 

3.1 DNVM install :

If you would like to install the latest version of a particular DNX implementation, we can use the

dnvm installcommand with suitable parameters.

By default, DNVM will assume the x86 architecture. For example, if we run the below command the DNVM will download and install the latest build available for the x86 architecture:

 

 

 

Syntax:

DNVM install -a <<Architecture>> -r coreclr <<version>>

 

For instance, if I need to download and install the x64 architecture based CoreCLR having the version 1.0.0-rc1-update1 the command would be as shown below:

 

Command:

DNVM install -a x64 -r coreclr 1.0.0-rc1-update1

 

The above listed commands download that particular runtime package from Nuget and install it in the user profiles runtimes folder. It also modifies the PATH environment variable accordingly.

 

C:\windows\system32>DNVM install -a x64 -r coreclr 1.0.0-rc1-update1 Downloading dnx-coreclr-win-x64.1.0.0-rc1-update1 from https://www.nuget.org/api/v2 Installing to C:\Users\****\.dnx\runtimes\dnx-coreclr-win-x64.1.0.0-rc1-update1 Adding C:\Users\****\.dnx\runtimes\dnx-coreclr-win-x64.1.0.0-rc1-update1\bin to process PATH Compiling native images for dnx-coreclr-win-x64.1.0.0-rc1-update1 to improve startup performance... Finished native image compilation.

 

 

I have use the x64 architecture in my sample, so my PATH Environment Variable would have the below entry:

 

 

3.2  DNVM upgrade:

 

Alternatively, you can also use the DNVM upgrade command, which would also install the runtime. However, this would download and install the most recently available runtime version:

 

Syntax:

DNVM upgrade -a <<Architecture>> -r coreclr

 

C:\windows\system32>dnvm upgrade -a x64 -r coreclr Determining latest version Downloading dnx-coreclr-win-x64.1.0.0-rc1-update1 from https://www.nuget.org/api/v2 Installing to C:\Users\****\.dnx\runtimes\dnx-coreclr-win-x64.1.0.0-rc1-update1 Adding C:\Users\****\.dnx\runtimes\dnx-coreclr-win-x64.1.0.0-rc1-update1\bin to process PATH Adding C:\Users\****\.dnx\runtimes\dnx-coreclr-win-x64.1.0.0-rc1-update1\bin to user PATH Compiling native images for dnx-coreclr-win-x64.1.0.0-rc1-update1 to improve startup performance... Finished native image compilation. Setting alias 'default' to 'dnx-coreclr-win-x64.1.0.0-rc1-update1'

 

 

4. Difference between DNVM Upgrade and DNVM Install :

 

DNVM upgrade command is different than the DNVM Install even though both the commands ultimately focus on installing the runtime.

DNVM Install finds the specified version, install it and makes it active in the current Command process by adding it to the process PATH variable.

Note that the selection is *ACTIVE* only for the duration of our terminal session (CMD prompt).

Once the current terminal session (CMD prompt) 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 pretty much the same thing, but also adds it to the User's PATH variable as the default active version, and updates the default alias.

 

(See the above highlighted section in BLUE which shows the output of the DNVM installand DNVM upgrade)

 

 

5.  DNVM list

 

 

If you need to know the available runtime versions available in your machine, you need to run the

below command:

 

Command:

 

dnvm list

 

 

The above screenshot indicates that you have both the architecture x64 and x86 available with the 1.0.0-rc1-update1 versions of the CoreCLR with the active one being the x86 version.

 

Since I had Visual Studio 2015 installed already in my box, there are DNX versions available for .NET Framework regular CLR and also .NET Core (the coreclr above) for both 32 and 64 bit architectures.

 

If you have don’t have the Visual Studio 2015 installed in your box then, Installing DNVM and the DNX will give you the below entry:

 

 

The output was pulled up from the below directory structure:

 

 

6.  DNVM use:

 

If you would like to change the runtime version and use a specific version you need to specify the ‘use’ switch with DNVM.

 

 

Syntax:

DNVM use -a <<Architecture>> -r Coreclr <<Version>>

 

 

 

This command will add the specified runtime version to the Process path as shown above.

 

 

So now if we list the available runtime versions you can see the active version is switched:

 

 

 

 

If we want this runtime version to be persisted throughout the terminal session, we could run the command just like we did previously, but we need to add the -p ( -persistent) flag, which will cause the selection to be added to our user path instead of the process path:

 

 

 

Now, our selection will be persisted 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 1.0.0-rc1-update1.

 

7.  Where DNVM

 

At any instant you would be able to find the location where the DNVM was placed by running the below command:

 

 

 

 

8. Remove Runtime References from PATH Variables

If you would like 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 the below command:

 

dnvm use none

 

 

If you would like to remove all runtime references we have set in our User PATH variable, we run the same above command but this time with the (-p) persistent switch:

 

dnvm use none -p 

 

9. Aliases to the rescue!!

 

At times, it can be difficult to remember the lengthy commands. Don’t worry, we have Aliases to the rescue.

 

DNVM provides a feature called “alias” which gives us the ability to assign aliases to the different installed runtime versions.

 

We can do this during dnvm install or dnvm upgrade using the -a ( -alias ) switch, or we can set aliases for existing installed versions using the alias command.

 

Example: I already have an alias, default, which in my case was set to x64 CoreClr 1.0.0-rc1-update1 when I ran dnvm upgrade in the previous section (see the output under section 3.2).

 

I can set an alias for this using the below command:

 

 

 dnvm alias core-64-rc1 1.0.0-rc1-update1 -r coreclr -a x64

 

 

 

Now I can refer to that particular runtime by its alias, as shown below:

 

 

dnvm use core-64-rc1

 

 

 

10. Understanding the Basics of DNU & DNX:

 

To explain the basics, I will be using the MVC6 sample application which I downloaded from the github site:

 

https://github.com/aspnet/Home/tree/dev/samples/1.0.0-rc1-update1/HelloMvc

I can place this content in any location of my File System and then I need to navigate to this location from the elevated CMD prompt and run the DNU restore command. Before we dive deep into what does this command do, we need to understand what does DNU mean.

 

10.1 What is DNU?

 

DNU stands for DNX Utility. This is similar to the ‘Library Package Manager’ in visual studio. This helps in reading all the dependencies of our respective project and downloads it.

 

10.2 What is DNX?

 

DNX stands for the Dot Net Execution Environment. This is a runtime which includes the code needed to bootstrap and run our applications for windows, MAC and LINUX.

 

10.3 How does DNU work?

 

DNU reads the project.json file which is present inside the ASP.NET5 application determines the runtime version to execute the application , identifies all the dependencies / references for the project and downloads them with the help of nugget.

 

10.4 What does project.json contain ?

 

Below are the list of few of the sections which are present within the Project.json file (Snippets placed below are from the project.json file of my sample MVC6 app):

 

 

 

Dependencies: This section lists all the references of the application with the name and version which is used by the runtime loader while the application is loaded.

 

"dependencies": {         "Microsoft.AspNet.Server.Kestrel": "1.0.0-rc1-final",         "Microsoft.AspNet.IISPlatformHandler": "1.0.0-rc1-final",         "Microsoft.AspNet.Diagnostics": "1.0.0-rc1-final",         "Microsoft.AspNet.Mvc": "6.0.0-rc1-final",         "Microsoft.Extensions.Logging.Console": "1.0.0-rc1-final"     },

 

 

Commands : The DNX.exe takes the name of the command as an argument. You can have your own custom command defined under this section.

 

 

In the below snippet, you can run the command DNX web ( explained under section 12) to either self-host the application or run it on Linux / IIS.

 

 

The DNX.exe thus launched will be listening on the port 5004. You can modify it under the commands section and use any available port.

 

 

"commands": {         "web": "Microsoft.AspNet.Server.Kestrel --server.urls https://*:5004"     },

 

 

Frameworks: This snippet will build for both Desktop (dnx451) or Core CLR (dnxcore50).

 

 

"frameworks": {          "dnx451": { },          "dnxcore50": { }     }

 

 

WebRoot: This property specifies the folder name where all the static files need to be placed. If this were in Visual Studio, the IIS site has to be pointed to this folder.

 

{      "webroot": "wwwroot" }

 

 

Sources: This section supports an array of lists which defines the set of files that should be included / excluded while compilation:

 

 

{   "exclude": [         "wwwroot"     ],     "packExclude": [         "**.kproj",         "**.user",         "**.vspscc"     ], }

 

 

11. DNU restore

 

 

DNU reads the nuget.config file available within the application content and downloads the dependencies specified with the project.json file and writes to the project.lock.json.

 

 

Project.lock.json now contains the set of packages that the runtime (coreclr) can use for compilation and execution.

 

 

The 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 – since 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. Note that while using CoreCLR, We download only those libraries we need for our application to run, and exclude everything else.

 

We can restore library packages by simply running dnu restore from within our project directory as shown below:

 

C:\inetpub\DNX_Demo\Home\samples\1.0.0-rc1-update1\HelloMvc>dnu restore Microsoft .NET Development Utility CoreClr-x64-1.0.0-rc1-16231     CACHE https://nuget.org/api/v2/   CACHE https://www.myget.org/F/aspnetrc1/api/v2/ Restoring packages for C:\inetpub\DNX_Demo\Home\samples\1.0.0-rc1-update1\HelloMvc\project.json Writing lock file C:\inetpub\DNX_Demo\Home\samples\1.0.0-rc1-update1\HelloMvc\project.lock.json Restore complete, 5719ms elapsed   NuGet Config files used:     C:\Users\****\AppData\Roaming\NuGet\nuget.config     C:\inetpub\DNX_Demo\Home\samples\1.0.0-rc1-update1\nuget.config     C:\inetpub\DNX_Demo\Home\samples\1.0.0-rc1-update1\HelloMvc\nuget.config   Feeds used:     https://nuget.org/api/v2/     https://www.myget.org/F/aspnetrc1/api/v2/

 

 

12. DNX web :

 

After we restored the packages and got the dependencies downloaded, we can now run the application.

 

 

In my example, the CoreCLR 1.0.0-rc1-update1 is set as the default. So now you need to first navigate to the location where you have saved your project and run the application.

 

 

To run the application, you need to use the command dnx web. This is the same setting which was pulled from the project.json file under the commands section.

 

C:\inetpub\DNX_Demo\Home\samples\1.0.0-rc1-update1\HelloMvc>dnx web Hosting environment: Production Now listening on: https://*:5004 Application started. Press Ctrl+C to shut down.

 

 

We can now access the application over https://localhost:5004 and the application comes up.

 

 

 

 Hope this helps !!