Develop and Deploy ASP.NET 5 Apps on Mac OS X

NOTE: This post is part 1 of a series on developing and deploying cross-platform web apps with ASP.NET 5:

  1. Develop and Deploy ASP.NET 5 Apps on Mac OS X (this post)
  2. Develop and Deploy ASP.NET 5 Apps on Linux
  3. Deploy ASP.NET 5 Apps to Docker on Linux
  4. Deploy ASP.NET 5 Apps to Docker on Azure

Download instructions and code for this post here:

The day has arrived when you can both develop and deploy an ASP.NET application on an Apple Mac.  Notice I said, develop, not just deploy.  For that you’re going to need either a souped up text editor (such as Sublime Text, Brackets, Atom, Emacs or Vim) together with OmniSharp for intellisense, or you’ll want to use Visual Studio Code, the new cross-platform IDE from Microsoft that uses OmniSharp with Roslyn and provides Git integration for version control, plus limited debugging support.  To get started setting up and using VS Code, check out the docs.

So why would you want to forsake full-blown Visual Studio running on Windows for a stripped down version running on OS X?

I’m not saying you should.  VS Code is still in preview and, at the time of this writing, lacks support for debugging ASP.NET 5 apps (although it’s promised soon).  And Microsoft offers the Community Edition of Visual Studio for free.  It’s more a matter of getting out of your comfort zone and trying something different.  It’s also about using different tools for different things.  I happen to use a MacBook Air, mainly because of the amazing hardware, and I like how iCloud syncs everything with my iPhone and iPad.  And while I have no problem running Windows in a virtual machine on my Mac using Parallels, it’s nice to hack together a web app for ASP.NET 5 on my Mac without having to fire up Win 8 and load Visual Studio, both of which gobble up a chunk of RAM. Note that while you’ll need to own a Mac, if you’re running Parallels you can create a virtual machine that runs OS X, which will allow you to create snapshots in time, so that you can easily revert to an earlier state.


To develop ASP.NET 5 apps on a Mac, we’ll start with these instructions for installing VS Code. (By the way, VS Code can also be used for TypeScript and Node.js development.) In order to launch VS Code from a Terminal window, you’ll want to add some entries to your .bash_profile file.  You can check to see if the file already exists by changing to your root directory with cd ~/, and then entering ls –a, to list all files, including hidden ones (those are the ones with names starting with a dot).  If .bash_profile does not exist, enter: touch .bash_profile.  Otherwise if it does exist, enter open -e .bash_profile, and it will open in TextEdit.  Then add the following text to the file:

code () {
    if [[ $# = 0 ]]
        open -a "Visual Studio Code"
        [[ $1 = /* ]] && F="$1" || F="$PWD/${1#./}"
        open -a "Visual Studio Code" --args "$F"
export PATH="~/npm-global/bin:$PATH"

This will allow you to launch VS Code at any folder from the terminal window simply by typing code ., so that you can start editing files contained in that folder.  It also sets up the Node package manager to install Yeoman and makes the DotNet Version Manager for every Terminal session (see below).

Next, you’ll want to install ASP.NET 5 on Mac OS X, so that you can deploy web apps on a Mac.  The docs list instructions for installing ASP.NET 5 on Mac OS X, which can be summarized as follows:

  • Install Homebrew with the command line developer tools
  • Tap the ASP.NET 5 repo from Homebrew
  • Install the DotNet Version Manager

ruby -e “$(curl -fsSL”
brew tap aspnet/dnx
brew install dnvm

dnvm upgrade

After this, entering dnvm will bring up the version manager, which allows you to select and configure different versions of the ASP.NET 5 runtime.


To see which versions are installed, enter: dnvm list.


Next, you’ll create a directory and fire up VS Code to create your first ASP.NET 5 app.  We’ll start with a Hello World console app! The quickest approach is to grab two files from the ConsoleApp folder for the AspNet Samples Repo: project.json and program.cs.

Here is project.json for the console app, which lists the dependencies you’ll bring in.

    "dependencies": {

    "commands": {
        "ConsoleApp": "ConsoleApp"
    "frameworks": {
        "dnx451": { },
        "dnxcore50": {
            "dependencies": {
                "System.Console": "4.0.0-beta-*"

And here is program.cs, which simply prints “Hello World” to the console.

using System;

public class Program
    public static void Main()
        Console.WriteLine("Hello World");

Editing program.cs in Visual Studio Code looks like this:


To launch the app, open Terminal at the ConsoleApp directory, then restore the dependencies and execute the program.

dnu restore
dnx . run


You should see “Hello World” printed to the Terminal window.


Console apps are well-suited for running tasks on a server, but more often you’ll use ASP.NET 5 to run web apps. The AspNet repo on GitHub has a HelloWeb sample, where you can grab two files: project.json and startup.cs.

Here is the project.json file for the web app.  Notice the “kestrel” command for starting an HTTP listener on Mac OS X and Linux.

    "version": "1.0.0-*",
    "dependencies": {
        "Kestrel": "1.0.0-*",
        "Microsoft.AspNet.Diagnostics": "1.0.0-*",
    "commands": {
        "kestrel": "Microsoft.AspNet.Hosting --server Kestrel --server.urls http://localhost:5004"
    "frameworks": {
        "dnx451": { },
        "dnxcore50": { }

Here is the startup.cs file, which configures the pipeline with an endpoint for displaying a welcome page.

using Microsoft.AspNet.Builder;

namespace HelloWeb
    public class Startup
        public void Configure(IApplicationBuilder app)

To start the web server, restore dependencies and then enter the kestrel command.

dnu restore
dnx . kestrel


VS Code also allows you to execute commands from the command palette, which you can bring up by typing ⇧⌘P.  From there enter a command listed in the “commands” section of project.json, for example, “kestrel”.


Then open a browser and enter the address: http://localhost:5004. You’ll see a message stating the web server has started. To end it, press Enter.  If it does not stop, open another terminal to kill the process: ps {To see a list of PIDS} kill -9 {PID #}.


Aside from running the console and web Hello World samples, you’re going to want to develop your own applications based on templates you’d find in Visual Studio on Windows.  To get a similar experience, you can install Yeoman, which scaffolds various kinds of ASP.NET 5 apps, such as MVC 6 or Web API (which is technically now part of MVC 6). To install Yeoman you’ll need the Node Package Manager, which you can download and install from here.  Once you have Node installed, you can use it to install Yeoman, the generator, grunt and bower – all in one fell swoop.

sudo npm install -g yo grunt-cli generator-aspnet bower


Having installed Yeoman, you can then navigate to a directory in Terminal where you’d like to create your new app in a child directory.  Then execute:

yo aspnet


This brings up a number of choices.  For example, you can select Web API Application, which then scaffolds the standard Web API app with a ValuesController. If you run dnu restore and dnx . kestrel, as you did with the sample web app, you can browse to the following URL to get back JSON values: http://localhost:5001/api/values.

And that is how you can both develop and deploy ASP.NET 5 apps on Mac OS X.  For the next part of this series, I’ll show you how to do the same on Linux.

About Tony Sneed

Sr. Software Solutions Architect, Hilti Global Application Software
This entry was posted in Technical and tagged , , , . Bookmark the permalink.

29 Responses to Develop and Deploy ASP.NET 5 Apps on Mac OS X

  1. Hi Tony, nice article, as always. It may worth noting, for those that are totally new to developing ASP.NET on Mac OSx that there are certain dependencies that need to be set up and are, unfortunately, missing from the instructions. This includes Node.js and Gulp. I was bitten by this before 😦 Other than that, concise and thorough post and I enjoyed it.

  2. Santosh says:

    Do you have any instruction on to debug web app in ios mac

    • Tony Sneed says:

      Yes, you can debug with Visual Studio Code v.10 or later using Mono. However, you cannot debug an ASP.NET 5 web app at this time. Support for ASP.NET 5 debugging will be available in VS Code at a later time.

  3. Bruno says:

    Hi Tony,
    can you please tell me how to debug on VS Code? (On OSX) I have mono installed but i have no luck on attaching the debugger on my MVC Web App. I tried to put a breakpoint in the controller but i got no luck on debugging.

    Thank You

    • Tony Sneed says:

      Presently you can debug Node.js, Mono apps in C#, and VS Code Extensions, but you cannot debug an ASP.NET 5 web app at this time. Support for ASP.NET 5 debugging will be available in VS Code at a later time.

      • Bruno says:

        Oh, alright.
        I knew that node.js and “.exe” could be debugged. I thought that ASP.NET 5 could be too.
        Anyways, thank you for your prompt answer!

  4. Stephen says:

    any advice on how to get an web app that requires a clickonce plugin to work in any mac browser?

    • Tony Sneed says:

      I believe ClickOnce is based on Windows and not portable to a Mac.

      • Stephen says:

        So how is someone supposed to run a web app on the mac that requires something like that? Is there anyway to accomplish that? I have installed on my mac, so that part is accomplished, it seems like the only missing piece is clickonce functionality, which used to be available on the mac in a firefox plug.

      • Tony Sneed says:

        ASP.NET 5 is a server-side web stack that can run on Mac or Linux, which you would use to write either a web ui or web api. ClickOnce is a client-side installer for Windows only. The two don’t have anything to do with one another.

        That said, if you want to run a client .NET app on a Mac, you should use Mono rather than ASP.NET, but Mono does not implement ClickOnce. Instead, you should look at alternatives such as Squirl (see this SO answer). Hope this helps.

  5. Carl Baron says:

    Hi Toni:
    I got this to run on Mono using xsp4. Have had a lot of problems with ASP.NET Core. Some problems were multiple DNXs and multiple project.jsons. I used MySql as database.

    Sample Log


  6. Aditya says:

    very useful article. Just wanted to add that dnx . run wasn’t working and on Google searching I found that the format has probably changed. ‘dnx run’ worked for me

  7. Brian says:

    What are the hoops you need to jump through to connect to SQL Server on Mac/Linux?

  8. Hi Tony,
    Thanks for the post. One question, can the same be done in IPAD mini 2 ?

    • Tony Sneed says:

      Sorry, .NET Core and Visual Studio Code won’t run on iOS. If you need to write mobile apps in C# you would need to use Xamarin.

      • Debdeep Chaudhuri says:

        Thanks for the reply. Actually i am hoping to run VS code to build 5 / core application on IPAD MINI 2. Which can be done in Mac book , you have shown a nice example of that also.
        Can the same is possible on IPAD MINI 2 also?

      • Carl Baron says:

        OSX is Unix 10. Microsoft has gone into the Unix Market. Xcode and Xamarian can develop apps for IOS. Apple does use certificates for IOS. Certicates are used to keep track of developers.

      • Tony Sneed says:

        You cannot use AspNet Core or .NET Core at this point to build apps that will run on iPad or any iOS device. For that use need to use Xamarin if you want to write it in C#.

  9. /hauke says:

    seems like the link to is dead. Maybe you’d like to fix it?
    Kind regards and thanks for your post,


  10. rickg says:

    You actually never cover deploying. Aka, can you show how to publish an MVC app from Mac VS 2017? There is no way to do it in the IDE from what I can tell; and using the dotnet publish doesn’t produce any file output on MVC files (I tested it on a console app and it works so MSBuild is fine).

    Long/short I have yet to see an example of how to publish a or mvc app on Mac. I believe the issue is with the web-config not having MSBuild info in it but I’m not sure what should be added. I also created a new MVC test project on Mac and tried to CLI dontnet publish it and again it produced no output.

    An example of how to publish would be awesome…

  11. very important information about development………
    helps a lot…very much thankful for sharing this article….
    keep sharing…..

  12. hasti says:


    I finish my application on .net core with azure data studio (sql) on mac

    now I don t know how can I should publish it .specially its database

    because its a little diffrenet with windows

    how can I get backup my database to upload on server?

    or is there any different way to upload and publish it?

  13. Brij says:


    I am developing .NET application in WPF with Framework .NET 5.0 and C#. Now want to deploy on MAC machine so let me know the procedure.


  14. Pingback: Visual Studio Code mac os x .net build and deploy - Programming Tutorial

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.