AspNetCore.Docs/docs/tutorials/your-first-mac-aspnet.rst

Your First ASP.NET 5 Application on a Mac
=========================================
By `Steve Smith`_ | Originally Published: 30 April 2015 

.. _`Steve Smith`: Author_

ASP.NET 5 is cross-platform and can be developed and run on OS X as well as Linux and Windows. See how you can quickly install, scaffold, run, debug, and deploy ASP.NET applications on a Mac.

This article covers the following topics:
	- `Setting Up Your Development Environment`_
	- `Scaffolding Applications Using Yeoman`_
	- `Developing ASP.NET Applications on a Mac With Visual Studio Code`_
	- `Running Locally Using Kestrel`_
	- `Publish to Azure`_



Setting Up Your Development Environment
---------------------------------------

First, make sure you have `installed ASP.NET on your Mac OS X machine </getting-started/installation/installing-on-mac/installing-on-mac>`_. This step will include installing `Homebrew <http://brew.sh/>`_ and configuring DNVM. This article has been tested with beta4. You can confirm that you are running the correct version of ``dnx`` by running the command ``dnvm list``. You should see ``default`` listed under the ``Alias`` column for ``1.0.0-beta4`` as shown:

.. image:: your-first-mac-aspnet/_static/dnvm-list-beta4.png

If you need to update the ``default`` alias, run ``dnvm alias default 1.0.0-beta4``.

Scaffolding Applications Using Yeoman
-------------------------------------

Coming soon: instructions for getting started with `Yeoman <http://yeoman.io>`_.

`Download a sample Empty Web Site <https://github.com/aspnet/docs/>`_ to use with this article.

Developing ASP.NET Applications on a Mac With Visual Studio Code
----------------------------------------------------------------

Now, install Visual Studio Code from `code.visualstudio.com <http://code.visualstudio.com>`_. Unzip the application and open it - the first time you should see the a welcome screen:

.. image:: your-first-mac-aspnet/_static/vscode-welcome.png

To get started with your first ASP.NET application on a Mac, select File -> Open and choose the folder where you unzipped the empty web site (or scaffolded a site with Yeoman).

.. image:: your-first-mac-aspnet/_static/file-open.png

Visual Studio Code may deted that you need to restore dependencies, as shown in this screenshot:

.. image:: your-first-mac-aspnet/_static/vscode-restore.png

From a Terminal / bash prompt, run ``dnu restore`` to restore the project's dependencies. At this point, you should be able to host and browse to your simple ASP.NET web application.

This empty project template simply displays "Hello World!". Open ``Startup.cs`` in Visual Studio Code to see how this is configured:

.. image:: your-first-mac-aspnet/_static/vscode-startupcs.png

If this is your first time using Visual Studio Code (or just *Code* for short), note that it provides a very steamlined, fast, clean interface for quickly working with files, while still providing tooling to make writing code extremely productive. 

In the left navigation bar, there are four icons, representing four viewlets:
	- Explore
	- Search
	- Git
	- Debug
	
The Explore viewlet allows you to quickly navigate within the folder system, as well as easily see the files you are currently working with. It displays a badge to indicate whether any files have unsaved changes, and new folders and files can easily be created (without having to open a separate dialog window). You can easily Save All from a menu option that appears on mouse over, as well.

The Search viewlet allows you to quickly search within the folder structure, searching filenames as well as contents.

*Code* will integrate with Git if it is installed on your system. You can easily initialize a new repository, make commits, and push changes from the git viewlet.

.. image:: your-first-mac-aspnet/_static/vscode-git.png

The Debug viewlet supports interactive debugging of applications. Currently only node.js and mono applications are supported by the interactive debugger.

Finally, Code's editor has a ton of great features. You should note right away that several using statements are underlined, because Code has determined they are not necessary. Note that classes and methods also display how many references there are in the project to them. If you're coming from Visual Studio, Code includes many of the keyboard shortcuts you're used to, such as ``command k c`` to comment a block of code, and ``command k u`` to uncomment.

Running Locally Using Kestrel
-----------------------------

The sample we're using is configured to use Kestrel as its webserver. You can see it configured in the ``project.json`` file, where it is specified as a dependency and as a command.

.. code-block:: javascript
	:linenos:
	:emphasize-lines: 8,13

	{
	  "webroot": "wwwroot",
	  "version": "1.0.0-*",

	  "dependencies": {
		"Microsoft.AspNet.Server.IIS": "1.0.0-beta4",
		"Microsoft.AspNet.Server.WebListener": "1.0.0-beta4",
		"Kestrel": "1.0.0-beta4-*"
	  },

	  "commands": {
		  "web": "Microsoft.AspNet.Hosting --server Microsoft.AspNet.Server.WebListener --server.urls http://localhost:5000",
		  "kestrel": "Microsoft.AspNet.Hosting --server Kestrel --server.urls http://localhost:5001"
	  },
	// more deleted
	
In order to run the ``kestrel`` command, which will launch the web application on localhost port 5001, run ``dnx . kestrel`` from a command prompt:

.. image:: your-first-mac-aspnet/_static/dnx-dot-kestrel.png

Navigate to ``localhost:5001`` and you should see:

.. image:: your-first-mac-aspnet/_static/hello-world.png

It's not necessarily obvious, but if you want to stop the web server once you've started it, simply press ``enter``. If that doesn't work, you can press ``control + z`` and then type ``kill %1`` to kill the process.

We can update the application to output information to the console whenever a request is received. Update the ``Configure()`` method as follows:

.. code-block:: c#
	:linenos:
	:emphasize-lines: 5
	
	public void Configure(IApplicationBuilder app)
        {
            app.Run(async (context) =>
            {
                Console.WriteLine("Request for " + context.Request.Path);
                await context.Response.WriteAsync("Hello World!");
            });
        }
		
Save the file and restart the web server. Make a few requests to the URL. You should see the request information output in the Terminal window (recall that most browsers will automatically attempt to request a ``favicon.ico`` file when making a request to a new domain):

.. image:: your-first-mac-aspnet/_static/kestrel-logging.png



Publishing to Azure
-------------------

Once you've developed your application, you can easily use the git integration built into Visual Studio Code to push updates to production, hosted on `Windows Azure <http://azure.microsoft.com>`_. First, if you haven't already done so, initialize git in the folder you're working in.



Summary
-------

ASP.NET 5 and DNX support installation on Mac OS X. Developers can quickly install the necessary tools to get started, including Yeoman for app scaffolding and `Visual Studio Code <http://code.visualstudio.com>`_ for rapid lightweight editing with built-in support for debugging, git integration, and Intellisense.

Additional Reading
------------------

Learn more about Visual Studio Code:
	- `Blog Post <http://blogs.msdn.com/>`_
	
	
.. include:: /_authors/steve-smith.rst