Sunday, August 9, 2020

Containerizing a .net microservice

Welcome visitor! Thank you for stopping by. This is the first blog of mine and I hope you like it. I am really excited about it. Please bear with me and I promise to get better every time.

In this article, you are going to see a complete tutorial on how can we can containerize a .net microservice. I will go step by step so that you can follow along. The following steps are covered:


Creating an Core 3.1 microservice.

Containerizing the microservice using Docker

Push it to Docker Hub.

Install docker on AWS EC2 or Azure Virtual Machine (I will be using AWS EC2 instance here).

Pull the image from Docker Hub and run

Test the service.


1. .Net core SDK (3.1)

    Link to install:

2. Visual Studio community edition or VS Code. I will be using VS Code.

    Link to install Visual Studio:

    Link to install:

3. Postman

   Link to install:

4. Docker for desktop (Windows or Mac)

    Link to install: 

5. Docker hub - Docker Hub is the world's largest library and community for container images. 

    You will need to create a free account.

    Link to install:

6. AWS free tier account / or Azure free account.

    Link to create free AWS account:

    Link to create a free AZURE account:

Once all the pre-requisites are installed, let's start working.

Creating an Core 3.0 Web API

First lets quickly create a simple .net application

Go to PowerShell or command prompt and run the command below to create a service

The dotnet command creates a new application of type webApi  (that's a REST API endpoint).

      1. The -o parameter creates a directory named sampleMicroservice where your app is stored.

    2. The --no-https flag creates an app that will run without an HTTPS certificate, to keep things simple for deployment.

Next type these commands:

The cd sampleMicroservice command puts you into the newly created app directory.

The code . commands opens the sample application in the VS code.

If you see the notification prompt as in the image, click on Yes. This is a prompt to add few files that VS code needs to build and run the project from VS code. 

So this creates a simple application with WeatherForecastController with only GET method.

To test your sample application before containerizing run the below commands:

Test your microservice in Postman using endpoint http://localhost:5000/weatherforecast.

Containerizing the microservice using Docker

Now, let's containerize the microservice. We will create a DockerFile based on our above .net microservice.

Let's understand a bit about docker before starting.

Docker is a containerization platform, meaning that it enables you to package your applications into images and run them as “containers” on any a platform that can run Docker.

It all starts with a Dockerfile. A Dockerfile is a file that you create which in turn produces a Docker image when you build it.

In short, Dockerfile describes the build process for the image and contains all the commands necessary to build the image and run the application.

Running the Docker image creates a Docker Container.

Creating a docker file

We will use Docker extension to create a docker file if you do not have an extension already installed go to View -> Command Pallete under VS Code menu, and type Docker to install the extension.

Once it is done you would see the docker extension as below.

The Docker extension makes it easy to build, manage, and deploy containerized applications from Visual Studio Code. This also allows us to automatically generate a docker file for the platform we need.

Now go to View -> Command Pallete -> type Docker

Select Add Docker Files to Workspace...

then select .Net: ASP.Net core

Select Linux

Select No as we do not need Docker Compose files.

Choose 80 as Port.

You will see 2 files created in the project directory: Dockerfile and .dockerignore. 

The .dockerignore file is similar to .gitignore file which will have a bunch of files and directories extensions that you want to exclude from the image that is going to be created.

This is how Dockerfile looks:

Let's build the image out of this docker file.

The naming convention of the docker image is: <Docker Hub ID>/Project Name>:<Version>

Docker Hub Id - It is your docker hub account that you might have created as mentioned in pre-requisites.

Project Name: Name of the repository, please note the name must be lowercase.

So in my case docker build command in PowerShell/ VS Code terminal will be:

-t is the tag.

and  you will see at the end:


So the docker build command will interpret all the steps in Dockerfile and gives the image that gets added to the docker image cache. You can view the image by running the command below:

Now the image is ready, in order to run it on the local machine, issue the following command:

-p flag - It is for port mapping, in this case, its mapping port 8080 of my local machine to port 80 of the container.

Your image will now be running as a container. To test this open Postman and run the command as below:

So, at this point, we have an app that is containerized and running on our local machine.

Since containers are fully self-contained, independently deployable apps, our aim is to deploy it on any machine which has nothing installed but just the docker and the app should run as expected. 

To achieve this, our next step is to publish our image somewhere so that it is available for use, and so here comes the need for DockerHub which is a repository comprising of useful docker images. 

At this point, you will need to have signed up for DockerHub account as mentioned in pre-requisites, once the image is pushed from the local the machine  you will see your image under repositories as below:

So to push the image to Docker Hub, we need to login to Docker hub:

You may be asked credentials, which will be your unique docker hub id and password.

To push the image to Docker Hub run the docker push command:

This will push your image on your repository space:

So now our .net microservice is available for consumption from any machine.

You can test this from any other machine if you have, you will just need to install docker if there is none. 

If you do not have any different machines, you can create an EC2 instance on AWS or a Virtual machine in AZURE. You will need to login to your free AWS account or Azure account whichever you prefer to use.

Install docker and run the image in Linux base AWS EC2 instance

I will show you steps to install docker and run the image in Linux based AWS EC2 instance.

1. Launch an instance with the Amazon Linux 2
2. Connect to your instance.
3. Once you are logged in, run these commands as below:

Update the installed packages and package cache on your instance

Install the most recent Docker Community Edition package.

Start the Docker service.

Run docker run command:

As this image is public, Docker should go to Docker Hub, (as it can’t find the image locally), pull down the image, and run it.

Note the public IP address of the EC2 instance.

Test the service using postman using the public IP address:

And our container running app will return the JSON response.

Note: You can do similar steps if you prefer to use AZURE.