Rick Strahl's Web Log

Wind, waves, code and everything in between...
ASP.NET • C# • HTML5 • JavaScript • AngularJs
Contact   •   Articles   •   Products   •   Support   •   Search
Ad-free experience sponsored by:
ASPOSE - the market leader of .NET and Java APIs for file formats – natively work with DOCX, XLSX, PPT, PDF, images and more

First Steps: Exploring .NET Core and ASP.NET Core

.NET Core and ASP.NET Core 1.0 are finally here, and in this post I'll show how to get started with these new tools using the command line tooling. This is not meant to be your typical getting started tutorial that jumps right into Visual Studio and creates a Web project from there. Rather, the purpose of this post is to demonstrate some of the core underpinnings of how .NET Core and ASP.NET Core projects are bootstrapped and using the command line tooling is actually the best way to demonstrate this.

I'll start at the beginning with 'HelloWorld' then add additional pieces and ASP.NET and demonstrate how to deploy and then run the application both on Windows and a Mac.

You can find the code for this simple walkthrough at:

If you're brand new to .NET Core and what it all means you might also enjoy reading the Overview post first:

Command Line Tooling

One of the nice things about the new command line tooling is that all .NET pieces - the runtimes, compiler and command line tooling - are installed through a single unified install. As I mentioned in my ASP.NET and .NET Core Overview post.

I’ll use Windows here to create this first application, but note that you can also do the same thing on a Mac or a Linux machine if the .NET SDK is installed. The steps other than installation are the same so you can follow along on a Mac or Linux.

Start by downloading the .NET SDK from http://dot.net. Click on the .NET Core link and follow the install instructions for your platform. To create a new project, you can follow the directions from that page.

The steps are:

  • Create a new folder
  • Change to the new folder
  • dotnet new to create a new project
  • dotnet restore to bring down NuGet packages required
  • dotnet run to actually run the application

As you can see in Figure above the output of this console application is dumped to the console. You’ve just created and run a .NET application in 3 small steps.

Start with dotnet new which creates a new project with a program.cs file that contains a public Main() function, just like you expect for a classic Console application. All .NET Core applications, including ASP.NET applications now are Console applications.

The first thing you need to do is dotnet restore which restores all the NuGet packages linked in the project. In an empty project like this one it doesn't actually do anything other than reference the .NET Standard Library installed on your machine.

Once you've restored you can do dotnet run which runs the default hello world program:

You can now open the program.cs file in that was generated and change the code. For example, change the Console.WriteLine() to add a date and time:

using System;

