Monthly Archives: September 2016

Creating and hosting ASP.NET Core application on Linux — Nothing Third-Party

Introduction and Background

It has been a while since I wanted to write something about ASP.NET Core hosting stuff, and Kestrel was something that was interesting from my own perspective. Previously I have written a bunch of stuff to cover up the basics of ASP.NET Core programming and in this one I will guide you on hosting the ASP.NET Core application natively, using the .NET Core libraries that you download while installation process. Secondly, it has been a while since I have had written anything at all and I might have forgotten the interests of my readers so excuse me if I miss out a few things.

image_60140ec0-ce46-4dbf-a14f-4210eab7f42c
Figure 1: Image captured from Scott Hanselman’s blog.

There is a lot of stuff to share in this post today, so stay tuned and hold your breath basically. I will be covering the following steps in this article:

  1. Installation of the latest version of .NET Core on Linux environment
    • If you already have a .NET Core framework installed, upgrade your system if that doesn’t support ASP.NET programming as of now.
    • In the previous versions, web development wasn’t support in .NET Core for Linux operating systems. In the recent versions, it has been added to the recent versions now so that is why I insist that before continuing you at least install the latest version of .NET Core.
  2. Setup an ASP.NET Web Application in your Linux environment.
    • I will guide you through many stages, such as development, editing, maintenance and using an IDE for all of these things.
    • I will walk you through many different areas (not the ASP.NET Area!) in ASP.NET web application’s file hierarchy, plus I will tell you what is back and what is about to change (or subject to change in the hierarchy).
  3. Build and run the project
    • In this section, I will guide you through a few of the tips that would deem helpful to you.
    • Before running, I will give you an overview of Kestrel — web server for ASP.NET 5.
    • I will then move onwards to using the website, which has the same feel as it had in Windows operating system, while developing ASP.NET web applications.
    • Tip: I will then give you a tip, by default, application is uploaded at 5000 port, which you would require to change in many cases, I will show you how to change the port of the web application’s hosting service.
  4. Finally, I will head over to final words that I put at the end of every post that I write on any of the platform that I have to write about.

Installing or upgrading .NET Core

I wrote an article that covered how you can start using .NET Core on Linux environments, you can read it here. That article was written entirely, to give you a concept of the .NET Core architecture, and a few commands that you can use to do most of the stuff. The only difference between the older article and this section of the post is that this would just contain a later version of .NET Core to be installed on the system. Whereas in the previous one you had to install the older one.

Try the following,

sudo apt-get update && dist-upgrade

If that doesn’t work, or it doesn’t show the updates, head over to the main website for .NET Core, and install the latest version from there.

Creating a new web application

Previously, .NET Core only supported creating libraries or console applications. At the moment, it supports ASP.NET web application development too, it supports the templates for ASP.NET too, at the moment just a simple ASP.NET MVC oriented web application is created, and I don’t think there is any need for other templates like Web API, SignalR, single page applications etc. I believe that is complete at the moment.

To create a new web application, create the new project in .NET Core and pass the type parameter as a web application, which would guide .NET Core (dotnet) to create a new application with the template of web application.

screenshot-3007
Figure 2: Creation of a new .NET Core project using web template. 

As you can see in the command above, we are passing a type (-t parameter) to the command to create a new web templated application. The content is as following,

screenshot-3008
Figure 3: ASP.NET Web application files and directories in .NET Core. 

The project looks similar to what we have on Windows environment. Just a difference of one thing: It includes, web.config as well as project.json file. Remember that Microsoft is mostly moving back to MSBuild and of course a few of the hosting modules are based on IIS servers so that is why web.config file is available in the project. However, the project at the moment uses project.json file for project-level configuration and (as we have heard mostly during these days) these would be migrated to MSBuild way of managing the project and other related stuff.

Editing and updating the web application

Microsoft has been pushing the limits since a while, of course on Linux you already had a few of the best tools for development but Visual Studio Code is still a better tool. In my previous posts, I said that I don’t like it enough — I still don’t like it very much, it needs work! — but it is better than many tools and IDEs available for C# or .NET-related programming. Since in this post I said that I won’t be talking about anything third-party, so Visual Studio Code is the tool that I am going to suggest, support and use in this case.

