Intro
Purpose
Become familiar with the building blocks for creating microservices with .NET.
Prerequisites
None.
Time to Complete
15 minutes
Scenario
Create a simple service that returns a list of values, then run the service in a Docker container.
Install .NET SDK
To start building .NET apps you just need to download and install the .NET SDK (Software Development Kit).
Not running x64? You'll need to download the .NET Core binaries instead.
Enable .NET channel
In order to install .NET Core from Red Hat on RHEL, you first need to register using the Red Hat Subscription Manager. If this has not been done on your system, or if you are unsure, see the Red Hat Getting Started Guide.
Install the .NET SDK
After registering with the Subscription Manager and enabling the .NET Core channel, you are ready to install and enable the .NET SDK.
In your terminal, run the following commands:
Terminal
yum install rh-dotnet22 -y
scl enable rh-dotnet22 bashRegister Microsoft key and feed
Before installing .NET, you'll need to register the Microsoft key, register the product repository, and install required dependencies. This only needs to be done once per machine.
Open a terminal and run the following commands:
Terminal
wget -q https://packages.microsoft.com/config/ubuntu/19.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.debInstall the .NET SDK
Update the products available for installation, then install the .NET SDK.
In your terminal, run the following commands:
Terminal
sudo apt-get install apt-transport-https
sudo apt-get update
sudo apt-get install dotnet-sdk-2.2If you receive an error message similar to Unable to locate package dotnet-sdk-2.2, run the following commands.
Terminal
sudo dpkg --purge packages-microsoft-prod && sudo dpkg -i packages-microsoft-prod.deb
sudo apt-get update
sudo apt-get install dotnet-sdk-2.2If that doesn't work, you can run a manual install with the following commands.
Terminal
sudo apt-get install -y gpg
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.asc.gpg
sudo mv microsoft.asc.gpg /etc/apt/trusted.gpg.d/
wget -q https://packages.microsoft.com/config/ubuntu/19.04/prod.list
sudo mv prod.list /etc/apt/sources.list.d/microsoft-prod.list
sudo chown root:root /etc/apt/trusted.gpg.d/microsoft.asc.gpg
sudo chown root:root /etc/apt/sources.list.d/microsoft-prod.list
sudo apt-get install -y apt-transport-https
sudo apt-get update
sudo apt-get install dotnet-sdk-2.2Register Microsoft key and feed
Before installing .NET, you'll need to register the Microsoft key, register the product repository, and install required dependencies. This only needs to be done once per machine.
Open a terminal and run the following commands:
Terminal
wget -q https://packages.microsoft.com/config/ubuntu/18.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.debInstall the .NET SDK
Update the products available for installation, then install the .NET SDK.
In your terminal, run the following commands:
Terminal
sudo add-apt-repository universe
sudo apt-get install apt-transport-https
sudo apt-get update
sudo apt-get install dotnet-sdk-2.2If you receive an error message similar to Unable to locate package dotnet-sdk-2.2, run the following commands.
Terminal
sudo dpkg --purge packages-microsoft-prod && sudo dpkg -i packages-microsoft-prod.deb
sudo apt-get update
sudo apt-get install dotnet-sdk-2.2If that doesn't work, you can run a manual install with the following commands.
Terminal
sudo apt-get install -y gpg
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.asc.gpg
sudo mv microsoft.asc.gpg /etc/apt/trusted.gpg.d/
wget -q https://packages.microsoft.com/config/ubuntu/18.04/prod.list
sudo mv prod.list /etc/apt/sources.list.d/microsoft-prod.list
sudo chown root:root /etc/apt/trusted.gpg.d/microsoft.asc.gpg
sudo chown root:root /etc/apt/sources.list.d/microsoft-prod.list
sudo apt-get install -y apt-transport-https
sudo apt-get update
sudo apt-get install dotnet-sdk-2.2Register Microsoft key and feed
Before installing .NET, you'll need to register the Microsoft key, register the product repository, and install required dependencies. This only needs to be done once per machine.
Open a terminal and run the following commands:
Terminal
wget -q https://packages.microsoft.com/config/ubuntu/16.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.debInstall the .NET SDK
Update the products available for installation, then install the .NET SDK.
In your terminal, run the following commands:
Terminal
sudo apt-get install apt-transport-https
sudo apt-get update
sudo apt-get install dotnet-sdk-2.2If you later perform an in-place upgrade, you may get an error message similar to Unable to locate package dotnet-sdk-2.2 when trying to install/update .NET.
See Ubuntu 19.04 install instructions to learn how to fix this issue.
Register Microsoft key and feed
Before installing .NET, you'll need to register the Microsoft key, register the product repository, and install required dependencies. This only needs to be done once per machine.
Open a terminal and run the following commands:
Terminal
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.asc.gpg
sudo mv microsoft.asc.gpg /etc/apt/trusted.gpg.d/
wget -q https://packages.microsoft.com/config/debian/9/prod.list
sudo mv prod.list /etc/apt/sources.list.d/microsoft-prod.list
sudo chown root:root /etc/apt/trusted.gpg.d/microsoft.asc.gpg
sudo chown root:root /etc/apt/sources.list.d/microsoft-prod.listInstall the .NET SDK
Update the products available for installation, then install the .NET SDK.
In your terminal, run the following commands:
Terminal
sudo apt-get install apt-transport-https
sudo apt-get update
sudo apt-get install dotnet-sdk-2.2Add the dotnet product feed
Before installing .NET, you'll need to register the Microsoft key, register the product repository, and install required dependencies. This only needs to be done once per machine.
Open a terminal and run the following commands:
Terminal
sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc
sudo wget -q -O /etc/yum.repos.d/microsoft-prod.repo https://packages.microsoft.com/config/fedora/27/prod.repoInstall the .NET SDK
Update the products available for installation, then install the .NET SDK.
In your terminal, run the following commands:
Terminal
sudo dnf update
sudo dnf install dotnet-sdk-2.2Add the dotnet product feed
Before installing .NET, you'll need to register the Microsoft key, register the product repository, and install required dependencies. This only needs to be done once per machine.
Open a terminal and run the following commands:
Terminal
sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc
sudo wget -q -O /etc/yum.repos.d/microsoft-prod.repo https://packages.microsoft.com/config/fedora/27/prod.repoInstall the .NET SDK
Update the products available for installation, then install the .NET SDK.
In your terminal, run the following commands:
Terminal
sudo dnf update
sudo dnf install dotnet-sdk-2.2Add the dotnet product feed
Before installing .NET, you'll need to register the Microsoft key, register the product repository, and install required dependencies. This only needs to be done once per machine.
Open a terminal and run the following commands:
Terminal
sudo rpm -Uvh https://packages.microsoft.com/config/rhel/7/packages-microsoft-prod.rpmInstall the .NET SDK
Update the products available for installation, then install the .NET SDK.
In your terminal, run the following commands:
Terminal
sudo yum update
sudo yum install dotnet-sdk-2.2Add the dotnet product feed
Before installing .NET, you'll need to register the Microsoft key, register the product repository, and install required dependencies. This only needs to be done once per machine.
Open a terminal and run the following commands:
Terminal
sudo zypper install libicu
sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc
wget -q https://packages.microsoft.com/config/opensuse/42.2/prod.repo
sudo mv prod.repo /etc/zypp/repos.d/microsoft-prod.repo
sudo chown root:root /etc/zypp/repos.d/microsoft-prod.repoInstall the .NET SDK
Update the products available for installation, then install the .NET SDK.
In your terminal, run the following commands:
Terminal
sudo zypper update
sudo zypper install dotnet-sdk-2.2Add the dotnet product feed
Before installing .NET, you'll need to register the Microsoft key, register the product repository, and install required dependencies. This only needs to be done once per machine.
Open a terminal and run the following commands:
Terminal
sudo rpm -Uvh https://packages.microsoft.com/config/sles/12/packages-microsoft-prod.rpmInstall the .NET SDK
Update the products available for installation, then install the .NET SDK.
In your terminal, run the following commands:
Terminal
sudo zypper update
sudo zypper install dotnet-sdk-2.2Check everything installed correctly
Once you've installed, open a new command prompt and run the following command:
Once you've installed, open a new terminal and run the following command:
Command prompt
dotnetIf the command runs, printing out information about how to use dotnet, you're good to go.
If you receive a 'dotnet' is not recognized as an internal or external command error, make sure you opened a new command prompt. If you can't resolve the issue, use the I ran into an issue button to get help fixing the problem.
Create your service
Create an app
In your command prompt, run the following commands:
In your terminal, run the following commands:
Command prompt
dotnet new webapi -o myMicroservice --no-https
cd myMicroserviceThe dotnet command creates a new application of type webapi (that's a REST API endpoint).
- The
-oparameter creates a directory namedmyMicroservicewhere your app is stored. - The
--no-httpsflag creates an app that will run without an HTTPS certificate, to keep things simple for deployment.
The cd myMicroService command puts you into the newly created app directory.
The generated code
Several files were created in the myNewMicroService directory, to give you a simple service that is ready to run.
myMicroservice.csprojdefines what libraries the project references etc.Startup.cscontains all the settings and configuration that are loaded when the app starts.Controllers/ValuesController.cshas code for a simple API that returns a list of values.
ValuesController.cs (shortened for clarity)
[Route("api/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
// GET api/values
[HttpGet]
public ActionResult<IEnumerable<string>> Get()
{
return new string[] { "value1", "value2" };
}
}Run your service
In your command prompt, run the following command:
In your terminal, run the following command:
Command prompt
dotnet runOnce the command completes, browse to http://localhost:5000/api/Values
![The API endpoint returns the JSON data ["value1","value2"]](/static/images/screenshot-microservice-tutorial-run.png?v=mT2N5o_y9ia0FUm2gy4zqPKO5oWORJ8iJ0QyO6D8mHg)
Congratulations, you've got a simple service running.
Install Docker
Docker is a platform that enables you to combine an app plus its configuration and dependencies into a single, independently deployable unit called a container.
If you already have Docker installed, make sure it's version 18.09 or higher.
Download and install
You'll be asked to register for Docker Store before you can download the installer.
By default, Docker will use Linux Containers on Windows. Leave this configuration settings as-is when prompted in the installer.
Check that Docker is ready to use
Once you've installed, open a new command prompt and run the following command:
Once you've installed, open a new terminal and run the following command:
Command prompt
docker --versionIf the command runs, displaying some version information, then Docker is successfully installed.
Add Docker metadata
To run with Docker Image you need a Dockerfile — a text file that contains instructions for how to build your app as a Docker image. A docker image contains everything needed to run your app as a Docker container.
Return to app directory
Since you opened a new command prompt in the previous step, you'll need to return to the directory you created your service in.
Since you opened a new terminal in the previous step, you'll need to return to the directory you created your service in.
Command prompt
cd myMicroserviceAdd a DockerFile
Create a file called Dockerfile with the following content in a text editor:
Dockerfile
FROM mcr.microsoft.com/dotnet/core/sdk:2.2 AS build
WORKDIR /src
COPY myMicroservice.csproj .
RUN dotnet restore
COPY . .
RUN dotnet publish -c release -o /app
FROM mcr.microsoft.com/dotnet/core/aspnet:2.2
WORKDIR /app
COPY --from=build /app .
ENTRYPOINT ["dotnet", "myMicroservice.dll"]Note: Make sure to name the file as Dockerfile and not Dockerfile.txt or some other name.
Optional: Add a .dockerignore file
A .dockerignore file reduces the set of files that are used as part of `docker build`. Fewer files will result in faster builds.
Create a file called .dockerignore file (this is similar to a .gitignore file if you are familiar with those) with the following content in a text editor:
.dockerignore
Dockerfile
[b|B]in
[O|o]bjCreate Docker image
Run the following command:
Command prompt
docker build -t mymicroservice .The docker build command uses the Dockerfile to build a Docker image.
- The
-t mymicroserviceparameter tells it to tag (or name) the image asmymicroservice. - The final parameter tells it which directory to use to find the
Dockerfile(.specifies the current directory).
You can run the following command to see a list of all images available on your machine, including the one you just created.
Command prompt
docker imagesRun Docker image
You can run your app in a container using the following command :
Command prompt
docker run -it --rm -p 3000:80 --name mymicroservicecontainer mymicroserviceOptionally, you can view your container running in a separate command promptterminal window using the following command:
Command prompt
docker psYou can browse to the following URL to access your application running in a container: http://localhost:3000/api/values.
![The API endpoint returns the JSON data ["value1","value2"]](/static/images/screenshot-microservice-tutorial-run-docker.png?v=XTy0VvUu2SqYYBIopEJc9HD9rqkvHcWdf1n05ZCncQA)
Congratulations! You've successfully created a small, independent service that can be deployed and scaled using Docker containers.
These are the fundamental building blocks of microservices.
Next steps
Next, deploy your microservice to the cloud.
Tutorial: Deploy microservice to Azure
You might also be interested in...
