Wednesday, April 24, 2019

Create and Host a Cross-Platform Web Site on ASP.NET Core

This is the second post in a series on .NET Cross-Platform Support. In my first post, I covered how to create, build, and deploy a console command in .NET Core for Windows, Linux, and MacOS. In today's post, I'll cover how to create a web site with ASP.NET Core and deploy it on both Windows and Linux.

If you're going to follow along, you'll need to install the .NET Core SDK. I'm doing my development with .NET Core 2.2 and Visual Studio Code on Windows, but you could just as easily do the same on Linux or MacOS.

The web site we'll create is a simple one-page site that performs conversions between different units of measurement, such as from miles to kilometers.


Creating an ASP.NET MVC Project

We'll use the dotnet new command to create a starter project. I want to use MVC, so we'll request the MVC template.We'll specify the folder and project name convert.

dotnet new mvc -o convert

This creates a folder named convert. Within that folder are our project files along with subfolders.

Coding the Site

Fire up Visual Studio Code and use Open Folder to open the convert folder that was just created.

If you're new to ASP.NET Core, let's take a moment to familiarize ourselves with the project that has been created. Keep in mind this MVC project is only one of many ASP.NET Core project tempaltes
you can use.

Project Structure

In the convert folder, there is Program.cs and Startup.cs. Program.cs contains function Main, which is where execution begins. It creates a WebHost, and references the Startup class.

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Logging;

namespace convert
    public class Program
        public static void Main(string[] args)

        public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>

Startup.cs contains the initialization code for the WebHost. This refactoring of ASP.NET is extremely modular and extensible, and includes a built-in dependency injection system.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.HttpsPolicy;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