You can install Visual Studio Code from their official website, note one thing, the Debian packages take a little longer for installation, so if you also don’t like to wait too much like me then I would recommend that you download the archive packages and install the IDE from them. There is no installation required at all, you just move the extracted files to a location where you want to store it. FInally, you create a symbolic link to your executable, which can be done like this,

sudo ls -s /home/username/Downloads/VSCode-linux-x64/code /usr/local/bin/code

This would create link and you can use Visual Studio Code IDE just by executing this “code” command anywhere in the directory (using the terminal), it would then load the directory itself as a project in the IDE which you can then use to update your application’s source code and other stuff that you want to.

Tip: Install the C# extension from market place for a greater experience.

Once this is done, head over to the directory where you create the project. Execute the following command,

code .

This would trigger Visual Studio Code to load your directory as the project in the IDE. This is how my environment looks like,

screenshot-3009
Figure 4: Visual Studio Code showing the default ASP.NET directory as a project.

The rest is history — I mean the rest is the similar effect, and feeling that you can get on Windows environment. First of all, when you work this way and follow my lead you will get the following errors in the IDE window.

screenshot-3010
Figure 5: Error messages in Visual Studio Code.

We will fix them in a moment. But at first, understand that these are meant to act like this. If you have had ever programmed in .NET Core, you must have known that before anything else you need to restore the NuGet packages for your project before even building the project. Visual Studio Code uses the same IntelliSense and tries to tell you what is going wrong. In doing so, it requires the binaries which are not available so you are shown that last error message. Above two are optional, middle one is a bit optional-required.

Build and run the project

Until this point we have had created the project. But now we need to restore the dependencies for our project which are going to be used by the .NET Core to actually execute our code. By default a lock file is not generated, so we need to create a new file and after that we would be able to build the project.

Execute the following command,

dotnet restore

After this, .NET Core would automatically generate the lock file and building process can be easily triggered.

screenshot-3012
Figure 6: Project.lock.json file created after restoring the project.

We can continue to building the project. I want you to pay attention to this point now. See what happens.

screenshot-3013
Figure 7: Build and run process of ASP.NET web application on .NET Core.

Now notice a few things in the above terminal window. First of all, notice that it keeps logging everything. Secondly, notice that it has a port “5000” appended. We didn’t train it to use that at all, and that also didn’t come from Program.cs file either (you can see that file!). But before I dig any deeper in explanation of how to change that, I want you to praise KestrelThe web server of ASP.NET 5. Kestrel is the implementation of libuv async I/O library that helps hosting the ASP.NET applications in a cross-platform environment. The documentation for kestrel and the reference documentation is also available, and you can get started reading most of the documentation about Kestrel, on the namespace Microsoft.AspNetCore.Server.Kestrel at the ASP.NET Core reference documentation website.

This is the interesting part because ASP.NET Core can run even on a minimal HTTP listener that can act as a web server. Kestrel is a new web server, it isn’t a full feature web server but adapts as community needs updates. it supports HTTP/1 only as of now but would support other features in the coming days. But remember, pushing every single feature and module in one server would actually kill the major purpose of using the .NET Core itself. .NET Core isn’t developed to push everything on the stack, but instead it is developed to use only the modules and features that are required.  Yes, if you want to add a feature you can update the code and build the service yourself. It is open sourced on GitHub.

Changing the port number of application

In many cases, you might want to change the port number where your server listens or you may also want to make this server the default server for all of your HTTP based communication on the network. In such cases, you must be having a special port number assigned (80-for default).

For that, head over to your Program.cs file, that is the main program file (main function of your project), and that is responsible for creating a hosting wrapper for your web application in ASP.NET Core environment. The current content for this object is,

screenshot-3015
Figure 8: Source code for the Program.cs file.

In that chain of “Use” functions, we just need to add one more function call to use a special URL. The function of “UseUrls(“”)” would allow us to update the URLs that are to be used for this web application. So I am just going to use that function here so that it would let us simply select which URL (and port) to use.

screenshot-3017
FIgure 9: URLs being managed.

Now, if you try to run the application you will run into the following problem in Linux-based system.

screenshot-3019
Figure 10: Unable to bind to the URL given, error message.

That is pretty much simple — it doesn’t have permission to do the trick. So what on Linux systems is done is that it simply is performed using the superuser credentials and account.

sudo dotnet run

It would prompt you for your password, enter your password and this time application would run on the localhost:80. In the cases where you have to upload the website to the servers, Azure App Services etc. In these cases, you are requires to have the application running under the server that acts as the default server, so in those cases you must handle the default TCP port for HTTP communication for the requests. Otherwise, you might require to work at the backends of NGINX or Apache servers etc. But that is a different story.

screenshot-3020
Figure 11: Web server running at port 80.

Now that our server is running, we can now go to a web browser to test it out. I am going to use Firefox, you can use any web browser (even a terminal-based).

screenshot-3021
Figure 12: ASP.NET Core web application being rendered in Firefox, running in Linux using Kestrel web server.

As you can see, the web application runs smoothly. Plus, it also logs any event that takes place. The terminal keeps a record of that, it can also allow you to actually transfer the output from main terminal’s output to a file stream to store everything. But that is a topic for a different post.

screenshot-3022
Figure 13: ASP.NET web application’s log in terminal window.

As requests come and responses are generated, this window will have more and more content.

Final words

I have wanted since a while, to write my own next web application for my own blog and stuff, in ASP.NET Core. At the moment, the framework is “almost” ready for production, but just not yet. Maybe in a couple of next builds it will be ready. There are many things that they need to look into. For example, the web server needs to be more agile — the features needs to be provided. That is not it, VIsual Studio Code must be fully integrated with ASP.NET Core tooling. At the moment it just allows us to edit the code, then we have to go back to the terminal to do the rest. It should provide us with the ability to do that.

To Microsoft’s team related to .NET Core: Why isn’t .NET Core being published on Linux? I am pretty much sure the framework is fully function, despite the bugs. But there are bugs in the main .NET framework too, there are some minor issues every here and there. My major concern here is to be able to do, “sudo apt-get install dotnet”. I can’t remember the longer version names.

To readers: If you are willing to use ASP.NET Core for your production applications, wait for a while. Althought ASP.NET Core is a better solution than many other solutions available. But my own recommendation is to stick to ASP.NET 4.6 as of now because that is more stable version as compared to this one.

A quick startup using .NET Core on Linux

I know you may be thinking… This post is another rhetoric post by this guy, yes it is. 🙂 .NET Core is another product that I like, the first one being, .NET framework itself. It was last year when .NET Core got started and Microsoft said they are going to release the source code as a part of their open source environment and love. By following the open source project environment and ethics, Microsoft has been working very hard in bringing global developers toward their environments, platforms and services. For example, .NET framework works on Windows, C# language is used to build Windows Store applications, C# is also the primary language in Microsoft’s web application development framework, ASP.NET and much more. The online cloud service of Microsoft is also programmed in C#; primarily. These things are interrelated to each other. Thus, when Microsoft brings all of this as an open source project, things start to get a lot better!

Everyone knows about the background of .NET Core, if you don’t know, I recommend that you read the blog post on Microsoft, Introducing .NET Core. The(ir) basic idea was to provide a framework that would work with any platform, any application type and any framework to be targeted.

Introduction and Background

In this quick post, I will walk you through getting started with .NET Core, installing it on a Linux machine and I will also give my views as to why install .NET Core on a Linux machine instead of Windows machine, I will then walk you through different steps of .NET Core programming and how you can use terminal based environment to perform multiple tasks. But first things first.

I am sure you have heard of .NET Core and other of the cool stuff that Microsoft has been releasing these years, From all of these services the ones that I like are:

  1. C# 6
    • In my own opinion, I think the language looks cleaner now. These sugar-coated features make the language easier to write too. If you haven’t yet read, please read my previous blog post at, Experimenting with C# 6’s new features.
  2. .NET Core
    • Of course, who wouldn’t love to use .NET on other platforms.
  3. Xamarin acquisition
    • I’m going to try this one out tonight. Fingers crossed.
  4. Rest are all just “usual” stuff around.

