====== .NET Core in Linux ======

===== Installation of .NET Core =====

<WRAP center round info 60%>
These instructions are for .NET Core v1.0.4 in Linux Mint 18.  Instructions for other versions and other distros are very similar.

Please visit https://www.microsoft.com/net/core for more information.
</WRAP>

Add the apt-get feed for Linux Mint 18:

<code bash>
sudo sh -c 'echo "deb [arch=amd64] https://apt-mo.trafficmanager.net/repos/dotnet-release/ xenial main" > /etc/apt/sources.list.d/dotnetdev.list'

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 417A0893

sudo apt-get update
</code>

Install the .NET Core SDK:

<code bash>
sudo apt-get install dotnet-dev-1.0.4
</code>

If you'd like to install a different version, ensure that you're installing the latest version, or just check to see what's available, you can search with apt-cache:

<code bash>
apt-cache search dotnet
</code>

Create a test app:

<code bash>
dotnet new console -o testinstallation

cd testinstallation
</code>

Restore the app's required packages, and run it:

<code bash>
dotnet restore

dotnet run
</code>

When you see "**Hello, World!**" as your output, you've verified your installation, and .NET Core is ready to go!

===== Visual Studio Code =====

There's no "Visual Studio IDE Community Edition" for Linux //yet//, but Microsoft has created a very capable cross-platform programmer's editor called Visual Studio Code.  It includes many of the handy features and behaviors you've grown used to in the Visual Studio IDE.

  - Go to https://www.visualstudio.com/
  - Click the Visual Studio Code download button.
  - Click the .deb button.
  - After the download completes, click the .deb file.  It will launch Package Installer automatically.
  - Click the "Install Package" button.

After the installation completes, locate Visual Studio Code in your menu and launch it.

Before you start working on any projects, you'll need to install the C# extension:

  - Locate the Extensions button in the sidebar and click it.
  - In the search box, type **C#**.  It will probably be the first match.  Verify by looking for the description "C# for Visual Studio Code (powered by OmniSharp)".
  - Click the Install button.
  - After the install completes, you'll be prompted with a Reload button.  Go ahead and click it.  The extension will be activated.

<WRAP center round tip 60%>
Visual Studio Code has a very active extension community.  I recommend searching the extension marketplace.  You'll find lots of useful items.

One example:  You'll probably want to install the "C# Extensions" extension, by jchannon.  It simplifies the creation of C# classes and interfaces.
</WRAP>

Now you're ready to create some projects!

===== .NET Core Project Examples =====

The .NET Core CLI provides several project templates.  This command:

<code bash>
dotnet new
</code>

...will show you a list, something like this:

<code>
Templates                 Short Name      Language      Tags
----------------------------------------------------------------------
Console Application       console         [C#], F#      Common/Console
Class library             classlib        [C#], F#      Common/Library
Unit Test Project         mstest          [C#], F#      Test/MSTest
xUnit Test Project        xunit           [C#], F#      Test/xUnit
ASP.NET Core Empty        web             [C#]          Web/Empty
ASP.NET Core Web App      mvc             [C#], F#      Web/MVC
ASP.NET Core Web API      webapi          [C#]          Web/WebAPI
Solution File             sln                           Solution
</code>

The calling convention to create a project is as follows:

<code bash>
dotnet new <template short name> -o <project name>
</code>

The -o argument is optional, but I recommend using it, since it also controls the naming of the files in the project folder, along with creating the folder itself.

Let's step through the creation of the console, mvc, and webapi project types.

==== Console Application ====

A console project is the simplest, and is nice for finding your way around.  We'll create a console project called "Hello", and restore its required packages:

<code bash>
dotnet new console -o Hello

cd Hello

dotnet restore
</code>

  - After you create the project, open Visual Studio Code.
  - On the Welcome page, you'll see an "Open folder..." link.  Click it, and open the Hello project folder.
  - In the Explorer panel, click Program.cs.
  - You'll see a prompt indicating that required assets to build and debug are missing, asking if you'd like to add them.  Click "Yes".

At this point, you have a runnable project.  Press [F5].  The project will build and run, and you'll see "Hello World!" in your Debug console.

Now you can make any changes you require.  As a simple exercise, we'll create a Greeter class to handle our "Hello World" duties. :-)

  - In the sidebar, click Explorer, to show the file list.
  - In any empty space, right-click and select "New file".
  - Name the file "Greeter.cs".
  - Create a basic class, with a hello method, as follows:

<code csharp>
using System;

namespace Hello
{
    public class Greeter
    {
        public void SayHello()
        {
            Console.WriteLine("Hello, world!");
        }
    }
}
</code>

  - Click "Program.cs" in the Explorer panel.
  - Replace the **Console.WriteLine("Hello World!");** line with this:

<code csharp>
Greeter myGreeter = new Greeter();
myGreeter.SayHello();
</code>

Press [F5], and you should see "Hello, world!" in the Debug console.

You've now generated a console app, and enhanced it with a simple class!

==== ASP.NET Core Web App (MVC) ====

Now we'll move from a text-based console client to the web.

Generate a MVC web application project:

<code bash>
dotnet new mvc -o SimpleMVC

cd SimpleMVC

dotnet restore
</code>

  - Open Visual Studio Code, then open the new MVC project by clicking "Open folder..." and selecting the SimpleMVC folder.
  - Click Startup.cs, and add the required assets when prompted.

The project should now be runnable.  Press [F5], and the project will build and run.  It should launch in your default web browser as localhost on port 5000.  You will see a simple application with "Home", "About", and "Contact" pages.  After you've clicked each page and verified that they load properly, close the browser tab and stop the running project by clicking the "Stop" button in Visual Studio Code.

Let's add a new page called "Company":

  - In the Explorer panel, right-click on the "Home" folder (under "Views"), and select "New File".
  - Name the file "Company.cshtml".

Add the following HTML to Company.cshtml:

<code html>
@{
    ViewData["Title"] = "Company";
}

<h2>Company Name</h2>
<p>Company info will go here</p>
</code>

Open HomeController.cs and add an action result for the new page:

<code csharp>
public IActionResult Company()
{
  return View();
}
</code>

Open _Layout.cshtml (in Views/Shared) and add a menu entry for the new page in the "nav navbar-nav" section:

<code html>
<li><a asp-area="" asp-controller="Home" asp-action="Company">Company</a></li>
</code>

Press [F5] to compile and run.  You should see a new entry for "Company" in the menu.  Clicking it should load the new page.

==== Postman ====

Before moving on to creating a web service, you'll need a way to //test// your service.  I recommend Postman.  You can download it [[https://www.getpostman.com/|here]].

  - Choose the Linux download, 64 or 32-bit.
  - The Postman archive will download automatically.
  - Extract it wherever you like.
  - Click "Postman" in the extracted folder to run it.

For local testing of services, it's as simple as this:

  - Select the request type.  (GET, POST, PUT, etc.)
  - Copy the request URL to the "Enter request URL" field.
  - Click "Send".

Postman also supports various authentication types, sending complex requests, additional headers, etc, but we won't need these features for the service we're creating.

==== ASP.NET Core Web API ====

For our final project, we'll create a simple RESTful web service.

Generate a Web API project:

<code bash>
dotnet new webapi -o SimpleService

cd SimpleService

dotnet restore
</code>

  - Open Visual Studio Code, then open the new Web API project by clicking “Open folder…” and selecting the SimpleService folder.
  - Click Startup.cs (in the Explorer tab), and add the required assets when prompted.

Open the ValuesController.cs file (in the Controllers folder) and you'll see that the template has already generated some endpoints for you.  Let's test the api/values endpoint:

  - Press [F5].  The project will compile and run, launching your default web browser.
  - The browser will report that it is unable to load localhost:5000.  That's OK! (The root path is not a valid endpoint.)
  - Leave the project running, and load Postman.
  - Make sure you have "GET" selected as your request type.
  - Enter the following URL into the Postman "Enter request URL" field: http://localhost:5000/api/values
  - Click "Send".

You should see this returned in Postman:

<code javascript>
[
  "value1",
  "value2"
]
</code>

If you look at the matching code in ValuesController.cs:

<code csharp>
// GET api/values
[HttpGet]
public IEnumerable<string> Get()
{
  return new string[] { "value1", "value2" };
}
</code>

...you can see that this is what it's supposed to be returning.

<WRAP center round tip 60%>
Visual Studio Code also has integrated debugging.

  - Add a breakpoint on the "return new string..." line by clicking just to the left of the line number.
  - Switch back to Postman and click "Send" again.  Execution of the service will pause on the line with the breakpoint.
  - Continue by pressing [F5].
</WRAP>

Now, stop the service by clicking the "Stop" button in Visual Studio Code, and we'll add our own controller.  We'll add a very simple "Get" endpoint that takes a number and returns the square root of that number.

  - Right-click on the Controllers folder and select "Add file".
  - Name it "MathController.cs".
  - Add the following code to MathController.cs:

<code csharp>
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;

namespace SimpleService.Controllers
{
    [Route("api/[controller]")]
    public class MathController : Controller
    {
        // GET api/math/5
        [HttpGet("{id}")]
        public string Get(double id)
        {
            return Math.Sqrt(id).ToString();
        }
    }
}
</code>

  - In Postman, change your request URL to this: http://localhost:5000/api/math/25
  - Click "Send".

You should see a "5" returned.

Now, let's take it one step further, and add a Model to do our math work for us.

  - Stop the service, if it's still running.
  - Right-click on an empty space in the Explorer pane, and select "New folder". Name it "Models".
  - Right-click on Models and select "New file".  Name it MathProvider.cs.
  - Add the following code to MathProvider.cs:

<code csharp>
using System;

namespace SimpleService.Models
{
    public class MathProvider
    {
        public double GetSquareRoot(double inputValue)
        {
            return Math.Sqrt(inputValue);
        }
    }
}
</code>

  - Switch to MathController.cs.
  - Add a using statement to make our new Models class accessible to the controller:

<code csharp>
using SimpleService.Models;
</code>

Change the Get method as follows:

<code csharp>
public string Get(double id)
{
  MathProvider myMath = new MathProvider();

  return myMath.GetSquareRoot(id).ToString();
}
</code>

  - Click [F5] to run the service.
  - In Postman, click "Send".

You will see a "5" returned again, but now it will be returned from our new model.  (If you'd like, set a breakpoint in the GetSquareRoot method of the MathProvider class to confirm that it's being hit.)

Congratulations, you've created a Web API service and added your own endpoint, along with a new model!

===== Installing Nuget Packages =====

To add nuget packages to an existing project, open a terminal in the root folder of the project, then issue a dotnet command in the following format:

<code bash>
dotnet add <PROJECT> package [arguments] [options]
</code>

For example, to add the Microsoft.AspNetCore.StaticFiles package, you'd do this:

<code bash>
dotnet add package Microsoft.AspNetCore.StaticFiles
</code>

If you want to add a specific version of a package, use the -v argument, like this:

<code bash>
dotnet add package Microsoft.AspNetCore.StaticFiles -v 1.0.1
</code>

{{tag>dotnet}}