namespace convert
    public class Startup
        public Startup(IConfiguration configuration)
            Configuration = configuration;

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
            services.Configure<CookiePolicyOptions>(options =>
                // This lambda determines whether user consent for non-essential cookies is needed for a given request.
                options.CheckConsentNeeded = context => true;
                options.MinimumSameSitePolicy = SameSiteMode.None;


        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
            if (env.IsDevelopment())
                // The default HSTS value is 30 days. You may want to change this for production scenarios, see


            app.UseMvc(routes =>
                    name: "default",
                    template: "{controller=Home}/{action=Index}/{id?}");

Since we're just building a simple demonstration web site, we dont need to make any changes to the code in Program.cs or Startup.cs.

Within the convert folder, we have Controllers, Models, and Views subfolders. These are all conceptually familiar to anyone familiar with the Model-View-Controller pattern. Controllers contains C# controller classes; Models contains C# model classes; and Views contain Razor pages (which are HTML with embedded C# code and Razor directives).

There's also a wwwroot folder, which contains static css, image, and JavaScript files.

Project Starting Point

We can build and run the project to see what we have been given out-of-the-box. In Visual Studio Code, open a new terminal window with Terminal > New Terminal. Run dotnew build to build the prjoect.

In traditional ASP.NET, launching the site locally from Visual Studio would use IIS or IIS Express to host the web site. In ASP.NET Core, all we need is the dotnet run command. Enter dotnet run in the terminal window to host a web server. Click the displayed HTTP or HTTPS link to open the site in a browser. We can see we get a simple Welcome page.

Code the HTML Page

We need to change the HTML in the default page, /Views/Home/index.cshml. We add the following code to the page:
    ViewData["Title"] = "Home Page";

<div class="text-center">
    <h1 class="display-4">Unit Converter</h1>
    <p>Use this page to convert between common units of measurement</a>.</p>

<div> </div>

    <input id="source-value" type="number" value="10" style="font-size: 14px" />
    <select id="source-unit">
        <option value="">-- select source units --</option>
        <option value="ft" selected>Feet (ft)</option>
        <option value="km" selected>Kilometers (km)</option>
        <option value="m">Meters (m)</option>
        <option value="mi">Miles (mi)</option>
    <button id="btn-convert" onclick="convert();">Convert</button> 
    <input id="dest-value" type="number" value="" style="font-size: 14px" readonly=readonly />
    <select id="dest-unit">
        <option value="">-- select destination units --</option>
        <option value="ft" selected>Feet (ft)</option>
        <option value="km">Kilometers (km)</option>
        <option value="m">Meters (m)</option>
        <option value="mi" selected>Miles (mi)</option>

function convert() {
    var value = $('#source-value').val();
    var sourceUnits = $('#source-unit').val();
    var destUnits = $('#dest-unit').val();


    if (sourceUnits==='' || destUnits==='') return;

    if (sourceUnits===destUnits)


    var url = '/home/Convert?value=' + value + '&source=' + sourceUnits + '&dest=' + destUnits;

        url: url,
        method: 'GET',
    }).done(function(data) {
        //$( this ).addClass( "done" );

We can now build the site with dotnet build and run it with dotnet run so that we can test it.

dotnet build
dotnet run

Now we can enter an amount and select source and destination units. Clicking Convert converts the value.

Our site, while simple, could easily be expanded to support many more conversions over time. For our purposes of testing cross-platform compatibility, this is sufficient and we can move on to seeing things work on Linux.

Publishing to Linux

We can generate output for linux with the dotnet publish command, specifying the distribution we wish to target. We'll use Ubuntu 18.04, 64-bit (because that's an AMI available for AWS EC2).

dotnet publish -c Release --self-contained -r ubuntu.18.04-x64

To deploy, we'll need to allocate a Linux web server, for which we'll use NGINX. We'll then deploy our convert site, and finally configure NGINX to serve as a reverse proxy to our ASP.NET Core site.

1. Create EC2 instance

We first create an Ubuntu EC2 instance on AWS. We save the .pem (key) file created with the instance, which will be needed anytime we want to connect to the instance with SSH.

Configure an inbound rule allowing port 80 in the security group for the EC2 instance.

As we allocate the EC2 instance, we save the .pem (key) file, which we'll need for subsequent steps.

2. Connect with SSH

Once the instance is up and running, we connect to it with SSH, specifying our instance URL and the .pem (key) file we created with the instance:

ssh -i "dp-dev.pem"

3. Set up web server

To set up a web server, we use the sudo ("SuperUser do") command to allow port 80 on the firewall.

sudo ufw allow 80/tcp

Next, we install nginx, a popular web server:

sudo apt-get install nginx
sudo service nginx start

Once installation completes, we are able to confirm that we can access the EC2 instance as a web server:

4. Deploy the .NET Core application

Via SSH, create a convert file under /home/ubuntu. Then use a tool such as WinSCP to copy the files from the Ubuntu publish folder to /home/ubuntu/convert:

5. Configure nginx to be a Reverse Proxy for Convert.dll

Following the Microsoft instructions here, we do the following to set up NGINX as a reverse proxy for the NET Core convert site. This simply means NGINX will forward requests to our application.

a. Stop the nginx site

sudo service nginx start

b. Change directory to /etc/nginx/sites-available and replace the file default with the content below (I used Notepad++ and WinSCP for this):

cd /etc/nginx/sites-available

server {
    listen        80;
    server_name *;
    location / {
        proxy_pass         http://localhost:5000;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection keep-alive;
        proxy_set_header   Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;

If you run into permission issues, try uploading your new default file to a path you have write access to, such as where you copied the convert application publish files to. Then, in cd /etc/nginx/sites-available, you can use sudo cp to copy the file:

cd /etc/nginx/sites-available
sudo cp /home/ubunto/convert/default .

c. Start the nginx service

sudo service nginx start

6. Start the Convert Site

From /home/ubuntu/convert, use the dotnet command to run convert.dll to start the Convert site

cd /home/ubuntu/convert dotnet convert.dll

7. Try to access the site in a browser:

Our ASP.NET Core Convert site is now running on Ubuntu Linux, with NGINX serving as a reverse proxy. If you've never worked with Linux as a web server before, getting to this step with a .NET web site is a great moment.


In this post I've shared what my first-time experience publishing an ASP.NET Core web site to Linux. There were plenty of unknowns working with an operating system I had little experience with, but with a little persistence I got there. .NET Core is well done, and ASP.NET Core is no exception. It's very empowering to realize how broader your .NET Skills can now reach with .NET Core.

No comments: