Get a working version of Mono
Add sources to NuGet.config (For package restore)
Get and compile libuv (Required for the Kestrel server)
So, what does all this mean to the uninitiated?!
Get a working version of Mono
Mono is an open source development platform that allows developers to build cross-platform .NET applications that run on a number of different operating systems such as Linux, Mac, Windows and instruction set architectures including x86, ARM and PowerPC. Since Microsoft started developing ASP.NET 5, they have been working with the Mono team to ensure ASP.NET 5 applications work with the platform.
To install Mono on your Linux machine, you’ll need to run the following shell script.
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF echo "deb http://download.mono-project.com/repo/debian wheezy main" | sudo tee /etc/apt/sources.list.d/mono-xamarin.list sudo apt-get update sudo apt-get install mono-complete
It’s been a while since I’ve done any shell scripting in Linux, so let’s go through it line by line.
The first line runs the command apt-key, which is used to manage the list of keys used by apt to authenticate packages. Apt (“Advanced Package Tool”) manages software package installations, updates and removals on Debian/Linux based systems. The long alphanumeric “3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF” is the public key for the Mono repository, so once we’ve added that key using apt-key we’ll be able to verify that the downloads from the repository are indeed from Mono and are safe to use. More info on apt here.
The sudo command at the start of the line (short for substitute user do or superuser do), allows a user to run a command with the security privileges of the super user.
The second line, beginning with echo, outputs a repository url to the list of sources that apt uses when you call it to update your packages. It does this by piping the url through to the command tee, which writes the string to the console and the specified file. The ‘deb’ part tells apt to download binaries, ‘wheezy’ is the distribution we’ll be tracking and the ‘main’ specifies we only want packages that comply to the DFSG (Debian Free Software Guidlines).
The last two lines download, update and install the packages specified in apt’s sources list. At this point, you might want to go and grab a coffee as depending on your internet connection the installation of Mono could take a while!
Once Mono has been installed, the next step is to install the .NET version manager, or DNVM for short. The DNVM is used to download versions of the .NET Execution Environment (DNX) and manage which version you are currently running. The DNX contains all the necessary code required to bootstrap and run an application, including the compilation system, SDK tools, and the native CLR hosts. Before we start though, we need to install unzip as it’s used by the DNVM.
sudo apt-get install unzip
To install DNVM, we just need to download the script from the ASP.NET 5 GitHub using curl.
curl -sSL https://raw.githubusercontent.com/aspnet/Home/dev/dnvminstall.sh | DNX_BRANCH=dev sh && source ~/.dnx/dnvm/dnvm.sh
Once that’s finished execute the script that’s been saved to ~/.dnx/dnvm/dnvm.sh and you should see the following output.
Running “dnvm list”, will tell us that we currently do not have a .NET Execution Environment (DNX) installed. So let’s go ahead and install the latest stable version, by running ‘dnvm upgrade’.
dnvm list dnvm upgrade
If everything ran smoothly, typing ‘dnvm list’ again will show us the version installed.
dave@ninja:~/.dnx/dnvm$ dnvm list Active Version Runtime Arch OperatingSystem Alias ------ ------- ------- ---- --------------- ----- * 1.0.0-beta6 mono linux/darwin default
We are now setup and ready to build and execute .NET applications on Linux! To test this we are going to create a basic ASP.NET web application, execute it and then access it using a web browser. One of the quickest and easiest ways to do this is to use scaffolding to generate a skeleton web application. One popular scaffolding application is called Yeoman, or yo for short, but as it’s installed and executed using the node.js package manager npm, we’ll need to install that first!
curl -sL https://deb.nodesource.com/setup | sudo bash - sudo apt-get install nodejs sudo npm update -g npm
Once that’s finished, we can install Yeoman (yo) and the ASP.NET 5 web app generator from OmniSharp.
sudo npm install -g yo sudo npm install -g generator-aspnet
Now that’s done we can finally create and test a web application running on Linux. Change directory to your projects folder (or mkdir ~/projects if you don’t have one). Execute the aspnet generator using yo asp:net and it will output a list of sample applications that we can choose to create.
dave@ninja:~/projects$ yo aspnet:app _-----_ | | .--------------------------. |--(o)--| | Welcome to the | `---------´ | marvellous ASP.NET 5 | ( _´U`_ ) | generator! | /___A___ '--------------------------' | ~ | __'.___.'__ ´ ` |° ´ Y ` ? What type of application do you want to create? Empty Application Console Application Web Application ❯ Web Application Basic [without Membership and Authorization] Web API Application Nancy ASP.NET Application Class Library Unit test project
Select the ‘web application basic’, enter a name such as ‘HelloWorld’ and the sample app will be generated! It will also give you instructions on how to start the web app.
Your project is now created, you can use the following commands to get going cd "HelloWorld" dnu restore dnu build (optional, build will also happen when it's run) dnx . run for console projects dnx . kestrel or dnx . web for web projects
Before we get the web app up and running however, we need to do a couple more things else we’re going run into some nasty errors.
Add sources to NuGet.config (for package restore)
The DNX utility, or DNU for short, is responsible for downloading an application’s dependencies which are specified in the project.json. This needs to be run before we run or build our application. DNU uses the repository locations defined in NuGet.config, so we’ll need to make sure some development locations have been added, otherwise some of the packages won’t be found when using the nightly builds of ASP.NET. Use the following command to edit the NuGet.config
Now paste in the following xml and press ctrl-O to output the changes
<?xml version="1.0" encoding="utf-8"?> <configuration> <packageSources> <add key="AspNetVNext" value="https://www.myget.org/F/aspnetvnext/api/v2/" /> <add key="nuget.org" value="https://www.nuget.org/api/v2/" /> </packageSources> <disabledPackageSources /> </configuration>
After that’s done, cd back into the HelloWorld application directory that we created earlier and run dnu restore.
This will ensure all the application’s dependencies have been downloaded for the version of DNX that we are currently running (type ‘dnvm list’ to see that).
I had a painful time when I ran ‘dnu restore’ and kept getting errors such as:
Cannot handle address family xxxx Stacktrace: at <unknown> <0xffffffff> at (wrapper managed-to-native) System.Net.Dns.GetHostByName_internal (string,string&,string&,string&) <0xffffffff> at System.Net.Dns.GetHostByName (string) <0x00047> at System.Net.ServicePoint.get_HostEntry () <0x001ef> at System.Net.WebConnection.Connect (System.Net.HttpWebRequest) <0x001af> at System.Net.WebConnection.InitConnection (object) <0x002f3> at System.Net.WebConnection.<WebConnection>m__0 (object) <0x0001f> at (wrapper runtime-invoke) <Module>.runtime_invoke_void__this___object (object,intptr,intptr,intptr) <0xffffffff>
To fix this I had to disable the Micro Name Service Cache Daemon, unscd on my Ubuntu box. I’m not sure if that’s a wise thing to do but it did solve the issue for me.
sudo service unscd stop
I also had to run dnu restore several times before it completed successfully as I kept getting HTTP request timeouts from nuget.org. However, once it does complete successfully, it will output ‘Restore complete’ to the console.
Get and compile libuv (Required for the Kestrel server)
We’re almost there, honestly! Now that we’ve downloaded all the dependencies for our HelloWorld test web application, we can almost run ‘dnx . kestrel’ to start the web server which will load and host the app. Kestrel is the new ASP.NET development web server and is based on libuv, a multi-platform support library with a focus on asynchronous I/O which is primarily developed for use by Node.js. To build and install libuv, run the following commands.
sudo apt-get install automake libtool curl curl -sSL https://github.com/libuv/libuv/archive/v1.6.1.tar.gz | sudo tar zxfv - -C /usr/local/src cd /usr/local/src/libuv-1.6.1 sudo sh autogen.sh sudo ./configure sudo make sudo make install sudo rm -rf /usr/local/src/libuv-1.6.1 && cd ~/ sudo ldconfig
Start the web server
We’re (finally) done! Let’s start the web server and access our web application!
dnx . kestrel
You should see ‘Started’ output to the console window. Kestrel will run on port 5000 (specified in the hosting.ini file of our sample project), and if you’re running it from a Microsoft Azure VM, you’ll need to open up the endpoint in the Azure portal to access it from another machine.
Once the port has been configured for public access, open up your web browser and type in the address of your VM, specifying port 5000 and you should see the sample web app Yeoman created for us!
And there you have it, ASP.NET 5 running on Linux. Super cool! I’ll be doing a whole set of posts soon covering topics such as converting your ASP.NET apps to version 5 and deploying them to a Linux production environment.