namespace ConsoleApplication
    public class Program
        public static void Main(string[] args)
            Console.WriteLine("Hello World. Time is: " +

Back at the command line just use dotnet run and you should see the updated message including the time displayed.

Hello World. Time is: 5:36 PM

Note that the code automatically was recompiled and executed with the change you made when you did dotnet run. There's no explicit compilation step - there is however an explicit dotnet build command you can use if you explicitly want to just build your project.

To recap. You:

  • installed .NET
  • ran three commands
  • and had a running .NET piece of code

While developers of languages like NodeJs have taken this for granted you can now much more easily create new project or small utilities using this same approach using .NET.

Where's my Executable?

One thing you might have noticed in the code above is that you are not executing an EXE file. Instead you run dotnet run in a folder that contains a project.json file which contains the instructions to bootstrap the application. This does mean that current applications have to run out of a dedicated folder and have to contain the files to build the project.

Code is compiled into an assembly on the fly (stored in the bin folder as a DLL) which is then loaded by the dotnet runtime loader that hosts the DLL when you do dotnet run. The build process does produce binaries in the bin folder, but there's no mainline exe. dotnet run options determine whether the project is compiled or uses the existing assemblies from the bin folder.

Building an Exe

When you dotnet build or dotnet run using the project json shown earlier, it produces a platform agnostic, portable set of assemblies that can execute on any platform that are loaded from dotnet.exe when you run dotnet run.

It is possible to build your application to an EXE by creating a platform specific build. A number of directives in project.json can be used to specify the output targets. dotnet publish then creates a renamed dotnet.exe that automatically launches the platform specific project. For more info please see .NET Core Application Deployment (thanks to Bertrand for the link).

In the future there's also been talk about the creation of native binaries with dynamic compilation, but for now only this pass through execution through dotnet.exe and a required folder are supported.

Command Line Bigotry?

So the command line tooling is interesting in that it makes it much easier to create, build and run .NET applications.

But it's not just that you can perform the build process from the command line, but the fact that it’s very easy to get started. Download a relatively small SDK, install it, scaffold a base project, then use any text editor (or full boat Visual Studio) to make a change to your code and run. Compare that with the process of how you get started with the full version .NET, which pretty much involves downloading Visual Studio or installing a slew of SDKs and figuring CSC command line syntax. Using dotnet.exe with a few simple commands is a lot more approachable, and more importantly you can be up and running with this code from download to running code in about 5 minutes.

This is a very good thing!

The command line tools are there to make getting started easier and to appease those that like to work on a lower level than the big monster that is Visual Studio.

But that isn’t to say that you’re going to have to build your application from the command line now - you can still use Visual Studio which then uses the command line tooling for creating the projects on your behalf.

In fact, if you install the Visual Studio tooling for ASP.NET Core you get Visual Studio integration like you would expect, so you can use the rich Visual Studio editor and your favorite tools and extensions to build your applications.

But behind the scenes, Visual Studio calls into these same command line tools to compile your project. This opens up the build process to tooling or your own build process management, because you have easy access to the same tools that Visual Studio uses to build your project.

Personally I'm not a big command line guy - I prefer visual tooling for most things, but I have to admit that with this new tooling I find myself at the command line more often. Because the tooling is easy to use with terse commands it can often be quicker to restart an app from the command line than the Visual Studio run cycle. So beware - you might end up changing your habits (again - probably a good thing).

Posted in ASP.NET Core  ASP.NET  

The Voices of Reason


June 29, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

Everything worked until I tried to convert it to a web app. I updated my project.json file as mentioned above. However this gave the error:

"The dependency "Microsoft.AspNetCore.Server.Kestrel >= 1.0.0 could not be resolved."

Do you know what I may have done wrong?

June 30, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

Great post as usual, thanks Rick! In "where's my exe", you missed that you can actually get an exe if you target a specific runtime. See https://docs.microsoft.com/en-us/dotnet/articles/core/deploying/index

Nicholas Petersen
June 30, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

That was excellent Rick, thank you.

Rick Strahl
June 30, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

@Lee - not sure why you would get that. Make sure you are online (the references are coming from NuGet after all) and that you have to the right target selected. Can you clone the project from Git to see if that works for you, and if it does compare what you find? Post back here if you find out what went wrong.

@Bertrand - thanks. Yup didn't know you could generate an Exe. I'll check it out and ammend the post later today.

Mike Gale
June 30, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

Thanks for sharing your explorations. I was initially dubious about this approach, but this article has changed my mind.

Have you explored changing a Kestrel site to a pure IIS site (without the proxying)?

Rick Strahl
June 30, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

@Mike - you can't run ASP.NET Core without Kestrel - Kestrel is THE web server that everything runs in. IIS is just a proxy front end as is something like ngnx on Linux. AFAIK there are no other hosts at the moment and I don't think you'd want another host really since Kestrel is highly optimized. You can embed Kestrel into other .NET Core apps so there should be very little need for something else.

Brad Falk
June 30, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

@Lee After converting it to a web app you have to do a dotnet restore, before the dotnet run. This will pull down the AspNetCore related dependencies.

This is a great article Rick, thanks for this.

Rick Strahl
June 30, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

@Brad - thanks for catching the missing `dotnet restore` calls whenever a library is added. I've added those into the post.

July 02, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

Finally I have managed to run ASP.NET MVC using .NET Core on linux. Great, easy to follow article.

July 04, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

hi Rick,

I always loved your article and found you opening the nuts n bolts of internal systems.

One thing which is still kind of magic to me is : how coreclr is designed to target multiple OS ? Does Jitter uses conditional compilation to produce native code at run time ( meaning if target platform is MAC OS then run some MSIL else run some other MSIL for windows platoform ) ? As I know full CLR makes use of Win32 APIs for resource allocations ( like threads ) - how does CoreCLR address all this cross platform.

Could you please help me understand this !!


Rick Strahl
July 04, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

@rahul - that's the way it's always worked with the JIT. In theory that was always possible and has been with Mono - you could run Windows compiled assemblies on Mac and Linux with Mono before - as long as you didn't stick Windows specific dependencies from the FCL into your code.

The runtime determines the execution environment that is platform specific, and the assembly code calls into the platform specific APIs that the runtime exposes for things like file access, network access and system resources like the environment etc.

With .NET Core you will eventually also be able to compile to native code by explicitly specifying your platform target which gets you a native binary. I think that works today with UWP executables (which is Windows only but you can get native, fully compiled binaries).

rahul agarwal
July 05, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

Thanks Rick !!! One more quick thing, CLR itself is COM component and is specific to Windows. In this sense, is CoreCLR different ?

Also for MONO, is different runtimes required for different platforms.


July 11, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

Saw this article mentioned on the ASP.NET community stand-up. Good stuff. I know understand how the .Use .Run work.

July 15, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

Hi Rick,
I am trying to run an asp.net core app on Linux and Windows but it throws up saying appsettings.json not found. I figured out that if i run the command like (in windows):
C:\Users\Dev> dotnet C:\MyProgramFolder\MyProgram.dll
it sets the ContentRootPath to C:\Users\Dev which is obviously not what I want.
The program.cs contains the usual .UseContentRoot(Directory.GetCurrentDirectory()). How do we handle this?

Rick Strahl
July 16, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

@Ammar - .NET Core Apps run out of the current folder that they are launched from, which is the same way .NET applications (and any Windows application for that matter) have always worked. If you want a different path and you want to control the path then you have to change path to that location. Path.SetPath() should work, along with looking at the executing assembly. .UseContentRoot() simply sets the path you provide it which in your code is the startup folder where you launched from.

July 16, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

@Rick - Thanks for the quick reply Rick. Indeed .net apps always run out of the current folder. Got a bit confused due to the problem that appsettings.json was not found. This project originally was created with RC1, migrated to to RC2 and then to RTM. I ran another project that was created fresh with RTM and it is worked fine. I compared all the configuration files and found everything same but still the first app did not work. I then opened the xproj file and replaced all "dnx" lines with "dotnet" ones copied for the new project and it all started working. Will dig more into it later.
Just mentioned it here so that someone else could save his/her time :)

Chris Harrington
July 19, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

Hi Rich,
I see this code in controller
return View("helloworld");
//return View("~/helloworld.cshtml");
but nothing in your article explaining that second commented-out call.
I wasn't able to get either one to generate output.

Could you also elaborate on : "ASP.NET Core MVC uses standard View discovery logic by default, so it’s looking in the /Views/Helloworld folder for a HelloworldMvc.cshtml view. " I'm assuming that you didn't demonstrate this in your code. But again, I couldn't get any of the views to render.

Rick Strahl
July 19, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

@Chris - the second commented call was meant to demonstrate that you can serve Razor pages from any location in your wwwroot application. So ~/helloworld.cshtml can sit in the /wwwroot folder of your project and get served. Note that this only works if the Content Root is set in program.cs (which is why I was originally experimenting with this code as it wasn't working withtout the content root set).

July 27, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

Really great article! This helped me understand the basics. I've also read the previous "ASP.NET and .NET Core Overview" post.
Like you I'm not a Command-Line fanatic, I'd rather stick to VS, but I like to know what's happening behind the scenes.
With classic .NET, I've always had a pretty good idea and feeling what was happening when I developed an application.

This article now helps me understand more what happens when I create a new (ASP).NET Core project in VS.

August 14, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

This is an awesome article.

While I rather dislike the design/layout/color of the website, I love your articles a lot.

They provide me in-depth information with a very good context, even if I have few background information of a topic. After reading your articles, I do _have_ good knowledge :-)

August 17, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

Great articles, that's the approach I was looking for...very very good stuff :)

Thanks Rick

September 01, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

I followed your examples and built several 'projects' using the following simple folder structure : example 01, example 02, etc... Note the space in the folder names.
Everything built fine until I got to the mvc views example.
Turns out the space in the folder name was the culprit. Everything builds fine when the folder contains no spaces, otherwise you get an error like 'error CS2001 source file [path]views.deps.json could not be found'
Anyone else having the same issue or is it just my computer?

Caleb Jenkins
September 02, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

Great write up Rick. Also, no need to "restore" to a mac, all of these steps can be followed along from a mac directly from scratch. So awesome.

September 05, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

Great article for beginners.
Thanks Rick!!

Erhan Kaluç
September 07, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core


Would you have any ideas about clustering an asp.net web application on linux systems for multi core machines ?
I wonder if we need to do anything special for clustering or not. I previously using clustering on my nodejs web applications.


September 23, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

Fantastic...after so many Hello World...this is the best, it explains how things work...!!!

Gives me confidence now..to move ...

September 27, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

Great Tutorial! Learned a lot from this.

Just a heads up, if you're trying to deploy or build on Linux the casing of the object matters for the view folder.

This snippet here -
                                public object HelloWorld()
                                                return new
                                                                message = "Hello World",
                                                                time = DateTime.Now

I had to rename the view folder to 'HelloWorld' mirroring the casing of the object in the git pull and in my application to get the view to render.


November 07, 2016

# re: First Steps: Exploring .NET Core and ASP.NET Core

I am coming from a pure javascript background using Node and found this tutorial helpful for learning about asp.net in general and how I can use Core on my Mac. Great article. I wish someone would write an article like this but "ported" to the Node user as I see this as MS's way of trying to lure those of use more used to Node than asp.net

January 05, 2017

# re: First Steps: Exploring .NET Core and ASP.NET Core

Fantastic, Rick!
As always, your post allows a developer to leap across the chasm of a new technology and hit the ground running. Thanks!


West Wind  © Rick Strahl, West Wind Technologies, 2005 - 2017