BROUGHT TO YOU IN PARTNERSHIP WITH

237
Get More Refcardz! Visit DZone.com/Refcardz

.NET Core on Linux

 Installing on Linux
CO N T E N TS
 Open Source Repositories
 The Layers of .NET Core
 dotnet Commands
BY DON SC HE NC K
 Tag Helpers... and more!

ANY DEVELOPER, ANY APP, ANY PLATFORM RED HAT ENTERPRISE LINUX 7 SERVER (64 BIT)

When .NET made its debut in 2002, it supported subscription-manager list --available
multiple languages, including C\# and Visual Basic (get the Pool Id to be used in the next step)
subscription-manager attach --pool=<Pool Id>
(VB). Over the years, many languages have been added
subscription-manager repos --enable=rhel-7-server-dotnet-rpms
to the .NET Framework. Because .NET Core is a new yum install scl-utils
development effort, language support must be re-in yum install rh-dotnet20
echo ‘source scl_source enable rh-dotnet20’ >>~/.bashrc
This refcard will guide you along the path to being scl enable rh-dotnet20 bash

productive using .NET Core on Linux, from installation UBUNTU 14.04 / LINUX MINT 17 (64 BIT)
to debugging. Information is available to help you
find documentation and discussions related to .NET sudo sh -c 'echo "deb [arch=amd64] https://apt-mo.
Core. An architectural overview is presented, as well trafficmanager.net/repos/dotnet-release/ trusty main" > /
etc/apt/sources.list.d/dotnetdev.list'
as tips for using the new Command Line Interface sudo apt-key adv --keyserver apt-mo.trafficmanager.net
(CLI). Building MVC web sites, RESTful services and --recv-keys 417A0893
standalone applications are also covered. Finally, sudo apt-get update

some tools and helpful settings are discussed as they

relate to your development efforts. UBUNTU 16.04 / LINUX MINT 18 (64 BIT)
Use the instructions for Ubuntu 14.04, replacing the
first command with:
INSTALLING .NET CORE 2.0 SDK ON LINUX
sudo sh -c 'echo "deb [arch=amd64] https://apt-mo.
CENTOS 7.1 (64 BIT) & ORACLE LINUX 7.1 (64 BIT)
trafficmanager.net/repos/dotnet-release/ xenial main" > /
Before starting, you must remove any previous etc/apt/sources.list.d/dotnetdev.list'
versions of .NET Core from your system
sudo yum install libunwind libicu UBUNTU 16.04 (64 BIT)
curl -sSL -o dotnet.tar.gz Use the instructions for Ubuntu 14.04, replacing the
https://go.microsoft.com/fwlink/?LinkID=809131
first command with:
sudo mkdir -p /opt/dotnet && sudo tar zxf dotnet.tar.gz
-C /opt/dotnet
sudo sh -c ‘echo "deb [arch=amd64]
sudo ln -s /opt/dotnet/dotnet /usr/local/bin
https://apt-mo.trafficmanager.net/repos/dotnet-release/
DEBIAN 8 (64 BIT) yakkety main"> /etc/apt/sources.list.d/dotnetdev.list’

sudo apt-get install curl libunwind8 gettext OTHER DISTROS

curl -sSL -o dotnet.tar.gz
https://go.microsoft.com/fwlink/?LinkID=809130
Visit the website dot.net.
sudo mkdir -p /opt/dotnet && sudo tar zxf dotnet.tar.gz -C
/opt/dotnet
sudo ln -s /opt/dotnet/dotnet /usr/local/bin

FEDORA 23 (64 BIT)

sudo dnf install libunwind libicu Get access to products and
curl -sSL -o dotnet.tar.gz https://go.microsoft.com/
fwlink/?LinkID=816869
resources to help you code.
sudo mkdir -p /opt/dotnet && sudo tar zxf dotnet.tar.gz
-C /opt/dotnet
Join Today. It’s free.
sudo ln -s /opt/dotnet/dotnet /usr/local/bin
DEVELOPERS.REDHAT.COM
.NET ON LINUX

FEDORA 24 (64 BIT)

sudo dnf install libunwind libicu
curl -sSL -o dotnet.tar.gz
https://go.microsoft.com/fwlink/?LinkID=848833
sudo mkdir -p /opt/dotnet && sudo tar zxf dotnet.tar.gz
-C /opt/dotnet
sudo ln -s /opt/dotnet/dotnet /usr/local/bin

© DZONE , INC . | DZO NE .CO M

.NET CORE 2.0 FOR
RED HAT ENTERPRISE
LINUX AND OPENSHIFT
CONTAINER PLATFORM

Truly portable .NET applications are here with

.NET Core 2.0. Develop microservices on your
device of choice, and deploy them as Linux
containers on Red Hat Enterprise Linux,
OpenShift Container Platform, and more.

Get started at RedHatLoves.NET

 3 .NET ON LINUX

such as dynamic compilation and access to objects and

OPEN SOURCE MEANS REPOSITORIES
strings, etc., are included in this layer.
At GitHub.com: TOOLING
Finally, the "add-on" part, completely separate from
PROJECT DESCRIPTION REPOSITORY
.NET Core yet used by many developers. Anything in
.NET Core foundational
CoreFX /dotnet/corefx/ Visual Studio or Visual Studio Code that makes it easier
libraries.
for the developer—Intellisense, a powerful autocomplete
Core .NET Core runtime and base
dotnet/coreclr/ helper, for example—is contained in this layer.
runtime library (mscorlib).
Client WCF libraries that allow
/dotnet/wcf/
THE \`DOTNET\` COMMAND
WCF .NET Core applications to com-
municate with WCF services. After installing .NET Core, you’ll use the command-
line tool dotnet, to do everything from creating code
CLI Command-line tools. /dotnet/cli/
to publishing the application. Note that the default
ASP.NET language is C\#, with support for F\# and VB included.
ASP.NET MVC framework. /aspnet/mvc/
MVC
Entity USEFUL DOTNET COMMANDS
/aspnet/EntityFrame-
Frame- Entity Framework data access. work/ IF YOU WANT TO... USE THE COMMAND...
work See what version you have dotnet --version
Templat- .NET templates for creating See more information about your
/templating/ dotnet --info
ing Engin code. CLI
Create a basic "Hello World" con-
THE LAYERS OF .NET CORE dotnet new console
sole app
.NET Core, and the associated pieces (ASP.NET, Entity Create a simple MVC web app dotnet new --type web
Framework, etc) are separated into layers. While this may
Create an VB "Hello World" console
seem disjointed, in fact it’s a powerful move, one that dotnet new --lang VB
app
allows the developer to pick and choose the bits they want.
Create a library dotnet new --type lib
It also means faster development of updates, and will allow
Add a package reference to a dotnet add package
the developer to decide which versions to employ. <PACKAGE_NAME>
project
Restore an app’s dependencies dotnet restore

Compile an app dotnet build

Run an app dotnet run

dotnet run --project &lt;-

Run an app in another location path-to-project&gt;

Publish an app for deployment dotnet publish

Get help dotnet --help

CREATING THE HELLO WORLD CONSOLE APP

THE LAYERS EXPLAINED The following three commands will create and run a
.NET CORE CLR console Hello World application.
This is the runtime, the very foundation of .NET.
dotnet new console -- This creates the source code.
Included are the just-in-time compiler and Virtual
Machine, type system, garbage collection, and more. The Program.cs file contains the working code. Note that
dotnet restore is run automatically after creating
.NET COREFX the code.
The "System" libraries are here, things such as reflection
dotnet run -- This builds and runs the application.
and streams, etc. When you reference, for example,
System.Console in your program, you’re using the core
.NET libraries in this layer. It is at this layer where a A CLOSER LOOK AT THE DOTNET RESTORE COMMAND
simple console application will run. The dotnet new command creates code (using templates
.NET CLI that are being built into .NET Core), but the dotnet restore
This is, simply, the command line interface (CLI). command will gather the dependencies necessary for
your code to compile. If you are familiar with other
ASPNET CORE
languages, you know it is necessary to use their package
The level that supports application development. Things

© DZONE , INC . | DZO NE .CO M

 4 .NET ON LINUX

manager to retrieve the dependencies for your project. For When listing your dependencies in the *.csproj file, you
example, you may use npm when developing in node.js in must also specify the version of the library. For example,
order to fetch your dependencies. <PackageReference Include="Microsoft.AspNetCore.All"
Version="2.0.0" />.
Likewise, the dotnet restore command is the equivalent
in .NET Core; it is a package manager. When executed, In this particular example, we are locking our
it will use your configuration to locate and retrieve dependency to version 2.0.0. You can search nuget.
any dependent libraries (and their dependencies, etc.) org to find versions of libraries. Or, if you are using an
for your project. The configuration that guides the editor with Intellisense such as Visual Studio or Visual
dotnet restore command is made up of two parts: The Studio Code, it will allow you to choose from a list of
*.xxproj file (e.g. helloworld.csproj), which lists your valid versions.
dependencies, and the NuGet configuration file, which
directs from where to fetch the dependencies. WHAT DOES DOTNET BUILD DO?

The NuGet configuration file, NuGet.Config, is located at When you run dotnet build, or if you run dotnet run and
~/.nuget/NuGet/NuGet.Config. This file contains a list
it automatically creates a new binary, by default it will
of endpoints used when fetching dependencies. The create a DLL at the following location:
endpoints can point to anywhere that can be reached
./bin/[configuration]/[framework]/[binary name]
from your machine, including the internet and internal
storage. The following lists the contents of the default
NuGet.Config file:
Using the HelloWorld application in a directory labeled
"helloworld" as an example, running dotnet build would
<configuration> result in:
<packageSources>
<add key="nuget.org" value="https://api.nuget.org/v3/ ~/helloworld/bin/Debug/netcoreapp1.0/helloworld.dll
index.json" protocolVersion="3" />
</packageSources>
</configuration>
This DLL is what is known as a Portable App, meaning it
can run on any system that has .NET Core installed.
You can add endpoints; they are searched in order. Copying this DLL to another system -- whether Linux,
You do not need to point to nuget.org. For example, MacOS or Windows -- means it can be run on that
you can use daily builds of .NET Core (obviously not
recommended for production) by switching to myget.org.
system using the dotnet run command. This powerful
For example, https://dotnet.myget.org/F/dotnetcore/api/
feature allows you to write once, run anywhere, as long
v3/index.json.
as .NETCore is installed on the target system.
You can override the default NuGet.Config file by storing a
project-specific copy in your project’s root directory. For What if .NET Core is not installed on the target system?
example, if your project is located at ~/src/mvc, you can In that case, you can build a self-hosting app, meaning
create the file ~/src/mvc/NuGet.Config and it will be used you can compile it for the target operating system, then
before the default file. distribute it. To run it, it does not need .NET Core installed
on the target system; the dotnet publish command will
WHERE ARE THE DEPENDENCIES STORED? copy all the necessary bits (libraries) into the target build
By default, all dependencies are stored locally on your directory. You need only to copy the contents of that
machine at ~/.nuget/packages/. You can override this directory to another system and it will execute.
by specify a path in the environment variable **DOTNET_
PACKAGES** before running the dotnet restore command. Note that you can build for any OS from any OS. This
As the dependencies are downloaded, a file is created powerful feature means you can build standalone
(or updated if it already exists) in the root directory of applications for Windows from Linux, for MacOS from
your project. The file, obj/project.assets.json, contains Windows, etc.
a list of your dependencies. This list snapshot in time is
used to when you run the dotnet restore command. You The details of creating a standalone application are
can delete this file, but you’ll need to run dotnet restore covered later in this refcard.
again before your next compile. The file is not needed to
HOW TO CREATE A BASIC ASP.NET MVC WEBSITE
run your application, only to build it.
The dotnet net new command has options to allow you to
build an ASP.NET MVC website. This is similar to using
DEPENDENCY VERSIONS
Visual Studio to create a new website and choosing the

© DZONE , INC . | DZO NE .CO M

 5 .NET ON LINUX

MVC option. To build and run a simple MVC website, use

TAG HELPER DEFINITION
the following:
Allows you to specify additional parameters for the
dotnet net new mvc controller, based on the name of the attribute. For exam-
asp-route-
dotnet run ple, asp-route-id could be set by using asp-route-
id="@ViewBag.ItemId".

You can now view the basic ASP.NET MVC website at asp-src-include
Include files with the ability to use globbing, e.g. asp-
http://localhost:5000. src-include="/scripts/**/*.js".

Used in conjunction with asp-src-include to exclude

asp-src-exclude
Note that if you’re running Linux in a VM, the localhost file(s).
will be accessible only inside the VM, and not from your
Windows host machine. You can make the website ANOTHER TAG HELPER EXAMPLE
accessible from the Windows host by using an environment <td>
variable in Linux: <a asp-action="Edit" asp-route-id="@item.ID">Edit</a>
<a asp-action="Details" asp-route-id="@item.ID">Details</a>
export ASPNETCORE_URLS=http://*:5000 <a asp-action="Delete" asp-route-id="@item.ID">Delete</a>
</td>
From your Windows host machine, open the browser and
point it to the IP address of your VM. For example, Which creates this HTML:
*http://10.1.2.2.:5000*.
<td>
When finished, pressing Ctrl-C will shut down the <a href="/Submissions/Edit/1">Edit</a>
<a href="/Submissions/Details/1">Details</a>
web server.
<a href="/Submissions/Delete/1">Delete</a>
ASP.NET RAZOR TAG HELPERS </td>

One of the improvements in ASP.NET is the new "Tag

Helper" feature. This feature allows you to use more DEBUGGING
HTML-like code constructs in your Razor code and less By sharing a volume between your host Windows PC
C#-type code. and a Linux machine (physical or VM, either will work),
HTML HELPER VS. TAG HELPER that lays the foundation for allowing you to be able to
@Html.LabelFor(m => Model.FirstName, new {htmlAttributes =
debug .NET Core applications from within Visual Studio.
new { @class = "control-label" }, }) There are four steps to configuring debugging between
a Windows host and a Linux VM, then one configuration
Is replaced with: step required for each project you wish to debug.
<label asp-for="FirstName" class="control-label"></label>
1. Enable Visual C++ iOS Development in Visual Studio
2015 Update 2 or newer. This is done by selecting
BINDING TO A CONTROLLER ACTION WITH A TAG HELPER Visual Studio in the Windows Programs and Features
<form asp-controller="Submissions" asp-action="Details"></ applet in the Control panel and modifying the
form>
installation to include "Visual C++ iOS Development".

SOME COMMON TAG HELPERS 2. On the Linux VM, install the cross-platform debugger
TAG HELPER DEFINITION from Microsoft, CLRDBG. Use the following command,
Used to create the HTML for a property. For example, which reads a bash script from GitHub and executes
asp-for <input asp-for="AlbumTitle" /> will create an it on your VM, to install the debugger into the
input area for the model property AlbumTitle. directory ~/clrdbg:
Defines which action will be used in the current a. curl -sSL
asp-action
controller.
[*https://raw.githubusercontent.com/Microsoft/MIEngine/
asp-all-route-data Allows you to append query string information to a URL.
getclrdbg-release/scripts/GetClrDbg.sh*](https://raw.
asp-controller Determines which Controller will be used githubusercontent.com/Microsoft/MIEngine/getclrdbg-release/
scripts/GetClrDbg.sh)
asp-fragment Allows you to specify a page fragment, e.g. "TOC". | bash /dev/stdin vs2015u2 \~/clrdbg

asp-host Allows you to specify a host, e.g. "google.com". 3. Set up ssh

asp-protocol Allows you to specify a protocol, e.g. "https".
a. Download PuTTYgen.exe and plink.exe from the
asp-route Determines which Route will be used PuTTY web site: I

© DZONE , INC . | DZO NE .CO M

 6 .NET ON LINUX

b. Run PuTTYgen.exe and generate a public/private DATA

NAME DEFINITION
TYPE
key pair. > Save the private key to C:\mytools\
private_key.ppk. > Copy and paste the public "version" string The Semver version of the project.
key into the file > ~/.ssh/authorized_keys on
your Linux machine. The longer description of the project, used in
"description" string
assembly properties.
c. Test the connection by running c:\mytools\
plink.exe -i > c:\mytools\private_key.ppk > The friendly name. Special characters and spaces
<username>@<Linux_machine_IP_address> -batch -t "title" string can be used (they’re not allowed in the "name"
> echo "SSH Successful!" property). This is used in the assembly properties.

4. Share a folder/directory between the Windows host Which testing tool: NUnit, xUnit, etc. An entry
"testRunner" string here also indicates that this is a test project (i.e.
and the Linux > machine
created with dotnet new --type xunittest).

a. Create a shared folder on the Windows host A JSON object that lists the dependencies used
"dependen- JSON
called "shared". by the project. These are downloaded when
cies" object
dotnet restore is run.
b. Create a directory on the Linux machine called "/ JSON Defines the tools available, including making the
"tools"
shared". object dotnet ef command available.
Previously "compilationOptions", this is where
c. If you are using Vagrant, add the following line "buildOp- JSON compile-time options are set. For example, "emi-
to your Vagrantfile: config.vm.synced_folder "\\ tions" object tEntryPoint" can be set to true or false to create
shared", "/shared" an executable or DLL.
Allows you to establishing different project con-
5. Create the launch options XML file and add it to your "configura- JSON
figurations such as Release, Debug, Staging, etc.
tions" object
project in Visual Studio. Call it "OffRoadDebug.xml": This setting is available to your code.

&lt;?xml version="1.0" encoding="utf-8"

?&gt;&lt;PipeLaunchOptions
CREATING THE SELF-HOSTING APPLICATION
xmlns="[*http://schemas.microsoft.com/vstudio/
By default, a new .NET Core application is a portable
MDDDebuggerOptions/2014*](http://schemas.microsoft.com/
vstudio/MDDDebuggerOptions/2014)" application. In fact, it’s not even an .EXE file; it’s a DLL.
PipePath="c:\\mytools\\plink.exe" PipeArguments="-i You can take that DLL and run it on any system that has
c:\\mytools\\private\_key.ppk .NET Core installed -- Linux, MacOS or Windows.
&lt;username&gt;@&lt;Linux\_machine\_IP\_address&gt;
The same DLL runs everywhere.
-batch -t
\~/clrdbg/clrdbg --interpreter=mi"
TargetArchitecture="x64" But what if you want to create an application that
MIMode="clrdbg" ExePath="dotnet" needs to run on a system that does not have .NET Core
WorkingDirectory="\~/sharewithvm/mvc"
ExeArguments="bin/Debug/netcoreapp1.0/mvc.
installed? It’s much more polite than, say, telling the user
dll"&gt;&lt;/PipeLaunchOptions&gt; they need to install the .NET Core framework first.

6. In Visual Studio, open a command window (Menu

Fortunately, it can be done. You can create a self-hosting
-&gt; View -&gt; Other Windows -&gt; Command Window)
application that can be sent to or downloaded from
and run the following command to start debugging:
anywhere and then executed.

d. Debug.MIDebugLaunch /Executable:dotnet/
To start, create a portable app by running dotnet new in
OptionsFile:C:\\<path-to-file>\\OffRoadDebug.xml
a directory named selfhost.

THE .CSPROJ FILE Now, instead of dotnet run or dotnet build, use the
following command:
The project.json file determines everything from
dependencies to build options to which tools are
dotnet publish -r Release -c win10-x64
used, and much more. Here’s a list of some of the
settings available:
This will create a self-hosting app at bin/Release/
DATA netcoreapp2.0/win10-x64/publish. Copy the contents of
NAME DEFINITION
TYPE this directory to a Windows 10 machine and you can run
"name" string The name of your application. the created selfhost.exe -- no .NET installation necessary.
The "win10-x64" is what is known as a Runtime Identifier

© DZONE , INC . | DZO NE .CO M

 7 .NET ON LINUX

(RID). This value instructs the compiler to build for a today, but it is the future of .NET. Because you can work
specific operating system -- in this case, Windows 10, in any OS—MacOS, Windows or Linux—you can easily
64-bit. A list of values can be found at (https://docs. switch between environments and remain productive.
microsoft.com/en-us/dotnet/articles/core/rid-catalog). Further, you can now use your .NET development skills
to work with and on open source software. This is the
dotnet restore
dotnet build rhel.7.2-x64
future, and the future is now.

Checking the contents of this directory reveals a FURTHER RESOURCES

standalone application. Simply distribute all the contents
• The Microsoft web site for .NET Core: dot.net
of this directory and it can be run on any system without
needing to install .NET Core. • The Red Hat web site for .NET Core on Linux:
redhatloves.net
CONCLUSION
• "Transitioning to .NET Core on Red Hat Enterprise
From a simple console application to a complex Linux" ebook: > developers.redhat.com/
architecture of RESTful microservices and web sites promotions/dot-net-core
running in Linux containers, .NET Core is not only ready
• .NET Weekly Standup Meeting: > live.asp.net

ABOUT THE AUTHOR

DON SCHENCK A developer since the beginning of time, Don is currently a Director of Developer
Experience at Red Hat, with a focus on Microsoft .NET on Linux. His mission is to bring .NET developers
into the Linux and open source communities. He also the author of "Getting Started with .NET on
Linux" by O’Reilly Media. Prior to Red Hat, Don was a Developer Advocate at Rackspace. His passion is
cooking and he hates the designated hitter rule.

BROWSE OUR COLLECTION OF FREE RESOURCES, INCLUDING:

RESEARCH GUIDES: Unbiased insight from leading tech experts

REFCARDZ: Library of 200+ reference cards covering the latest tech topics

COMMUNITIES: Share links, author articles, and engage with other tech experts

JOIN NOW

BROUGHT TO YOU IN PARTNERSHIP WITH

DZONE, INC.
150 PRESTON EXECUTIVE DR.
CARY, NC 27513
DZone communities deliver over 6 million pages each month to more than 3.3 million software 888.678.0399
developers, architects and decision makers. DZone offers something for everyone, including 919.678.0300
news, tutorials, cheat sheets, research guides, feature articles, source code and more.
REFCARDZ FEEDBACK WELCOME
"DZone is a developer's dream," says PC Magazine. [email protected]

Copyright © 2017 DZone, Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or SPONSORSHIP OPPORTUNITIES
transmitted, in any form or by means electronic, mechanical, photocopying, or otherwise, without prior written permission of the publisher.
[email protected]