ASP.NET Core MVC From Scratch

ASP.NET Core was recently released by Microsoft, and I am really excited about this new cross-platform web framework. As soon as it was released I had .NET Core running on my MacBook Pro and was developing console application as well as web applications using Visual Studio Code.

I find it best to learn a new technology by minimizing my use of automated tools in the beginning. During this honeymoon period I prefer manual use of the dotnet CLI, a minimal IDE like Visual Studio Code, and avoiding built-in templates and wizards. I prefer to learn the nitty gritty details, and only once I truly know what is happening under the covers, do I embrace the automation.

To keep things even more minimal, I am developing on macOS to really test out the cross-platform capabilities, and then I'll switch to Windows and full-blown Visual Studio for the experience on Windows.

ASP.NET Core with MVC and Razor

The goal here is to understand the minimal configuration and effort to get a simple ASP.NET Core Web Application up and running on macOS using MVC and the Razor View Engine. Certainly I can create ASP.NET Core Web Apps without MVC and Razor, but I'll save those configurations for another article. I want to display a very simple web page using MVC and Razor, which will provide a starting point for adding additional features.

dotnet CLI

All the magic happens first with the dotnet CLI. I need to create a .NET Core Application on my MacBook using the dotnet CLI and from there I will use Visual Studio Code to fill in the details. At a command prompt I start the process of creating a new directory for the application, creating a new application using the dotnet CLI, and then restoring all the nuget packages used by the app.

mkdir MinimalAspNetCoreMvc && CD $_
dotnet new
dotnet restore

This is all I need to get started. Now I just need to open the project in Visual Studio Code.

code .

About 10 seconds after Visual Studio Code has started I get a prompt to install the necessary assets to enable debugging. I choose "Yes."

Adding Dependencies to Project.json

Since I am developing an ASP.NET Core MVC Web Application, I know I need a couple of dependencies: Microsoft.AspNetCore.Mvc, and Microsoft.AspNetCore.Server.Kestrel. ASP.NET Core MVC is obvious since that is my goal, but I also need a server to serve my web pages on macOS so I need Kestrel as well. At a minimum I need to add these two dependencies to project.json:

"Microsoft.AspNetCore.Mvc": "1.0.0",
"Microsoft.AspNetCore.Server.Kestrel": "1.0.0"

I also need to set another build option for runtime compilation:

"preserveCompilationContext": true

Here is the minimal project.json for my ASP.NET Core MVC Web Application.

  "version": "1.0.0-*",
  "buildOptions": {
    "debugType": "portable",
    "emitEntryPoint": true,
    "preserveCompilationContext": true
  "dependencies": {},
  "frameworks": {
    "netcoreapp1.0": {
      "dependencies": {
        "Microsoft.NETCore.App": {
          "type": "platform",
          "version": "1.0.0"
        "Microsoft.AspNetCore.Mvc": "1.0.0",
        "Microsoft.AspNetCore.Server.Kestrel": "1.0.0"
      "imports": "dnxcore50"

Since I have added two new dependencies, I want to run dotnet restore to install these dependencies. I can do this from within Visual Studio Code via the Command Palette ( CMD-SHIFT-P ), within Visual Studio Code from a new terminal window ( CTRL-` ), or from the original terminal window I used to create the application. Either way, I run the following command to install the necessary nuget packages.

dotnet restore

Configuring the Console Application

This may sound weird since I am developing a web app, but all applications, including web applications, are console applications in .NET Core. I just need to create a new web host in the console application, tell it to use Kestrel to serve the files, and run it. My program.cs file is as follows.

using System.IO;
using Microsoft.AspNetCore.Hosting;

namespace ConsoleApplication {
    public class Program {
        public static void Main(string[] args) {
            var host = new WebHostBuilder()


This is all self-explanatory. Notice I am telling the host to UseStartup<Startup>(). This says additional configuration can be found in a separate class, called Startup.

Startup - Configure and Use ASP.NET Core MVC

In order to use MVC, I need to inject all its services into the ASP.NET Core dependency injection framework as well as add its middleware to the pipeline. This is a pretty deep topic so I recommend you read the details in the documentation. This is critical to get ASP.NET Core using MVC. This is being done in the Startup Class I referenced when building the host via UseStartup<Startup>().

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

public class Startup {
    public void ConfigureServices(IServiceCollection services) {

    public void Configure(IApplicationBuilder app) {

The services.AddMvc() statement injects the MVC services into the dependency injection framework, and the app.UseMvcWithDefaultRoute() statement adds MVC to the middleware pipeline. You may see this as just app.UseMvc(). I chose another extension method so I could use the built-in default routing in MVC.

Controllers and Views

Now that I have the configuration pieces out of the way, I can start developing MVC controllers and views. Just to make sure all is well, I am going to create a quick page that displays "Powered by ASP.NET Core." Using the default routing in ASP.NET Core MVC, I can simply create an Index Action on a HomeController, and this will be invoked as the homepage. I'll also create a default view ( Index.cshtml ) that it can serve in the Views > Home directory. This is just typical ASP.NET Core MVC at this point.

Here is my HomeController.cs file in the Controllers Directory.

using Microsoft.AspNetCore.Mvc;

public class HomeController : Controller {
    public IActionResult Index() {
        ViewBag.Message = "Powered by ASP.NET Core";
        return View();

Here is my Index.cshtml file in the Views > Home Directory.

<html lang="en-US">
    <meta charset="utf-8" />
    <title>ASP.NET Core Website</title>

The web application is now ready to run!

Run the ASP.NET Core MVC Application

Everything looks good and the web application is now ready for its debut. I could run this from within Visual Studio Code, but I prefer to do it at the command line. I could run the dotnet build command to build it, but I know the dotnet run command will invoke build anyway. Therefore, I issue dotnet run at the command line.

dotnet run

Project MinimalAspNetCoreMvc (.NETCoreApp,Version=v1.0) will be compiled because expected outputs are missing
Compiling MinimalAspNetCoreMvc for .NETCoreApp,Version=v1.0

Compilation succeeded.
    0 Warning(s)
    0 Error(s)

Time elapsed 00:00:01.7698360

Hosting environment: Production
Content root path: /Users/Sasquatch/Projects/Core/MinimalAspNetCoreMvc
Now listening on: http://localhost:5000
Application started. Press Ctrl+C to shut down.

This is promising. I open Safari and view the following page at localhost:5000.

ASP.NET Core MVC Web Application


This is a great start to learning ASP.NET Core MVC and the minimal configuration needed to display a page using the Razor View Engine. This is probably a good time to step back, however, and see what I can do without MVC and Razor. I'll write an article about that, too. If you enjoyed this article, I recommend ASP.NET Core Web API on macOS using Visual Studio Code.

Posted by David Hayden
Koder Dojo
David Hayden is a professional Microsoft web developer. He mentors and tutors computer science students in C, C++, Java, and Python. In addition to writing computer science and programming tutorials at Koder Dojo, he also writes tutorials on C#, ASP.NET Core, and Azure as well as tutorials on Orchard Core.