In this post I am going to talk about .NET Core on Linux because I have already talked about the C# stuff.

Screenshot (898)
Figure 1: .NET Core is a cross-platform programming framework by Microsoft.

Why Linux for .NET Core?

Before I dive any deeper, as I had said, I will give you a few of my considerations for using .NET Core on Linux and not on Windows (yet!) and they are as following. You don’t have to take them seriously or to always consider them, they are just my views and my opinions, you are free to have your own.

1. .NET Core is not yet complete

It would take a while before .NET gets released as a public stable version. Until then, using this bleeding edge technology on your own machines won’t be a good idea and someday sooner you will consider removing the binaries. In such cases, it is always better to use it in the virtual machine somewhere. I have set up a few Linux (Ubuntu-based) virtual machines for my development purposes, and I recommend that you go the same.

  1. Install VirtualBox (or any other virtualization software that you prefer; I like VirtualBox for its simplicity).
  2. Set up an Ubuntu environment.
    • Remember to use Ubuntu 14.04. Later ones are not yet supported yet.
  3. Install the .NET Core on that machine.

If something goes wrong. You can easily revert back where you want to. If the code plays dirty, you don’t have to worry about your data, or your machine at all.

2. Everything is command-line

Windows OS is not your OS if you like command-line interfaces. I am waiting for the BASH language to be introduced in Windows as in Ubuntu, until then, I am not going to use anything that requires a command-line interface to be used on my Windows environment. In Linux, however, everything almost has a command-line interface and since the .NET Core is a command-based program by Microsoft that is why I have enjoyed using it on Linux as compared to Windows.

Besides, on command-line interface, creating, building and running a .NET Core project is as simple as 1… 2… 3. You’ll see how, in the sections below. 🙂

3. I don’t use Mac

Besides these points, the only valid point left is then why shouldn’t we use Mac OS for .NET Core is because I don’t use it. You are free to use Mac OS for .NET Core development too. .NET Core does support it, its just that I don’t support that development environment. 😀

Installation of .NET Core

Although it is intended that soon, the command would be as simple as:

$ sudo apt-get install dotnet

Same command is used on Mac OS X and other operating systems other than Ubuntu and Debian derivatives. But until the .NET Core is in development process that is not going to happen. Until then, there are other steps that you can perform to install the .NET Core on your own machine. I’d like to skip this part and let Microsoft give you the steps to install the framework.

Installation procedure of .NET Core on multiple platforms.

After this step, do remember to make sure that the platform has been installed successfully. In almost any environment, you can run the following command to get the success message.

> dotnet --help

If .NET is installed, it would simply show the version and other help material on the screen. Otherwise, you may want to make sure that that procedure did not incur any problems during the installation of the packages. Before I get started, I want to show you the help material provided with “dotnet” command,

afzaal@afzaal-VirtualBox:~/Projects/Sample$ dotnet --help
.NET Command Line Tools (1.0.0-preview1-002702)
Usage: dotnet [common-options] [command] [arguments]

Arguments:
 [command]      The command to execute
 [arguments]    Arguments to pass to the command

Common Options (passed before the command):
 -v|--verbose   Enable verbose output
 --version      Display .NET CLI Version Number
 --info         Display .NET CLI Info

Common Commands:
 new           Initialize a basic .NET project
 restore       Restore dependencies specified in the .NET project
 build         Builds a .NET project
 publish       Publishes a .NET project for deployment (including the runtime)
 run           Compiles and immediately executes a .NET project
 test          Runs unit tests using the test runner specified in the project
 pack          Creates a NuGet package

So, you get the point that we are going to look deeper into the commands that dotnet provides us with.

  1. Creating a package
  2. Restoring the package
  3. Running the package
    • Build and Run both work, run would execute, build would just build the project. That was easy.
  4. Packaging the package

I will slice the stuff down to make it even more clearer and simpler to understand. One thing that you may have figured is that the option to compile the project natively is not provided as an explicit command in this set of options. As far as I can think is that this support has been removed until further notice. Until then, you need to pass a framework type to compile and build against.

