Creating a new ASP.NET project from scratch in Mac? You are not alone. In this post you’ll find a step-by-step guide to create and run your first ASP.NET 5 website in Mac. Is easy!

**OBSOLETE. WARNING: January 28th, 2016, **DNX’s was uptaded, announcing the  retirement of DNX in favor of “dotnet-cli”. Steps shown here where tested with ASP.NET Core RC1. It is no warrantied that it will work in newer versions.

DNX (retired)

The DNX is being retired in favor of the new dotnet CLI command line tools. See:

As a result, we’re not accepting anymore changes to this project. Please file any new issues on


Before get your hands on code, there are some tools you’ll need.

Installing Visual Studio Code

With all dependencies in place, its time to install Visual Studio in your Mac. Is as easy as:

  1. Download Visual Studio code (
  2. Open your “Applications” folder in Mac.
  3. Drag and drop from “Downloads” to “Applications”


Create a new project: File > New… WTF?

The first time you open Visual Studio Code, your Windows developer instinct heads you to File… (New file, New Window, Open…). Oh, wait, no “New” options?!

Yes sir… things outside works in a different way. With VSCode you can only open a physical folder with an existing project.


The recommended way to create ASP.NET projects for VSCode is to use Yeoman and ASP.NET Generators, previously installed (see prerequisites list). Go to Terminal and type “yo aspnet –grunt”:

Sergios-MacBook-Pro:WebApplicationBasic Sergio$ yo aspnet --grunt ----- | | .--------------------------. |--(o)--| | Welcome to the | ---------´ | marvellous ASP.NET 5 | ( _´U_ ) | generator! | /A\ '--------------------------' | ~ | '..'_ ´ |° ´ Y ? What type of application do you want to create? (Use arrow keys) Empty Application Console Application Web Application ❯ Web Application Basic [without Membership and Authorization] Web API Application Nancy ASP.NET Application Class Library Unit test project

Yeoman uses Gulp by default. Like Grunt instead? include the –grunt option while invoking yo

Yeoman will ask you the new project Name. So type e.g. “WebApplicationBasic”. A new ASP.NET project will be created. It can be opened with VSCode:

File > Open…vscode-file-menu

And locate the Yeoman generated folder. Important: We should select the entire folder. It is like the old “.csproj” Visual Studio file.

No. there is no .sln. Neither .csproj.
So, important: Choose the entire folder!


And now VSCode is ready to edit:


Project.json: The new CSPROJ

The CSPROJ file we knew in Visual Studio has been replaced by a combination of folder content + Project.json file. The latter is part of the DNX specification, containing metadata, containing metadata, compilation information, dependencies… everything related to the project, in JSON format:

{ "version": "1.0.0-*", "compilationOptions": { "emitEntryPoint": true }, "tooling": { "defaultNamespace": "WebApplicationBasic" }, "dependencies": { "Microsoft.AspNet.Diagnostics": "1.0.0-rc1-final", "Microsoft.AspNet.IISPlatformHandler": "1.0.0-rc1-final", "Microsoft.AspNet.Mvc": "6.0.0-rc1-final", "Microsoft.AspNet.Mvc.TagHelpers": "6.0.0-rc1-final", "Microsoft.AspNet.Server.Kestrel": "1.0.0-rc1-final", "Microsoft.AspNet.StaticFiles": "1.0.0-rc1-final", "Microsoft.AspNet.Tooling.Razor": "1.0.0-rc1-final", "Microsoft.Extensions.Configuration.FileProviderExtensions" : "1.0.0-rc1-final", "Microsoft.Extensions.Configuration.Json": "1.0.0-rc1-final", "Microsoft.Extensions.Logging": "1.0.0-rc1-final", "Microsoft.Extensions.Logging.Console": "1.0.0-rc1-final", "Microsoft.Extensions.Logging.Debug": "1.0.0-rc1-final" }, "commands": { "web": "Microsoft.AspNet.Server.Kestrel" }, "frameworks": { "dnx451": {}, "dnxcore50": {} }, "exclude": [ "wwwroot", "node_modules", "bower_components" ], "publishExclude": [ "node_modules", "bower_components", ".xproj", ".user", "**.vspscc" ], "scripts": { "prepublish": [ "npm install", "bower install", "grunt default" ] } }

It includes a command, “web” capable of launching a website using the Kestrel server (the “IIS” server equivalente outside the Windows world).

Launching the project

In VSCode, press F1 (Fn + F1) to show de actions menu. Write “dnx” to see dot net runtime options:


First of all, we need to restore package dependencies as we would do (well Nuget would) . Click on “dnx: Restore Packages”. In the second option. click “dnu restore”


A new Terminal window will be opened, executing the concrete command we need to perform to restore the packages:

cd '/Users/Sergio/Projects/WebApplicationBasic' ; /Users/Sergio/.dnx/runtimes/dnx-mono.1.0.0-rc1-final/bin/dnu restore find: /usr/local/lib/dnx/runtimes: No such file or directory Sergios-MacBook-Pro:~ Sergio$ cd '/Users/Sergio/Projects/WebApplicationBasic' ; /Users/Sergio/.dnx/runtimes/dnx-mono.1.0.0-rc1-final/bin/dnu restore Microsoft .NET Development Utility Mono-x64-1.0.0-rc1-16202 CACHE Restoring packages for /Users/Sergio/Projects/WebApplicationBasic/project.json Writing lock file /Users/Sergio/Projects/WebApplicationBasic/project.lock.json Restore complete, 9785ms elapsed NuGet Config files used: /Users/Sergio/.config/NuGet/nuget.config Feeds used:

Once all dependencies are in place, is time to launch our Kestrel web server:

F1 (Fn + F1) dnx: Run > dnx web – (WebApplicationBasic)

vscode-dnx-run-command vscode-dnx-web

Sergios-MacBook-Pro:WebApplicationBasic Sergio$ cd '/Users/Sergio/Projects/WebApplicationBasic' ; /Users/Sergio/.dnx/runtimes/dnx-mono.1.0.0-rc1-final/bin/dnx web Hosting environment: Production Now listening on: http://localhost:5000 Application started. Press Ctrl+C to shut down.

And that’s all! Open your favourite web browser and type http://localhost:5000. Here is your ASP.NET website running on Mac OS X:


Important: Visual Studio Code do not support web debugging by the moment.