ASP.NET Core is the open-source, cross-platform evolution of Microsoft’s ASP.NET web framework. It can run on Windows, Mac, and Linux, and provides a powerful platform for building MVC-style web applications and REST APIs.

Whether you’re an experienced .NET developer looking to dive into ASP.NET Core, or new to the entire .NET ecosystem, this tutorial is designed to give you everything you need to get started!

Your first step is to install the .NET Core SDK on your machine. The download page includes packages for Windows, Mac, and Linux. From there, the steps required to scaffold a new ASP.NET Core project depend on whether or not you choose to use Visual Studio. Don’t worry, I’ll walk you through the setup process both ways!

Using Visual Studio

Visual Studio
If you’re on Windows, Visual Studio is a rich development experience designed for .NET developers. The free Community Edition works just fine with ASP.NET Core! Regardless of the edition you use, ensure it’s up to date with at least the 2015 Update 3 installed.

To create a new project, choose File > New > Project and pick the .NET Core > ASP.NET Core Web Application (.NET Core) template. Then, pick either the Web API or Web Application templates. If you want to include boilerplate authentication support, click Change Authentication and pick an option. Or, leave it on No Authentication if you’ll be adding security yourself (with Stormpath, we hope!). Finally, click OK to scaffold a new project.

Setting up ASP.NET Core with Visual Studio

The template can run on top of IIS Express, or utilize the Kestrel HTTP server. By clicking the arrow to the right of the Start button in the toolbar, you can choose whether to run using IIS Express or Kestrel.

Setting up ASP.NET Core

Press F5 to compile and run the project, and then point your browser at http://localhost:5000 (or your IIS Express port). When you see the default welcome page you’ll know you’re all set up!

Without Visual Studio

Unlike the ASP.NET of the past, you don’t need Visual Studio to build and debug ASP.NET Core applications! If you’re on Mac or Linux, or simply want a lightweight development option, you can use Visual Studio Code, Sublime, Atom, or your favorite text editor to write ASP.NET Core applications.

When you install the .NET Core SDK on your machine, the dotnet command line tool is added to your PATH. You should be able to run this on the command line:

To create a new project, you’ll need the Yeoman ASP.NET Generator. Once the generator is installed, use it to scaffold a new project:

Yeoman will display a menu of templates to choose from. Pick the Web Application or Web API Application template and type a name for your project.

Setting up ASP.NET Core

Then, navigate inside the new directory and use dotnet to restore the necessary packages and run your project:

Setting up ASP.NET Core

After the project compiles, the default web server (Kestrel) will start up. Try pointing your browser to https://localhost:5000. When you see the default welcome page, your application is running!


I suppose there could be a reason or two that you’re not yet using ASP.NET Core, but setup pain certainly isn’t one of them. Even on a Mac or Linux machine installation and setup are a breeze. Ready to deploy your first ASP.NET Core application, or interested in learning more about authentication and user management for .NET? Check out these resources:
Tutorial: Build an ASP.NET Core Application with User Authentication
Token Authentication in ASP.NET Core
Tutorial: Deploy an ASP.NET Core Application on Linux with Docker

If you have any questions, or just want to chat, reach out to me via email or on Twitter @nbarbettini!