Using .NET Core on Linux

Although the procedure on both of the environments is similar and alike. I am going to show you the procedure in Ubuntu. Plus, I will be explaining the purpose of these commands and multiple options that .NET provides you with. I don’t want you feel lonely here, because most of the paragraphs here would be for Microsoft team working on .NET project, so I would be providing a few suggestions for the team too. But, don’t worry, I’ll make sure the content seems to be and remain on-topic.

1. Creating a new project

I agree that the framework development is not yet near releasing and so I think I should consider passing on my own suggestions for the project too. At the moment, .NET Core supports creating a new project in the directory and uses the name of the directory as the default name (if at all required). Beginners in .NET Core are only aware of the commands that come right after the “dotnet”. However, there are other parameters that collect a few more parameters and optional values such as:

  1. Type of project.
    • Executable
      • At the moment, .NET only generates DLL files as output. Console is the default.
    • Dynamic-link library
  2. Language to be used for programming.

To create a new project, at the moment you just have to execute the following command:

$ dotnet new

In my own opinion, if you are just learning, this is enough for you. However, if you execute the following command you will get an idea of how you can modify the way project is being created and how it can be used to modify the project itself, including the programming language being used.

$ dotnet new --help
.NET Initializer

Usage: dotnet new [options]

Options:
 -h|--help Show help information
 -l|--lang <LANGUAGE> Language of project [C#|F#]
 -t|--type <TYPE> Type of project

Options are optional. However, you can pass those values if you want to create a project with a different programming language such as F#. You can also change the type, currently however, Console applications are only supported.

I already had a directory set up for my sample testing,

Screenshot (899)
Figure 2: Sample directory open. 

So, I just created the project here. I didn’t mess around with anything at all, you can see that the .NET itself creates the files.

Screenshot (900)
Figure 3: Creating the project in the same directory where we were.

Excuse the fact that I created an F# project. I did that so that I can show that I can pass the language to be used in the project too. I removed that, and instead created a C# program-based project. This is a minimal Console application.

In .NET Core applications, every project contains:

  1. A program’s source code.
    • If you were to create an F# project. Then the program would be written in F# language and in case of default settings. The program is a C# language program.
  2. A project.json file.
    • This file contains the settings for the project and dependencies that are to be maintained in the project for building the project.

However, once you are going to run you need to build the project and that is what we are going to do in the next steps.

2. Restoring the project

We didn’t delete the project. This simply means that the project needs to be restored and the dependencies need to be resolved before we can actually build to run the project. This can be done using the following command,

$ dotnet restore

Note: Make sure you are in the working directory where the project was created.

This command does the job of restoring the packages. If you try to build the project before restoring the dependencies, you are going to get the error message of:

Project {name} does not have a lock file.

.NET framework uses the lock file to look for the dependencies that a project requires and then starts the building and compilation process. Which means, this file is required before your project can be executed to ensure “it can execute”.

After this command gets executed, you will get another file in the project directory.

Screenshot (902)
Figure 4: Project.lock.json file is now available in the project directory.

And so finally, you can continue to building the project and to running it on your own machine with the default settings and setup.

3. Building the project

As I have already mentioned above, the native compilation support has been removed from the toolchain and I think Ubuntu developers may have to wait for a while and this may only be supported on Windows environment until then. However, we can somehow still execute the project as we would and we can perform other options too, such as publishing and NuGet package creation.

You can build a project using the following command,

$ dotnet build

Remember that you need to have restored the project once. Build command would do the following things for you:

  1. It would build the project for you.
  2. It would create the output directories.
    • However, as I am going to talk about this later, you can change the directories where the outputs are saved.
  3. It would prompt if there are any errors while building the project.

We have seen the way previous commands worked, so let’s slice this one into bits too. This command, too, supports manipulation. It provides you with optional flags such as:

  1. Framework to target.
  2. Directory to use for output binaries.
  3. Runtime to use.
  4. Configuration etc.

This way, you can automate the process of building by passing the parameters to the dotnet script.

4. Deploying the project

Instead of using the term running the project, I think it would be better if I could say deploying the project. One way or the other, running project is also deployed on the machine before it can run. First of all, the project I would show to be running, later I will show how to create NuGet packages.

To run the project, once you have built the project or not, you can just execute the following command:

$ dotnet run

This command also builds the project if the project is not yet built. Now, if I execute that command on my directory where the project resides, the output is something like this on my Ubuntu,

Screenshot (904)
Figure 5: Project output in terminal.

As seen, the project works and displays the message of, “Hello World!” on screen in terminal. This is a console project and a simple project with a console output command in C# only. That is why the program works this way.

Creating NuGet packages

Besides this, I would like to share how you can create the NuGet package from this project using the terminal. NuGet packages have been in the scene since a very long time and they were previously very easy to create in Visual Studio environment. Process is even simpler in this framework of programming. You just have to execute the following command:

$ dotnet pack

This command packs the project in a NuGet package. I would like to show you the output that it generates so that you can understand how it is doing everything.

afzaal@afzaal-VirtualBox:~/Projects/Sample$ dotnet pack
Project Sample (.NETCoreApp,Version=v1.0) was previously compiled. 
Skipping compilation.
Producing nuget package "Sample.1.0.0" for Sample
Sample -> /home/afzaal/Projects/Sample/bin/Debug/Sample.1.0.0.nupkg
Producing nuget package "Sample.1.0.0.symbols" for Sample
Sample -> /home/afzaal/Projects/Sample/bin/Debug/Sample.1.0.0.symbols.nupkg

It builds the project first, if the project was built then it skips that process. Once that has been done it create a new package and simply generates the file that can be published on the galleries. NuGet package management command allows you to perform some other functions too, such as updating the version number itself, it also allows you to specify framework etc. For more, have a look at the help output for this command,

afzaal@afzaal-VirtualBox:~/Projects/Sample$ dotnet pack --help
.NET Packager

Usage: dotnet pack [arguments] [options]

Arguments:
 <PROJECT> The project to compile, defaults to the current directory. 
 Can be a path to a project.json or a project directory

Options:
 -h|--help Show help information
 -o|--output <OUTPUT_DIR> Directory in which to place outputs
 --no-build Do not build project before packing
 -b|--build-base-path <OUTPUT_DIR> Directory in which to place temporary build outputs
 -c|--configuration <CONFIGURATION> Configuration under which to build
 --version-suffix <VERSION_SUFFIX> Defines what `*` should be replaced with in version 
  field in project.json

See the final one, where it shows the version suffix. It can be used to update the version based on the build version and so on. There is also a setting, which allows you modify the way building process updates the version count. This is a widely used method for changing the version number based on the build that produced the binary outputs.

The NuGet package file was saved in the default output directory.

Screenshot (905)
Figure 6: NuGet package in the default output directory.

Rest is easy, you can just upload the package from here to the NuGet galleries.

Final words

Finally, I was thinking I should publish a minimal ebook about this guide. The content was getting longer and longer and I was getting tired and tired, however since this gave me an idea about many things I think I can write a comparison of .NET Core on Windows and Linux and I think I have enough time to do that.

Secondly, there are few suggestions for end users that I want to make.

  1. Do not use .NET Core for commercial software. It is going to change sooner,
  2. .NET Core is a bleeding edge technology and well, since there is no documentation, you are going to waste a lot of time in learning and asking questions. That is why, if you are considering to learn .NET framework, then learn the .NET framework and not .NET Core. .NET framework has a great amount of good resources, articles, tips and tutorials.
  3. If you want cross-platform features and great support like .NET framework, my recommendation is Mono Project over .NET Core maybe because it is yet not mature.

I have a few feedback words on the framework itself.

  1. It is going great. Period.
  2. Since this is a cross-platform framework, features must not be available Windows-only such as that “dotnet compile –native” one. They must be made available to every platform.

At last, the framework is a great one to write programs for. I enjoyed programming for .NET Core because it doesn’t require much effort. Plus, the benefit of multiple programming languages is still there, Besides, Visual Studio Code is also a great IDE to be used and the C# extension makes it even better. I will be writing a lot about these features these days since I am free from all of the academics stuff these days. 🙂

See you in the next post.