I've been looking into ASP.NET Core on and off for a while now and I thought it a good time to document what I've learned. With that in mind I'm going to create a series of posts covering ASP.NET Core starting with the fundamentals and moving towards more advanced concepts.

For reference, all code created during these posts can be found in a Github repo.

ASP.Net Core - Command line Tools

While we can install .NET Core with Visual Studio, you can also install all you need and then create and run a C# project without even touching VS. This is done using the .NET Core command line tools, specifically the .Net Version Manager (DNVM), the .Net Execution Environment (DNX) and the .NET Execution Environment Utilities (DNU).

.Net Version Manager (DNVM)

According to the readme on the ASPNet Core DNVM Github repo, DNVM is:

a set of command line utilities to update and configure which .NET Runtime to use

The available runtimes are:

  • .Net Framework (CLR) - This is the full .NET Framework, with all components of the framework installed and ready for use.

  • .Net Core (CoreCLR) - This is a modular runtime that includes a subset of the .NET framework. This is supposed on Windows, Mac and Linux.

DNVM has the following commands.

List

Using the command dnvm list shows the current runtime options available on your machine. For example:

Active Version           Runtime Architecture OperatingSystem Alias  
------ -------           ------- ------------ --------------- -----
       1.0.0-rc1-update1 clr     x64          win
       1.0.0-rc1-update1 clr     x86          win
       1.0.0-rc1-update1 coreclr x64          win
       1.0.0-rc1-update1 coreclr x86          win
  *    1.0.0-rc1-update2 clr     x64          win             default
       1.0.0-rc1-update2 clr     x86          win
       1.0.0-rc1-update2 coreclr x64          win
       1.0.0-rc1-update2 coreclr x86          win

Here you can see the runtimes available on my machine. You can also see which I have active and which is the default alias.

Install

We use the dnvm install command to install new versions of the runtime. For example:

dnvm install latest  

This command installs the latest version of the CLR runtime for the x86 architecture. If we wanted to specify which runtime and architecture we could run the following command.

dnvm install latest -r clr -arch x64  

This command installs the latest version of the CLR runtime for the x64 architecture. If we wanted to use the CoreCLR runtime for a 32-bit architecture we would specify as follows:

dnvm install latest -r coreclr -arch x86  

The install command also adds the newly fetched version to the process PATH variable. This means that the newly fetched version will be marked as active for the terminal session. So, if you close the terminal and open a new one the active runtime will have reverted to the default (or to none if a default doesn't exist).

Upgrade

We can use this command to install a new version of a runtime or upgrade and existing version.

dnvm upgrade -r clr -arch x86  

This installs the latest 32-bit version of the .NET Framework. If we wanted to reinstall the latest 32-bit version of the .Net framework (providing it's already installed) we would use the following command:

dnvm upgrade -r clr -arch x86 -f  

The upgrade command is like the install command with one exception. install adds the newly fetched version of the runtime to the users PATH variable. Meaning it will persist between terminal sessions. So, if you close the terminal and open a new on the active runtime will stay the same.

Use

The use command allows us to switch runtimes for the current process or user. As with the upgrade command changes for the current process live as long as the terminal session. Conversely, changes for the user are made in the users PATH and so persist after the terminal session ends.

So if we wanted to switch to using the update2 clr runtime, we would use the following command:

dnvm use 1.0.0-rc1-update2 -r clr -arch x64  

This command switches to the selected runtime for the current process. But if we want to switch runtime for the user, we add the -p parameter. Which means that the change will be persisted between terminal sessions.

dnvm use 1.0.0-rc1-update2 -r clr -arch x64 -p  

Now if we wanted to remove the runtime selection for the current process we would use:

dnvm use none  

But to remove the runtime selection for the current user, we add the -p parameter (as below):

dnvm use none -p  

Alias

We can also alias runtimes to reduce typing and speed up use of commands.

dnvm alias  

This command lists the current aliases that you have set-up. For example, my output is as follows:

Alias   Name                              Orphan  
-----   ----                              ------
default dnx-clr-win-x64.1.0.0-rc1-update2  False  

The value in the Orphan column indicates whether a runtime has been removed, but the alias still exists and hence has been "orphaned".

So to create an alias we run the following command:

dnvm alias RC1U2CLR64 1.0.0-rc1-update2 -r clr -arch x64  

Now if we wanted to switch to the runtime using the alias we would run this command.

dnvm use RC1U2CLR64  

.NET Execution Environment (DNX)

According to the ASP.Net Docs DNX is:

...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.

DNX provides a cross-platform .NET development environment. Using DNX you can develop on one platform and deploy to another providing you have the relevant DNX installed on both platforms. As you can imagine that significantly simplifies the work needed to develop cross-platform applications because DNX takes care of hosting the CLR, handling dependencies and bootstrapping your application. Also, using the new project.json file makes it easy to define your project and it's dependencies, so that the project can be published and these dependencies can be simply resolved.

DNX commands are configured in your project.json file, and can be run from the command line. For example, the following kestrel command checks the Microsoft.AspNet.Hosting assembly for an entry point and specifies the required server and url parameters before starting a web server to host the application:

"commands": {
    "kestrel": "Microsoft.AspNet.Hosting --config hosting.ini",
  },

.NET Execution Environment Utility (DNU)

The DNU tool is used to manage the dependencies and packages in a project. As the DNU command is located in the DNX folder each DNU instance is linked to a specific runtime execution environment. So looking in my user profile folder (%UserProfile%/.dnx/runtimes) I can see all the runtimes installed. If I look in a runtime folder I see the dnu.cmd command file.

The DNU commands are as follows (taken from dnu command output):

  • build - Produce assemblies for the project in given directory.
  • clear-http-cache - Clears the package cache.
  • commands - Commands related to managing application commands (install, uninstall).
  • feeds - Commands related to managing package feeds currently in use.
  • install - Install the given dependency.
  • list - Print the dependencies of a given project.
  • pack - Build NuGet packages for the project in given directory.
  • packages - Commands related to managing local and remote packages folders.
  • publish - Publish application for deployment.
  • restore - Restore packages.
  • wrap - Wrap a csproj/assembly into a project.json.

Building a Sample Project

Now let's work through the steps required to build a sample .NET Core project from the command line. Please note, I'm creating a .Net Core and not ASP.Net Core project. I'm doing this because I want to create a very basic application for this sample and I also want to dive into an ASP.NET Core project in the next post.

Step 1: Create Sample Files

To begin with create a folder and add the following project.json and Program.cs files.

project.json

{
  "version": "1.0.0-*",
  "description": "Sample Demo Project - Built without visual studio!",
  "commands": {},
  "frameworks": {
    "dnx451": { },
    "dnxcore50": {
      "dependencies": {
        "System.Console": "4.0.0-0~",
        "Microsoft.CSharp": "4.0.0-0~"
      }
    }
  }
}

Program.cs

using static System.Console;

namespace DNX.Demo  
{
    public class Program
    {
        public void Main(string[] args)
        {
            WriteLine("Application Running");
            Read();        
        }
    }
}

Step 2: Restore Dependencies

Now open a command window and navigate to the sample project folder. Then use the dnu restore command to pull the package dependencies. This step pulls the required dependencies to your %UserProfile%/.dnx/packages folder.

Step 3: Run the Application

Finally run the dnx run command. This command should generate the following output, which is the Console.Writeline output from the Program.Main method:

c:\Code\Test1>dnx run  
Application Running  

So there we have a brief overview of the command line tools available with ASP.Net Core and how to create a very basic console application from the command line without using Visual Studio!

Hope that was helpful for someone...