Note: The screenshots may contain out of date version numbers (etc) but the text commands should be accurate and up to date i.e. please refer to the text commands and use the screenshots as rough guide to correctness only.
.NET Core is supported on the following distributions:
| OS | Version | Architectures |
|---|---|---|
| Red Hat Enterprise Linux | 7.2 | x64 |
| Fedora | 23 | x64 |
| Debian | 8.2 | x64 |
| Ubuntu | 14.04 LTS, 16.04 LTS | x64 |
| Linux Mint | 17 | x64 |
| openSUSE | 13.2 | x64 |
| Centos | 7.1 | x64 |
| Oracle Linux | 7.1 | x64 |
| Mac OS X | 10.11, 10.12 | x64 |
| Windows Client | 7 SP1 - 10 | x64, x86 |
| Windows Server | 2008 R2 SP1 - 2016 | x64, x86 |
It also works fine on Ubuntu 16.10 x64 which is the distribution/version I have used while preparing this workshop.
If you are using one of the distributions above (that is not Ubuntu 16.10 x64) you should go here and follow your distribution's specfic instructions, then skip forward a little way to the section entitled Smoke Testing .NET Core.
If you are not using one of the above distributions you have two options:
I have pre-prepared an Ubuntu 16.10 x64 VM for you for just this situation.
You can now install the latest VirtualBox 5.1.12 and VirtualBox Extension Pack 5.1.2 (available on my USB sticks) and then import the pre-baked vm LCA2017_Before.ova (also available on my USB sticks) now and then continue on with the workshop, or...
Note: Please ask an I will supply the password for the VM.
You can compile from source though your milage may vary. If you get stuck you can always fall back to importing the VM.
Note: The following are fast instructions on how to install .NET Core on Ubuntu Linux 16.10 x64. For more information see here.
First let's check we're completely up to date.
sudo apt-get update && sudo apt-get upgrade
Note: If you see any errors here please resolve them before continuing.
Now we're up to date let's add the .NET Core APT feed.
sudo sh -c 'echo "deb [arch=amd64] https://apt-mo.trafficmanager.net/repos/dotnet-release/ yakkety main" \
> /etc/apt/sources.list.d/dotnetdev.list'
sudo apt-key adv --keyserver apt-mo.trafficmanager.net --recv-keys 417A0893
sudo apt-get update
Next let's see what .NET Core versions are now available.
apt-cache search dotnet
Now we can install the newest version of .NET Core SDK.
sudo apt-get install dotnet-dev-1.0.0-preview2-1-003177
You can find out more information on versions of the .NET CLI here.
Let's check the version of dotnet we now have available.
dotnet --version
Excellent! We now have version 1.0.0-preview2-1-003177 of the .NET Core SDK.
Let's create a new .NET Core Project using the new project scaffolding command.
mkdir DotNetCoreTestApp
cd DotNetCoreTestApp
dotnet new
To run our new DotNetCoreTestApp we'll need to restore our NuGet packages first.
dotnet restore
All that is left now is to execute our new .NET Core Application.
dotnet run
Let's confirm it's not all "an illusion Michael".
cat Program.cs
Superb! The world of .NET Core on Ubuntu Linux is now open to you...
As you have already seen .NET Core is driven by the dotnet Core CLI.
Let's take a look at the features provided by dotnet.
dotnet --help
We have seen dotnet new, dotnet restore and dotnet run already.
The dotnet new command scaffolds the simplest .NET Core application possible (the Hello, world!) which is made up of two files: Program.cs and project.json.
Program.cs contains the public static void Main(string[] args) that is the entry point for your application. It also writes the Hello, world! to the console.
project.json is your project's configuration file. It (amongst other things) defines the dependencies of your application. You can see that your application is targetting version 1.1 of the .NET Core platform and runtime via the netcoreapp1.1 framework dependency.
The dotnet restore command's job is to restore your dependencies. In the current case this is just Microsoft.NETCore.App which is a "meta package" for the set of .NET API's that are included in the default .NET Core application model. As you expand the scope of your application you will add more dependencies in this location.
.NET Core dependencies / packages are restored from http://www.nuget.org by default. You can also opt-in to restore packages from other locations (e.g. internal package sources).
It seems self-evident that dotnet build will build (compile, etc) your .NET Core application. You can learn more about the .NET Core build process here. Take some time to read more about the .NET Core build process now.
The dotnet publish command copies your application and all its dependencies into a folder preparing it for publishing. Importantly it produces one of the following three types of outputs:
-
A portable application: An application in .NET's Common Intermediate Language (CIL) which allows the application to be executed anywhere there is a compatible .NET Runtime. In our current situation (on GNU/Linux, with .NET Core)this runtime is the CoreCLR (the .NET Core Common Language Runtime) though there are other compatible (legacy perhaps) runtimes that can be used.
-
A portable application with native dependencies: the same as the above with an extra platform folder containing the native dependency(s). This is important as a single application bundle can be delivered to multiple platforms where there are some native dependencies required.
-
A self-contained application: the same as either of the above, but we also bundle the runtime(s) required to execute the application. This is great as the application then contains everything required for execution on all target platforms, rather than an expectation/supposition that the target operating system will have the precise version of the runtime required for our application. This is a relatively new concept for .NET.
Note: All of the above application types still require the dotnet run command to bootstrap their execution.
Unsurprisingly the [dotnet run] command(https://docs.microsoft.com/en-us/dotnet/articles/core/tools/dotnet-run) will execute your application. But it actually does more than that. It allows you to have a single command to prepare and execute your application. It will detect if you do not have an up-to-date build of your application and then execute dotnet build. It will also detect if you have missing dependencies and execute dotnet restore etc.
Take some time to read more about dotnet build now.
Note: In the future .NET Core will support "native compilation" (they call this .NET Native which is an ahead-of-time compiler) where a native binary can be produced per-target-platform. This process is currently under active development. My understanding is that this will produce an ELF binary.
The [dotnet test] command(https://docs.microsoft.com/en-us/dotnet/articles/core/tools/dotnet-test) runs your unit tests using the configured test runner. We will learn more about unit testing in the next section.
The dotnet pack command packages your application as a NuGet Package. The NuGet Package is the package format for .NET applications, libraries, frameworks, etc. Like many other packaging formats it's basically just a zip file and a manifest file with a .nupkg extension.
The NuGet Package will become relevent once you want to distribute your application, library, framework, etc.
That's it for dotnet CLI commands.
Prerequisites: If you would like to check out Visual Studio Code (VS Code) please go here and install it for your operating system / distribution of choice. It's also 100% OK to continue on with your text editor of choice.
Open VS Code (or another text editor of your choice) and edit project.json updating the "dependencies": {} section so it looks like the following. This will set the test libary to xUnit.net and include the bridge between dotnet test and xUnit.net.
},
"dependencies": {
"xunit":"2.2.0-beta4-build3444",
"dotnet-test-xunit": "2.2.0-preview2-build1029"
},Also, you will need to update the top of your project.json to tell dotnet to use the xUnit.net test runner.
{
"version": "1.0.0-*",
"testRunner": "xunit",
"buildOptions": {Your complete project.json should look as follows.
{
"version": "1.0.0-*",
"testRunner": "xunit",
"buildOptions": {
"debugType": "portable",
"emitEntryPoint": true
},
"dependencies": {
"xunit":"2.2.0-beta4-build3444",
"dotnet-test-xunit": "2.2.0-preview2-build1029"
},
"frameworks": {
"netcoreapp1.1": {
"dependencies": {
"Microsoft.NETCore.App": {
"type": "platform",
"version": "1.1.0"
}
},
"imports": "dnxcore50"
}
}
}Note: If you are trying out VS Code you may be prompted to install the C# Language Extension. If so go ahead and click on "show recommendations" and "install" to do that now.
Also: If you're using VS Code you will see the following prompts after restarting the editor. Go ahead and select "yes" to install the required assets for building and debugging via VS Code.
And: Then select "restore" in VS Code or run dotnet restore from the command line to restore (download) your new dependencies. You should then see output similar to the following.
Now open Program.cs and import (use / using) the xUnit.net library as shown below. This will allow our code to use the Classes and Methods (etc) provided by xUnit.net.
using System;
using Xunit;
namespace ConsoleApplication
{Next we'll refactor our existing terminal application as shown below. This will simplify the process of testing our method HelloWorld() in the SystemUnderTest class.
public class Program
{
public static void Main(string[] args)
{
var sut = new SystemUnderTest();
var hello = sut.HelloWorld();
Console.WriteLine(hello);
}
}
public class SystemUnderTest
{
public string HelloWorld()
{
return "Hello World!";
}
}Lastly we will write our unit test. Add the following unit test TestClass at the bottom of Program.cs just before the final }.
public class TestClass
{
[Fact]
public void TestMethod()
{
var sut = new SystemUnderTest();
Assert.Equal("Hello World!", sut.HelloWorld());
}
}Your complete Program.cs should look as follows.
using System;
using Xunit;
namespace ConsoleApplication
{
public class Program
{
public static void Main(string[] args)
{
var sut = new SystemUnderTest();
var hello = sut.HelloWorld();
Console.WriteLine(hello);
}
}
public class SystemUnderTest
{
public string HelloWorld()
{
return "Hello World!";
}
}
public class TestClass
{
[Fact]
public void TestMethod()
{
var sut = new SystemUnderTest();
Assert.Equal("Hello World!", sut.HelloWorld());
}
}
}Running your new unit test is as simple as follows.
dotnet restore
dotnet build
dotnet run
dotnet test
Which should produce the following output.
If you look closely you will see that your test has passed.
=== TEST EXECUTION SUMMARY ===
DotNetCoreTestApp Total: 1, Errors: 0, Failed: 0, Skipped: 0, Time: 0.134s
SUMMARY: Total: 1 targets, Passed: 1, Failed: 0.
Awesome! Now you know how to unit test your .NET Core project.
Feel free to explore .NET Core and/or build a new .NET Core application.
The .NET Core Concepts will be useful to you.
Excellent! You have said hello to the world of .NET Core.
Next continue with 4. "Hello, world!" ASP.NET Core.