Diving into Azure

Create your own VS Code codespace using a custom build box

johan.ohlin@outlook.com (Johan Ohlin) — Fri, 05 Feb 2021 00:00:00 +0000

From Feburary 17, the option to run codespaces with your repositories, hosted in Azure (maybe even paid with credits), is gone and now all you can do is running it in GitHub while paying hard earned cash for it. But there are options. You can setup your own Azure VM and let it be your build box by using the Remote SSH plugin in VS Code. In this blog post I’ll show you all the steps you need to setup the VM, connect to it from VS Code, and finally create, build and deploy a .NET Core app with Docker.

Setup the build VM

The first step is to prepare a VM to run your builds on. This can be a local computer or a VM in the cloud, depending on what your have available. I’ll use an Azure VM in this example.

Generate key with password

To secure a VM properly, Microsoft recommends that you use a password protected key rather than just a password. There are different ways of creating keys to use. In this example, I’ll show you how to create the key in Azure cloud shell associated with your personal login, but there are other ways to do it also.

If you don’t already heave a password protected key, create one with this command in the cloud shell. This will create a 4096 bits key for the user name azureuser. Remember this user name because you’ll use it later on. You can change this user name to whatever you prefer. This command will ask you for a password. This password will be used whenever this key is being used to make note of it somewhere.

ssh-keygen \
  -m PEM \
  -t rsa \
  -b 4096 \
  -C "azureuser"

This key will be stored in the .ssh folder in your cloud account. It’ll create two files, one for your private key (id_rsa) and one for the public (is_rsa.pub).

Create SSH Key in Azure

Whenever you’re creating a new VM with key authentication, the public key will be used as the VMs way to authenticate you. To make it easier to handle the public key, you can create an SSH Key in Azure that holds the public key so it’s ready when you create a VM.

Search for SSH Key in Azure and create a new instance. In the public key section, paste in the public key you just created (from id_rsa.pub). To show the content of that file, simply type cat id_rsa.pub inside the .ssh folder.

Create VM

If you create the VM in the portal, make sure you select Linux image. For this post, I used Ubuntu 18.04 LTS. Also deselect Availability options if they are preselected for you.

As size, I’m using a Standard_B1s with 1 VCPU and 1 GB of RAM costing me around 9 USD/month. This is actually enough to even create docker builds.

For the authentication, select SSH public key. Username should be the same as you used when creating the key earlier on. If you created an SSH Key from you public key in the previous step, then select Use existing key stored in Azure as SSH public key source. You’ll then be able to select from a list the SSH key.

Make sure SSH port 22 is open so we can connect to the VM later on.

Considering OS disk, you have several options. Running a managed disk will give you several improvements regarding reliability and flexibility. You can dynamically increase the size of the disk (but not decrease) something you can’t easily with an unmanaged page-blob disk. A 32 GB managed standard ssd disk will currently cost you around 2.60 USD/month.

Options under Networking can be left as default, unless you have specific needs.

Under Management, make sure to select Auto-shutdown to save a little more on your VM cost.

Click Review + create and then Create.

If you don’t want to pay for a constand static IP then you’ll get a new IP each time you restart your VM. A better way of doing this is to assign it a DNS name that you can use when connecting to it. This name needs to be unique in the region where you have your VM. If you didn’t set a DNS name when you created the VM then you can do that from the VM overview page.

Create VM with Azure CLI

If you want to create the VM in Azure CLI from the cloud shell, use the following commands. Since a VM creates a number of resources (disk, nic, etc) it’s easier if the VM gets it’s own resource group to stay in. Then, if you want to delete it you know exactly what items to delete.

The parameter --generate-ssh-keys will only generate new keys if you don’t have any existing ones. Since we created keys above, they will be used instead and the command will then ask you for the password for the keys.

As described in the section about creating a VM in the portal, it’s beneficial to assign a DNS name to your VM. Change the variable uniquednsname below to something unique before running the script.

subscription=<subscription guid>
location=westeurope
resourceGroup=linuxbox
vmName=linuxbox
uniquednsname=linboxtest
image=UbuntuLTS
username=azureuser

# Create a new resource group
az group create --name $resourceGroup --location $location --subscription $subscription

# Create the VM
az vm create \
  --subscription $subscription \
  --resource-group $resourceGroup \
  --name $vmName \
  --image $image \
  --admin-username $username \
  --generate-ssh-keys \
  --storage-sku StandardSSD_LRS \
  --os-disk-size-gb 30 \
  --size Standard_B1s \
  --public-ip-address-dns-name $uniquednsname

# Enable auto shutdown at 6 pm
az vm auto-shutdown \
  --subscription $subscription \
  --resource-group $resourceGroup \
  --name $vmName \
  --time 1800

Config details for disks, vm and vm sizes.

The response from creating the VM will look like this

{
  "fqdns": "linboxtest.westeurope.cloudapp.azure.com",
  "id": "/subscriptions/___/resourceGroups/linuxbox/providers/Microsoft.Compute/virtualMachines/linuxbox",
  "location": "westeurope",
  "macAddress": "00-11-BB-AA-55-22",
  "powerState": "VM running",
  "privateIpAddress": "10.0.0.16",
  "publicIpAddress": "100.200.200.100",
  "resourceGroup": "linuxbox",
  "zones": ""
}

Test the connection by using SSH in the cloud console

`1`	`ssh azureuser@linboxtest.westeurope.cloudapp.azure.com`

On new VM

Now it’s time to setup the tools you need/want on your build box. In the examples below, I’ll build a ASP.NET Core app, build it as a docker container and deploy it azure so these are the tools I’ll install here.

Install docker

sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu bionic stable"
sudo apt update
apt-cache policy docker-ce
sudo apt install -y docker-ce

Verify docker is running

`1`	`sudo systemctl status docker`

As it currently stands, you can only run the docker commands by logging in as root or if running with sudo. But from VS Code, we’ll run as your custom user. We therefore need to enable that user to run docker commands.

Add your user to the docker groups

sudo groupadd docker
sudo usermod -aG docker azureuser
newgrp docker
sudo chown azureuser:azureuser ~/.docker -R
sudo chmod g+rwx ~/.docker -R

Docker is working from your user account if you can run docker version without getting any permission errors at the end of the message. If you get permission errors then try to logout and login as your user, or even restart the VM.

Install .Net 5 SDK and runtime

wget https://packages.microsoft.com/config/ubuntu/18.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
sudo apt-get update
sudo apt-get install -y apt-transport-https
sudo apt-get install -y dotnet-sdk-5.0

Install Azure CLI

There’s a all-in-one script to install Azure CLI on Linux. If you want to do it the long way you can read more here.

`1`	`curl -sL https://aka.ms/InstallAzureCLIDeb \| sudo bash`

Setup your local work computer

Now the VM is prepared and we continue with setting up the things you need on your local work computer

Configure SSH

The basic idea behind the workflow is that your work computer can communicate with the Linux VM using SSH. The VM is configured to authenticate using a key so we need to start by setting up the key configuration. The SSH configuration files can be found in the .ssh folder in your user folder.

Copy the file .ssh/id_rsa in your cloud shell to a file with the same name on your local work computer. This is a secret file so don’t store it anywhere public on the computer.

Create a file config in the .ssh folder on your computer. Inside the file, add the following setup, with adjustments to point to your created VM.

Host linuxbox
HostName linboxtest.westeurope.cloudapp.azure.com
User azureuser
IdentityFile ~/.ssh/id_rsa

Try the SSH connection by running the following command in Powershell. You should be prompted for the password you’ve configured for the key.

`1`	`ssh linuxbox`

If everything works well and you’re able to connect, then you can continue to the next section.

Configure VS Code

In VS Code, find and install the extension Remote - SSH by Microsoft.

Open the Remote Explorer tab to the left and select SSH Targets in the drop-down menu. You should be able to see linuxbox as an SSH Target. The name linuxbox will depend on the Host you defined in the config file. Right-click on linuxbox and select to open in same or new window.

You will be prompted to select what target OS type that you’re connecting to. Select Linux. This setting will be stored in VS Code as the setting remote.SSH.remotePlatform.

Next you’ll have to enter the password for the key used.

If you see a green little box down in the left corner saying SSH: linuxbox then VS Code is connected and you’re ready to create your first remotely built program with this setup.

One thing you’ll notice soon is that each time you have to reload VS Code (i.e. you add an extension that needs a reload, or you select a folder to open) you’ll also have to enter your SSH key password again. This is just to keep your connection secure so you have to get used to it.

If you have a lot of extensions installed on your local VS Code that you also want to use on your remote build machine then there’s now a new section in the Extensions tab, called SSH: LINUXBOX - INSTALLED. Go through your local extensions and look for them that have Install in SSH: linuxbox in blue written under them. These can also be installed on your remote server.

Some extensions that are useful to install on your VM, in this specific setup, are:

Docker (from Microsoft) - if you’ve configured docker to run from your local user then you can control docker on the VM from this Docker extension.
Azure Account (from Microsoft) - enables you to login to Azure from your VM. Inside the Docker extension, you can now browse your Azure Container Registry resources you have.
C# (from Microsoft) - C# editing support

Create a sample application

VS Code is now connected to your VM and everything done in VS Code will be executed on the VM. If you open a terminal window in VS Code (press CTRL + '), this will also be connected to the VM.

We’ve previously installed .NET Core CLI on the VM so let’s use that to create an app. Run this command to create the app structure. The app will also be loaded in VS Code.

1
2

dotnet new mvc -o MyNiceApp
code -r MyNiceApp

You can test run your application with dotnet run

Create a docker file named dockerfile in the root of your project, next to the project file. Add the following code to the file.

FROM mcr.microsoft.com/dotnet/sdk:5.0-buster-slim AS build-env
WORKDIR /app

# Copy csproj and restore as distinct layers
COPY \*.csproj ./
RUN dotnet restore

# Copy everything else and build
COPY . ./
RUN dotnet publish -c Release -o out

# Build runtime image
FROM mcr.microsoft.com/dotnet/aspnet:5.0-buster-slim
WORKDIR /app
COPY --from=build-env /app/out .
ENTRYPOINT ["dotnet", "MyNiceApp.dll"]

To create a new image file in docker you have two options. The first is to build it with a command.

`1`	`docker build -t myniceapp .`

And the second is to right-click the dockerfile in VS Code and select Build image...

You can list your created images with

`1`	`docker images`

If needed, you can test run the image locally

`1`	`docker run -it --rm -p 8080:80 myniceapp`

Assuming you have Azure Container Registry up and running, you can now push this image there directly from the terminal in VS Code. First you need to login in Azure Container Registry.

1
2

az login
az acr login --name mycontainerregistry

When that is done, you can tag the image and finally push it. Replace myacr with the name of your container registry before running the commands.

1
2

docker tag myniceapp myacr.azurecr.io/myniceapp
docker push myacr.azurecr.io/myniceapp

Your webapp is now available in Azure Container Registry to be deployed to a cluster, a container intance or an app service.

Conclusions

So, your custom build box is ready to be used. But is it worth all the fuss? Here are some pros and cons.

Pros

You can run a VM using Azure credits
You can use the above setup steps to connect to a linux computer locally that you already own and then there’s no VM charges at all.
You can use your build box for many repositories. The Code Space can only be used for a single repository. If you need to work on two repositories at once, then you need to pay for two running Code Spaces, but not two VMs.

Cons

A Code Space is very easy to setup, especially in GitHub, while a custom VM build box has many configuration steps involved
You have to automatically shut your VM down when you don’t need it (auto-shutdown of VM at specific time is helpful)

If you decide to build your own or use the existing GitHub one is maybe down to personal preferences. I’ll most likely end up using a combination of both. But I’m very grateful to the VS Code team for building the Remote SSH plugin making this option even possible.

Using SGR5 in Windows Terminal

johan.ohlin@outlook.com (Johan Ohlin) — Fri, 06 Nov 2020 00:00:00 +0000

With the release of Windows Terminal 1.4 support for SGR 5 parameters were added. SGR (Select Graphic Rendition) parameters sets display attributes when you’re showing text on a terminal. These attributes can alter things like colour of the text and now also, and with this Windows Terminal release, you can make the text blink.

The easiest way to to get started is pick a ready made ASCII art and then add some blinking colour to it. For this illustration I picked a lighthouse.

To get right to it, create a new bash file lighthouse.sh and add the following code to the file.

echo -e ""
echo -e "            +             \033[5;1;33m/\033[0m"
echo -e "\033[5;1;33m\\ \033[0m          |           \033[5;1;33m/\033[0m"
echo -e "  \033[5;1;33m\\ \033[0m        |         \033[5;1;33m/\033[0m"
echo -e "    \033[5;1;33m\\ \033[0m     / \\      \033[5;1;33m/\033[0m"
echo -e "      \033[5;1;33m\\ \033[0m /_____\  \033[5;1;33m/\033[0m"
echo -e "      \033[5;1;33m/\033[0m  |\033[5;1;33m\u2588\u2588\033[0m|\033[5;1;33m\u2588\u2588\033[0m|  \033[5;1;33m\\ \033[0m"
echo -e "    \033[5;1;33m/\033[0m  |;|     |;|  \033[5;1;33m\\ \033[0m"
echo -e "  \033[5;1;33m/    \033[0m\\.    .   /    \033[5;1;33m\\ \033[0m"
echo -e "\033[5;1;33m/\033[0m       ||:  .  |       \033[5;1;33m\\ \033[0m"
echo -e "        ||:     |         \033[5;1;33m\\ \033[0m"
echo -e "        ||:.    |           \033[5;1;33m\\ \033[0m"
echo -e "        ||:    .|"
echo -e "        ||:   , |         /-\\"
echo -e "        ||:     |                                          /-\\"
echo -e "        ||: _ . |                             /-\\"
echo -e "       _||_| |__|                      \033[04m____"
echo -e "  ____~\033[0m    |_|  |___           \033[94m__-----~    ~---,__             ___"
echo -e "-~                  ~---___,--~                  ~~----_____-~"
echo -e "~----,____                      \033[0m -Niall-"
echo -e ""
echo -e ""

To run this script showing a lighthouse, you first have to make the file executable. On Linux, that’s done like this.

`1`	`chmod 755 lighthouse.sh`

After that, you can add ~/lighthouse.sh at the end of your login script .bashrc, and, voila, you have a pimped login screen for your WSL terminal.

So how does it work? The key is the escape character \033. It’s not specific to bash but is rather interpreted by Windows Terminal.

The SGR codes used in the example are

Code	Effect
0	Reset to normal
1	Bold
5	Slow blink
33	Yellow
94	Bright blue

You can specify several SGR codes at once after the escape character by starting with [ and ending with m. Some examples:

Change terminal output to slow blinking, bold and yellow

`1`	`\033[5;1;33m`

Change terminal output to bright blue

`1`	`\033[94m`

Reset terminal output to normal

\033[0m

By alternating these three examples, we’re able to create a blinking effect in the ASCII art making the light pulsate and the water turn blue.

There are a lot more things you can do as shown here. If you want to build more advanced things you can also use blocks. I had to change the windows of the lighthouse to use unicode block elements instead to make the colour fill up the whole window.

You might think that blinking text isn’t that useful - and you’re right. But it’s fun, you have to admit that.

Deploying a worker service to Kubernetes

johan.ohlin@outlook.com (Johan Ohlin) — Tue, 19 Nov 2019 00:00:00 +0000

Once you have the worker service configured with health checks it’s time to get it deployed. In this article I’ll show you how to deploy the service to AKS (Kubernetes) using ACR and Helm.

This article is based on a previous article where we created a Worker Service in .NET Core 3 with health check endpoints enabled.

In a real world scenario you would set up complete CI/CD pipelines doing some of these steps for you. However, in this article I’ll do all the steps manually to show a bit more in detail how it’s being done.

Create docker image

If you created your project with docker support, then you should have a docker file in your project root. If not, then you can create a new one by right-clicking the project and selecting Add -> Docker Support. You’ll be asked what Target OS to create the dockerfile for, either Linux or Windows. This is not the OS on your machine but rather what OS the container will be running on and you can use both Linux and Windows on a Windows computer.

The dockerfile might differ depending on what version of Visual Studio you’re using. But it should look something like this.

FROM mcr.microsoft.com/dotnet/core/aspnet:3.0-buster-slim AS base
WORKDIR /app
EXPOSE 80

FROM mcr.microsoft.com/dotnet/core/sdk:3.0-buster AS build
WORKDIR /src
COPY ["WorkerServiceWithHealthChecks/WorkerServiceWithHealthChecks.csproj", "WorkerServiceWithHealthChecks/"]
RUN dotnet restore "WorkerServiceWithHealthChecks/WorkerServiceWithHealthChecks.csproj"
COPY . .
WORKDIR "/src/WorkerServiceWithHealthChecks"
RUN dotnet build "WorkerServiceWithHealthChecks.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "WorkerServiceWithHealthChecks.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "WorkerServiceWithHealthChecks.dll"]

To build a docker image from your dockerfile you need to have docker running on the build machine, which is the local dev machine for me. I have Docker Desktop installed, running Linux containers.

The FROM line in the dockerfile above tells what source to use. aspnet:3.0-buster-slim is a Debian Linux source containing ASP.NET 3.0. More possible sources can be found here.

In Visual Studio, right-click on a dockerfile and select Build Docker image to build it. You can also build a Docker image using the command line

`1`	`docker build --rm -f "Dockerfile" -t workerservicewithhealthchecks:latest .`

Push docker image to a container registry

A container registry is like a code repository on internet, but for container images. These images can then easily be pulled later on by different resources that need them. In this example, I’ll use Azure Container Registry (ACR) to store the built images.

For the purpose of this article, I’ve setup a basic container registry named blogacrtest, accessible through the URI blogacrtest.azurecr.io.

To push an image to ACR from your command prompt you need to first have Azure CLI installed. When it’s installed you can login to ACR this way:

1
2

az login
az acr login -n blogacrtest

If you have created an ACR instance separately from the AKS instance then they need to be linked together for AKS to have permissions to pull images. There are different ways of doing it. One of the newer options is to use the update command for AKS. It’s currently in preview mode so you need to enable preview features before you can use it. This might not be an option for you if you’re running your cluster in production. This way of linking only works if they are in the same subscription.

`1`	`az aks update -n myAKSCluster -g myResourceGroup --attach-acr blogacrtest`

Run the following command to view all the existing images you’ve created. Your recent image myworkerservice should be there in the list with the tag latest.

`1`	`docker image list`

We need to create a tag target for the new container registry that refers to the local image.

`1`	`docker tag workerservicewithhealthchecks blogacrtest.azurecr.io/workerservicewithhealthchecks:0.0.1`

When we now list all images we’ll see how both images point to the same image id.

1
2
3

REPOSITORY TAG IMAGE ID CREATED SIZE
blogacrtest.azurecr.io/workerservicewithhealthchecks 0.0.1 59aa0a033cb6 4 minutes ago 210MB
workerservicewithhealthchecks latest 59aa0a033cb6 4 minutes ago 210MB

And then finally we can push the image.

`1`	`docker push blogacrtest.azurecr.io/workerservicewithhealthchecks:0.0.1`

This will take some time when we do it for the first time.

The push refers to repository [blogacrtest.azurecr.io/workerservicewithhealthchecks]
58d48a1xxxxx: Pushed
ce65098xxxxx: Pushed
0a37aeexxxxx: Pushing [================> ] 25.78MB/76.45MB
1c7781dxxxxx: Pushed
00672cbxxxxx: Pushing [===========================> ] 23.01MB/41.34MB
2db44bcxxxxx: Pushing [=======> ] 10.32MB/69.21MB

I won’t go into detail how a docker image is built up, but basically it’s split up into separate layers, out of which your code only is one of them. The other layers are related to the framework your code is running on. When you make changes to your code and push anew then only that layer needs to be pushed, the others stay as they are. The subsequent pushes will therefore go much quicker, unless you change the source part in your docker file.

In Azure Container Registry it should now look like this.

Creating a Helm chart for deployment

Helm is a package manager for Kubernetes that abstracts away many of the complexities of a deployment using the native yaml files, something you otherwise would have to use. Helm 3 has recently reached release candidate level so I’ll use that version here instead of the stable Helm 2. The main reason is that Helm 3 has ditched the tiller component that Helm 2 forced you to install in your kubernetes cluster with way to high access rights. Now with that security issue gone we should stick to Helm 3.

A Helm chart is the package that bundles your docker image file into a deployable unit. Helm has a lot of features to offer, including defining dependencies between several different Helm charts and also, once you’ve installed a Helm chart in Kubernetes, the ability to rollback to a previous version of your chart.

The official way to create a Helm chart in Visual Studio is still using Helm version 2. Right-click on your project and select Add -> Container Orchestration Support. In the dialog that comes up, select Kubernetes/Helm. This will create a chart for your project and setup a connection to Azure Dev Spaces (a really cool feature that I’ll write more about another time).

But if you want to use Helm 3 you have to do a bit more manual work. Installing Helm in Windows is done by using chocolatey, but that has currently also only Helm 2 to offer. Keep an eye on this page for what Helm versions being supported.

The current way to install Helm 3 is to download it from the releases page and add the folder with the binary to the path environment variable. If you run helm version you should see the current client version being printed on screen.

1
2

> helm version
> version.BuildInfo{Version:"v3.0.0-rc.3", GitCommit:"...", GitTreeState:"clean", GoVersion:"go1.13.4"}

If you have Helm 2 installed you'll see two lines here, the client and tiller in the cluster. If tiller isn't configured, you'll see an error, as in the example below.

1
2
3

> helm version
> Client: &version.Version{SemVer:"v2.16.0", GitCommit:"...", GitTreeState:"clean"}
> Error: could not find tiller

Inside your code project, create a folder named charts. Inside that folder, run the following command to create a Helm chart for your docker image. It’s important to write the chart name in lower case or you’ll end up with errors later on during deployment.

`1`	`helm create workerservicewithhealthchecks`

When the Helm chart is created, it creates templates for deployment (pods), service and ingress. However, the worker service, that we’re trying to deploy here, only needs a deployment since there’s no inbound traffic. The health check endpoint on the worker service is accessed directly on each pod by Kubernetes and for that, the deployment is just enough. You can therefore delete the files ingress.yaml, service.yaml and serviceaccount.yaml from your chart.

In the file values.yaml you can remove the section service:. Also change ingress to have enabled: false and serviceAccount: to have create: false. Change the section image: to link to our new repository. These sections in the file should then look like this:

image:
repository: blogacrtest.azurecr.io/workerservicewithhealthchecks
pullPolicy: IfNotPresent

ingress:
enabled: false

serviceAccount:
create: false

In the file Chart.yaml we have a setting appVersion that needs to reflect the tag we’ve assigned to the image. In the example above we set the value to 0.0.1 so that’s the value we need to change the app version to. Don’t confuse this setting with version which is the setting of the chart that you’re creating. If you change anything in the chart settings, but not in the app code, then you bump version. If you make changes in your app code then you bump both version and appVersion. The Chart.yaml file now looks like this:

apiVersion: v2
name: workerservicewithhealthchecks
description: Worker Service with Health Checks
type: application
version: 0.0.1
appVersion: 0.0.1

The file NOTES.txt contains information about the new installation that will be written out on the screen after the installation is successful. Since we won’t have a service running, we need to make some alternations here. This sample explains how to setup a proxy to view the health endpoint without running a complete kubernetes service and ingress. Just paste this text into the file and save it.

For testing purposes, you can now create a proxy on your local machine to access the service.
Run these commands and then navigate to `http://127.0.0.1:8080/health` to view the health status endpoint

export POD_NAME=$(kubectl get pods --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "workerservicewithhealthchecks.name" . }},app.kubernetes.io/instance={{ .Release.Name }}" -o jsonpath="{.items[0].metadata.name}")
kubectl --namespace {{ .Release.Namespace }} port-forward $POD_NAME 8080:80

Finally, the chart has installed a test to see that the service is up and running. Since we’re not using a service, we can remove the tests folder.

We’re almost done with the helm chart, but first we need to tweak the deployment template to work with health checks.

Kubernetes health checks

In the previous article, we created a worker service with health checks enabled. Here, we’ll hook it up to the infrastructure so Kubernetes can be made aware of the status of the worker service.

Kubernetes has two functionalities for checking the health of a pod:

Readiness - checks if pod has started up and is ready to receive requests. Since we have a worker service, we don’t need to think about this one.
Liveness - checks if pod is alive and working as it should. This is the check we can hook into.

If we open up the deployment.yaml file from the Helm chart, we find a section inside the containers: looking like this:

livenessProbe:
httpGet:
path: /
port: http
readinessProbe:
httpGet:
path: /
port: http

We need to make some changes here, but first we need to take a look at what options we have. There are different ways to make health checks in Kubernets:

Command - run a command inside pod to figure out its health
HTTP probe - a GET call to a specific endpoint
TCP probe - call to a specific port

In this case, we’ll use the HTTP probe since that’s what we setup in the previous article. A simple HTTP health check can look like this.

livenessProbe:
httpGet:
path: /health
port: 80

But there are also other settings you can use here to configure the probe:

initialDelaySeconds - Number of seconds to wait until starting to check the liveness probe. Default is 0.
periodSeconds - How many seconds between each probe. Default is 10.
timeoutSeconds - Seconds to wait until a timeout is reached. Default is 1.
successThreshold - Number of consecutive successful calls needed after a failed one before it’s classified as successful again. Default is 1 and liveness probe needs 1 to work properly.
failureThreshold - Number of consecutive failed calls needed until it’s classified as failed and Kubernetes will restart the container. Default is 3.

Many of these values are working fine for us by default, but not all. As described in the previous article, a Worker Service is locking the thread until an async/await is reached. During this time, no response will be given on the health endpoint. The value for timeoutSeconds X failureThreshold needs to be set to a value that is safe considering how often the thread will be released for the health endpoint. This makes these settings highly individual per worker service.

Another value you might need to adjust is the initialDelaySeconds in case your worker service takes some time to start up.

So in the end, our deployment configuration might look something like this:

livenessProbe:
httpGet:
path: /health
port: http
failureThreshold: 6
timeoutSeconds: 5
periodSeconds: 15
initialDelaySeconds: 30

The key here is that a Worker Service doesn’t need to be as responsive as a Web Service, and thus it’s OK if it takes longer time for Kubernetes to find a stuck pod. Try to aim to cover for up to at least the 99th percentile.

Kubernetes deployment

We have now completed setting up the Helm chart for the worker service. If we want to test-run the installation we can do so by navigating to the charts folder and then run the following command. The first name is the name of the installation in Kubernetes and the second name is the chart name.

`1`	`helm install workerservicewithhealthchecks workerservicewithhealthchecks --dry-run --debug`

If we’re happy with the result we can go ahead and install it for real with this command:

`1`	`helm install workerservicewithhealthchecks workerservicewithhealthchecks`

The result should then be displayed as:

Release "workerservicewithhealthchecks" has been upgraded. Happy Helming!
NAME: workerservicewithhealthchecks
LAST DEPLOYED: Wed Nov 20 08:08:55 2019
NAMESPACE: default
STATUS: deployed
REVISION: 5
NOTES:
For testing purposes, you can now create a proxy on your local machine to access the service.
Run these commands and then navigate to http://127.0.0.1:8080/health to view the health status endpoint

export POD_NAME=$(kubectl get pods --namespace default -l "app.kubernetes.io/name=workerservicewithhealthchecks,app.kubernetes.io/instance=workerservicewithhealthchecks" -o jsonpath="{.items[0].metadata.name}")
kubectl --namespace default port-forward $POD_NAME 8080:80

If you later on want to make an upgrade to your code you’ll need to go through the following steps:

Change code
Build new docker image
Tag docker image with ACR domain and new tag version
Update Charts.yaml with new version and appVersion
Call helm upgrade instead of install, as seen below

`1`	`helm upgrade workerservicewithhealthchecks workerservicewithhealthchecks`

Following the results in Kubernetes

To view all the installed pods, run kubectl get pods. In the result you can see the name of your pod and also how many times Kubernetes has restarted it (remember from the previous article that we deliberately made it crash so Kubernetes would restart it).

1
2

NAME                                             READY   STATUS    RESTARTS   AGE
workerservicewithhealthchecks-6c69799695-gxmgv   1/1     Running   3          51m

We can now get more detailed information about this pod by running

`1`	`kubectl describe pod workerservicewithhealthchecks-6c69799695-gxmgv`

The result is a long list of data, including information about the health checks we have configured, but at the bottom you’ll find the recent events, including how Kubernetes has been killing and restarting the pod. In the helm chart, we configured that it would take 6 failed health checks before it should be deemed as bad. That’s why the Unhealthy warning in the event has 6 times as many events as the event Killing.

Events:
  Type     Reason     Age                  From                               Message
  ----     ------     ----                 ----                               -------
  Normal   Scheduled  34m                  default-scheduler                  Successfully assigned default/workerservicewithhealthchecks-6c69799695-gxmgv to aks-nodepool1-abc-0
  Normal   Pulling    34m                  kubelet, aks-nodepool1-abc-0  Pulling image "ohlin.azurecr.io/workerservicewithhealthchecks:0.0.3"
  Normal   Pulled     34m                  kubelet, aks-nodepool1-abc-0  Successfully pulled image "ohlin.azurecr.io/workerservicewithhealthchecks:0.0.3"
  Warning  Unhealthy  8m6s (x12 over 22m)  kubelet, aks-nodepool1-abc-0  Liveness probe failed: HTTP probe failed with statuscode: 503
  Normal   Killing    8m6s (x2 over 21m)   kubelet, aks-nodepool1-abc-0  Container workerservicewithhealthchecks failed liveness probe, will be restarted
  Normal   Created    8m5s (x3 over 34m)   kubelet, aks-nodepool1-abc-0  Created container workerservicewithhealthchecks
  Normal   Started    8m5s (x3 over 34m)   kubelet, aks-nodepool1-abc-0  Started container workerservicewithhealthchecks
  Normal   Pulled     8m5s (x2 over 21m)   kubelet, aks-nodepool1-abc-0  Container image "ohlin.azurecr.io/workerservicewithhealthchecks:0.0.3" already present on machine

Another way to follow the results of how kubernetes changes the status of the pod as it gets restarted, is to list pods with a watch that updates the list as changes occur.

`1`	`kubectl get pods --watch`

This will result in a list like this where each restart creates a new line

NAME                                             READY   STATUS    RESTARTS   AGE
workerservicewithhealthchecks-6c69799695-gxmgv   1/1     Running   421        3d19h
workerservicewithhealthchecks-6c69799695-gxmgv   1/1     Running   422        3d19h
workerservicewithhealthchecks-6c69799695-gxmgv   1/1     Running   423        3d19h
workerservicewithhealthchecks-6c69799695-gxmgv   1/1     Running   424        3d19h

Conclusions

In this and the previous article, we’ve created a worker service in .NET Core 3 that mainly works on a timer but also exposes a health endpoint that Kubernetes uses to restart it when needed. We have not configured any service or ingress objects enabling external access and it’s therefore not possible to access the service pod to manually check the health status unless you also setup a proxy using kubectl, but that shouldn’t be used in a production environment.

In a real world scenario, you would therefore also need hook up logging to a service like Azure Monitor. This can provide a lot of useful and needed telemetry about how the service is processing the jobs it’s expected to do, something we don’t know (or care) about, from a liveness point of view.

Despite being slightly more fiddly in the setup, adding a health check to a background service gives you a good way to add automatic restart functionality with health rules that you can define for yourself in the code. The possibility is there - why not use it?

Worker services in Kubernetes with health checks

johan.ohlin@outlook.com (Johan Ohlin) — Thu, 07 Nov 2019 00:00:00 +0000

One of the key features of Kubernetes is its ability to kick out bad pods and start up new ones. But to be able to do that, Kubernetes needs to communicate with the service to determine its health status.

In this first article, we’re creating a .NET Core 3 Worker Service with the ability to report it’s status and determine if it’s good or bad. In the next article, we continue with deploying this worker service to AKS, enabling Kubernetes to detect if app is in a bad state and then restart it automatically.

To make a practical example out of this, we’ll set the service to always throw an unhandled exception after some time causing the worker loop to stop. This is a typical example of when we want Kubernets to remove the bad service and start up a new one instead.

Setting up the worker service

Per default, the worker service is only thinking about itself, running an internal job, processing a queue or something other less interactive. This is very different from a web service which constantly listens for incoming requests. To implement health checks we need to add light-weight web service capabilities to the worker service so Kubernetes can send requests to ask for health updates. There’s no Visual Studio template that includes both worker and web service and you can solve this in different ways. In this article, I’ve started by creating a web service and then I added the functionality for the worker service, but you could do it the other way around also.

Create a new empty project using the ASP.NET Core Web Application template. Make sure to use ASP.NET Core 3.0 as framework. If you’ve installed Visual Studio 2019 (16.3 or higher) then 3.0 will be the default framework when creating new projects.

If you create projects using the command prompt then it can be done like this.

`1`	`dotnet new web -n WorkerServiceWithHealthChecks`

Add the NuGet package Microsoft.Extensions.Hosting to your project.

Create a worker service as shown below. This code will run for 10 minutes and then throw an unhandled exception which will cause the service to fail, but the app will still be running.

public class InvoiceWorker : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var ticks = 0;
        while (!stoppingToken.IsCancellationRequested)
        {
            if (ticks++ > 10) throw new Exception("Oups...");
            Console.WriteLine("Processing an invoice");
            await Task.Delay(60 * 1000, stoppingToken);
        }
    }
}

public void ConfigureServices(IServiceCollection services)
{
    services.AddHostedService<InvoiceWorker>();
}

Your worker service is now ready to be used.

Adding a health check endpoint

The logic for supporting health checks in an ASP.NET Core Web App is built in and you don’t need any extra NuGet packages for it. But you do need to wire up the internal logic - how you determine if your app is healthy or not.

To do that, we start by creating a static class that we can report the worker service progress to.

public static class InvoiceWorkerStatistics
{
  private static DateTime _lastProcessTime;
  private static readonly object _lockObject = new object();
  public static DateTime GetLastProcessTime()
  {
    lock (_lockObject) {
      return _lastProcessTime;
    }
  }
  public static void SetProcessTime()
  {
    lock (_lockObject) {
      _lastProcessTime = DateTime.UtcNow;
    }
  }
}

In the InvoiceWorker class we created earlier, add the following line to update the statistics class every time we’re running a loop in the iteration.

`1`	`InvoiceWorkerStatistics.SetProcessTime();`

Every 3 seconds, the worker service will now report progress until it crashes out after 10 iterations.

Next we create a health check class that can interpret these statistics and figure out if our worker service is in a healty state or not. The function checks the last time an iteration was running. If it was more than 90 seconds ago then something must have gone wrong and we deem the service to be unhealthy, otherwise it’s healthy. You also have the option to report a Degraded result if the service temporarily needs a break but soon will be available again. For our worker service scenario, since we don’t receive web requests for processing, this is not needed.

public class InvoiceWorkerHealthCheck : IHealthCheck
{
  public Task<HealthCheckResult> CheckHealthAsync(
    HealthCheckContext context,
    CancellationToken cancellationToken = default)
  {
    var lastProcess = InvoiceWorkerStatistics.GetLastProcessTime();
    var timeAgo = DateTime.UtcNow.Subtract(lastProcess);
    var data = new Dictionary<string, object> {
      { "Last process", lastProcess },
      { "Time ago", timeAgo }
    } as IReadOnlyDictionary<string,object>;

    if (lastProcess > DateTime.UtcNow.AddSeconds(-90))
    {
      return Task.FromResult(HealthCheckResult.Healthy("Processing as much as we can", data));
    }

    return Task.FromResult(HealthCheckResult.Unhealthy("Processing is stuck somewhere", null, data));
  }
}

So how long should you wait until classifying your worker service as unhealthy? That completely depends on what you’re processing. If you have few processes that each take 10 minutes to process then maybe you need to wait 30 minutes until you report an unhealthy status. We’ll talk more about how Kubernetes handles these values in the next article, but if an unhealthy status is reported, then Kubernetes will restart your worker service, so be careful with how you set the values here.

Configure the health check service in the ConfigureServices method

public void ConfigureServices(IServiceCollection services)
{
  services.AddHealthChecks()
          .AddCheck<InvoiceWorkerHealthCheck>("service_health_check");
  services.AddHostedService<InvoiceWorker>();
}

Expose an endpoint for the health checks by making changes to the Configure method as shown below. In this example, I’ve added a custom response writer that creates a JSON document with all the available data from the health check. If you don’t add this then the defined health check message will be returned instead.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
  if (env.IsDevelopment())
  {
    app.UseDeveloperExceptionPage();
  }

  app.UseRouting();
  app.UseEndpoints(endpoints =>
  {
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
      AllowCachingResponses = false,
      ResponseWriter = WriteResponse
    });
  });
}

private static Task WriteResponse(HttpContext httpContext, HealthReport result)
{
  httpContext.Response.ContentType = "application/json";
  var json = new JObject(
    new JProperty("status", result.Status.ToString()),
    new JProperty("results", new JObject(result.Entries.Select(pair =>
      new JProperty(pair.Key, new JObject(
        new JProperty("status", pair.Value.Status.ToString()),
        new JProperty("description", pair.Value.Description),
        new JProperty("data", new JObject(pair.Value.Data.Select(
          p => new JProperty(p.Key, p.Value)
        )))
      ))
    )))
  );
  return httpContext.Response.WriteAsync(json.ToString(Formatting.Indented));
}

Your health checks are now completely setup. You can test it by running the project and navigate to the health endpoint. In the beginning, you’ll get an HTTP 200 response looking like this.

{
  "status": "Healthy",
  "results": {
    "service_health_check": {
      "status": "Healthy",
      "description": "Processing as much as we can",
      "data": {
        "Last process": "2019-11-01T13:42:21.5588159Z",
        "Time ago": "00:00:01.4801542"
      }
    }
  }
}

But after a minute, when the exception has been thrown and the timeout has passed, the response will be an HTTP 503 (Service Unavailable) looking like this.

{
  "status": "Unhealthy",
  "results": {
    "service_health_check": {
      "status": "Unhealthy",
      "description": "Processing is stuck somewhere",
      "data": {
        "Last process": "2019-11-01T13:42:45.7795177Z",
        "Time ago": "00:00:30.6624213"
      }
    }
  }
}

Conclusions

It’s very neat to be able to get health data from a worker service, or from any service for that matter. Can you always use health checks created this way in a worker service? The simple answer is no. When you process inside the worker service you’re blocking the thread and no calls can be made to the health endpoint. If you have a long-running process that never uses any async/await calls then you’ll block for a long time and you might get false health results due to timeouts on the health endpoint.

The key here is if you can use async/await once in a while to free up the thread to process other things, like web requests. This could look something like this.

public class InvoiceWorker : BackgroundService
{
  protected override async Task ExecuteAsync(CancellationToken stoppingToken)
  {
    while (!stoppingToken.IsCancellationRequested)
    {
      // Heavy process loop
      for (int i = 0; i < 100; i++) {
        externalService.ProcessNonAsyncCall();
        await Task.Delay(1, stoppingToken);
      }
      await Task.Delay(60 \* 1000, stoppingToken);
    }
  }
}

So, even if the external service used inside the iterator isn’t async, we can make an async call inbetween the process calls and thus free up resources for the health checks. It all depends on the specific scenarios for your worker service.

The worker service is now completely configured for health checks. In the next article we’ll continue with deploying the worker service to kubernetes and to configure the usage of the health checks to determine if the pod is functioning or not.

Using Azure App Configuration in a Worker Service

johan.ohlin@outlook.com (Johan Ohlin) — Tue, 22 Oct 2019 00:00:00 +0000

With .NET Core 3 we were introduced to the new Worker Service template for running continuous jobs. In this article, I’ll show you how to setup the service and also to make use of the new Azure App Configuration service that centralizes the management of app settings.

The Worker Service is simple to use and easy to understand - just create an app with the template and run it. However, it lacks some of the features the classing web job had (timers, queue handling etc) and instead you must wire up this functionality yourself. When you create a new Worker Service template you’re presented with a list page currently only having one option - the basic temple, so we can probably expect more Worker Service templates coming here in the future. Time will tell if that assumption is correct or not.

The Azure App Configuration service enables admins to centralize app settings for several services over multiple environments. I’ll write another article about specific use cases here later on.

Configure Azure App Configuration

One of the best features in Azure App Configuration is labels. You can create a setting and then use labels to keep different values for the same setting separated. In the example below, I’m just creating two simple settings configured for two different services, each with its own values, using labels. In the code further down I’ll connect and fetch the settings for one of these services.

The keys use the standard way of using : to create hierarchical values. You can read more about that in this article about configuration providers.

Creating a new Worker Service project

To use the new Worker Service template, you need to have .NET Core 3 SDK installed on your computer. If you use Visual Studio then you need to use version 2019 (version 16.3 or higher), which also installs the correct .NET Core framework.

After you’ve created a new project using the Worker Service template, you also need to install the NuGet package Microsoft.Extensions.Configuration.AzureAppConfiguration to be able to communicate with the App Config service.

Add the following settings to your appsettings.json file. The connection string can be found under Access Keys in the App Configuration service. The hierarchical path to the settings OptionA and OptionB should match what you setup in App Configuration.

{
  "AppConfiguration": {
    "ConnectionString": "..."
  },
  "Processing": {
    "OptionA": "blue",
    "OptionB": "green"
  }
}

We also create a settings class that maps to these settings in appsettings.json

public class ProcessingSettings
{
  public string OptionA { get; set; }
  public string OptionB { get; set; }
}

In the Program.cs file, extend the host builder with a call to ConfigureAppConfiguration according to the example below.

public class Program
{
  public static void Main(string[] args)
  {
    CreateHostBuilder(args).Build().Run();
  }

  public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
      .ConfigureServices((hostContext, services) =>
      {
        // Default backup settings from appsettings.json
        var settings = hostContext.Configuration.GetSection("Processing");
        services.Configure<ProcessingSettings>(settings);

        // Register the worker service
        services.AddHostedService<CustomerWorker>();
      })
      .ConfigureAppConfiguration((hostingContext, config) =>
      {
        var settings = config.Build();
        config.AddAzureAppConfiguration(options =>
        {
          options.Connect(settings["AppConfiguration:ConnectionString"])
            .ConfigureRefresh(refresh =>
            {
              refresh.Register("Processing:OptionA", "InvoiceService")
                     .Register("Processing:OptionB", "InvoiceService");
            });
        });
      });
}

The ConfigureRefresh function deals with what will happen when a refresh of settings is triggered, something that will happen automatically at startup.

At this point we’ve configured our app to first inject settings from appsettings.json and then to download the settings from Azure App Configuration every time we start the app. The order in which we specify the configuration providers here make a difference since a latter one will overwrite previously injected settings. If all your settings come from Azure App Configuration, then you can exclude the line where you configure ProcessingSettings in the example above.

In this example, we’re downloading the values for OptionA and OptionB for label InvoiceService. If you create a setting without a label, then just leave this variable out or pass in \0 as label.

If we then create a simple background service, we can inject the settings by using the IOption pattern.

namespace InvoiceService
{
  public class InvoiceWorker : BackgroundService
  {
    private ProcessingSettings \_settings;

    public InvoiceWorker(IOptions<ProcessingSettings> settings)
    {
      _settings = settings.Value;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
      while (!stoppingToken.IsCancellationRequested)
      {
        Console.WriteLine($"Option A: {_settings.OptionA}");
        Console.WriteLine($"Option B: {_settings.OptionB}");
        await Task.Delay(5000, stoppingToken);
      }
    }
  }
}

This works great! But there’s more we can do here to extend the experience. In an ASP.NET MVC Core application, we can use IOptionSnapshot to fetch the settings anew each time the web app is being called. The key here is that IOptionSnapshot checks for new values from the source each time it’s being resolved. To avoid having each web app call generate a call to App Configuration, the client caches the settings for 30 sec by default.

However, in the worker service we only call the constructor once - when the app is starting, so that logical flow wouldn’t work here. Instead we have to setup a loop that calls a refresh function at given intervals. We also need to change to use the IOptionMonitor which has a neat callback function that will capture all changes to the settings.

Change the Program.cs file to look like the example below. The key in this change is on line 34 where we fetch a refresher object from the app configuration client that we later on can use to refresh data from the Azure service. Further down, we have a timer that forces the settings to refresh every 30 seconds.

Notice how we also set the cache expiration to be a lower value than the default 30 seconds. This value basically sets how often resolving IOptionSnapshot should trigger a refresh from Azure App Configuration. For a worker service, having a high cache time here doesn’t make sense since we’re not using IOptionSnapshot to trigger a refresh but rather use a controlled timer. But we shouldn’t neither keep it to the default 30 seconds because the cache still prevents us from seeing the refreshed values, thus we set it to a low value.

public class Program
{
  private static IConfigurationRefresher \_refresher = null;
  private static Timer \_timer;

  public static void Main(string[] args)
  {
    CreateHostBuilder(args).Build().Run();
  }

  public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
    .ConfigureServices((hostContext, services) =>
    {
      // Default backup settings from appsettings.json
      var settings = hostContext.Configuration.GetSection("Processing");
      services.Configure<ProcessingSettings>(settings);

      // Register the worker service
      services.AddHostedService<CustomerWorker>();
    })
    .ConfigureAppConfiguration((hostingContext, config) =>
    {
      var settings = config.Build();
      config.AddAzureAppConfiguration(options =>
      {
        options.Connect(settings["AppConfiguration:ConnectionString"])
          .ConfigureRefresh(refresh =>
          {
              refresh.Register("Processing:OptionA", "InvoiceService")
                      .Register("Processing:OptionB", "InvoiceService")
                      .SetCacheExpiration(TimeSpan.FromSeconds(1));
          });
        _refresher = options.GetRefresher();

        _timer = new Timer(async (o) =>
        {
          await Program._refresher.Refresh();
        }, null, TimeSpan.FromSeconds(30), TimeSpan.FromSeconds(30));
      });
    });
  }
}

In our background worker we must change IOption to IOptionMonitor to be able to detect the changes when a setting is changed in App Configuration.

public CustomerWorker(IOptionsMonitor<ProcessingSettings> settings)
{
  settings.OnChange((settings) => {
    _settings = settings;
  });
  _settings = settings.CurrentValue;
}

The OnChange method will here be triggered every time the Refresh() function will detect new values in App Configuration

Conclusions

That’s all we need to do. We’re all hooked up to the App Configuration service and every time the settings are being changed there, our Worker Service will pick it up within 30 seconds without needing a restart. This is a very neat functionality that you probably should implement whenever possible.

Re-throwing exceptions - the right way

johan.ohlin@outlook.com (Johan Ohlin) — Fri, 02 Aug 2019 00:00:00 +0000

In the company where I work we have an interview question for candidates where we ask them to explain the difference between different ways to re-throw an exception in a C# try-catch expression. How hard can it be? Well, surprisingly many developers get it wrong.

The questions looks something like this:

In the code for MyBrokenFunction below, three different ways to re-throw an exception are shown. Explain the difference between the three different options, what we’ll see in the catch section in the Main function, and which one is the best to use.

using System;
using System.Diagnostics;

namespace ThrowErrorExample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                MyImportantFunction();
            }
            catch (Exception e)
            {
                // Log error or something
                Debugger.Break();
            }
        }

        static void MyImportantFunction()
        {
            try
            {
                var value = Divide(10, 0);
            }
            catch (Exception ex)
            {
                // Log exception or something

                // Option 1
                throw ex;

                // Option 2
                throw;

                // Option 3
                throw new Exception("Failed to do something important", ex);
            }
        }

        static double Divide(int a, int b)
        {
            return a / b;
        }
    }
}

Do you know which one you would choose? Well, let’s go through the different options one by one.

Option 1

In this example we re-throw the same exception object that is passed in into the catch clause.

try
{
    var value = Divide(10, 0);
}
catch (Exception ex)
{
    // Log exception or something
    throw ex;
}

It looks straight forward, but it has a major drawback. Re-throwing the same exception object resets the stack trace so we won’t be able to see the original error.

at ThrowErrorExample.Program.MyImportantFunction() in C:\Users\me\ThrowErrorExample\Program.cs:line 32
at ThrowErrorExample.Program.Main(String[] args) in C:\Users\me\ThrowErrorExample\Program.cs:line 12

By looking at the StackTrace, it looks like the exception started on line 32 and we have no information about earlier problems. The error message is “Attempted to divide by zero” which is absolutely correct, but the message is somewhat confusing since we have no direct code that is making any divisions.

This example is quite easy, but if you have a complex hierarchy with many layers of code, then you might have lost valuable information about where the problem was caused.

Option 2

In the second example we simply throw without specifying what we throw.

try
{
    var value = Divide(10, 0);
}
catch (Exception ex)
{
    // Log exception or something
    throw;
}

The result in the stack trace is different from the previous one and we see no references at all to line 32 where the throw statement is.

at ThrowErrorExample.Program.Divide(Int32 a, Int32 b) in C:\Users\me\ThrowErrorExample\Program.cs:line 44
at ThrowErrorExample.Program.MyImportantFunction() in C:\Users\me\ThrowErrorExample\Program.cs:line 25
at ThrowErrorExample.Program.Main(String[] args) in C:\Users\me\ThrowErrorExample\Program.cs:line 12

Instead we see the full stack trace back to the line where the original problem occurred. As in the previous option, the error message is “Attempted to divide by zero”, and here it makes more sense if we also look at the stack trace.

Option 3

The final option is that we wrap the exception in a new exception, maybe a domain specific version that contains more information about the problem.

try
{
    var value = Divide(10, 0);
}
catch (Exception ex)
{
    // Log exception or something
    throw new Exception("Failed to do something important", ex);
}

The stack trace in the caught exception will the look like

at ThrowErrorExample.Program.MyImportantFunction() in C:\Users\me\ThrowErrorExample\Program.cs:line 38
at ThrowErrorExample.Program.Main(String[] args) in C:\Users\me\ThrowErrorExample\Program.cs:line 12

We have no information here about the original exception, the same problem as we had for option 1, but this time we have an inner exception as well with its own stack trace.

at ThrowErrorExample.Program.Divide(Int32 a, Int32 b) in C:\Users\me\ThrowErrorExample\Program.cs:line 44
at ThrowErrorExample.Program.MyImportantFunction() in C:\Users\me\ThrowErrorExample\Program.cs:line 25

This inner exception points us all the way back to the original exception source.

The first exception had the message specified when we created the new exception, but the inner exception had the original message

Conclusions

Looking at the examples above, it’s quite clear that option 2 is the preferred choice and option 1 should be avoided. Option 2 is also the default expression when you use the existing code snippets in Visual Studio.

Most developers we interviewed picked option 1 as their primary choice and option 2 as their second. If it’s something I’ve learned from these interviews then it’s that guessing based upon logic won’t always take you in the right direction.

Develop with CosmosDB in Docker

johan.ohlin@outlook.com (Johan Ohlin) — Fri, 05 Jul 2019 00:00:00 +0000

Micro services are increasingly more popular in new development project. In this post I’ll show you how to connect to a CosmosDB emulator from your docker app.

CosmosDB emulator on host

The CosmosDB emulator is locked down to localhost by default. To allow calls from within the docker cluster you need to open up for network access. This is done by adding the AllowNetworkAccess parameter at startup. You also need to specify a new access key. The key needs to be a Base64 encoded 64 character long string, like this one.

A custom startup script for the CosmosDB emulator could look like this:

`1`	`"c:\Program Files\Azure Cosmos DB Emulator\CosmosDB.Emulator.exe" /AllowNetworkAccess /Key=YWJjZGVmZ2hpamtsbW5vcHFyc3RhYmNkZWZnaGlqa2xtbm9wcXJzdGFiY2RlZmdoaWprbG1ub3BxcnN0YWJjZA==`

To connect to the CosmosDB emulator from your docker app you can’t use localhost:8081 anymore since that refers to your docker instance and not the host machine. Instead, if you’re using a newer version of docker, then you can use https://host.docker.internal:8081 to connect to CosmosDB.

If you have an older version of docker then you’ll need to connect by IP which works just as fine.

CosmosDB emulator as docker container

Another way to run the CosmosDB emulator locally is to run it as a container and Microsoft is providing a prepared solution for this. There are different ways to configure your container and you can find more information about it on the docker image page.

For a basic scenario you can run the following commands to setup a container.

cmd
set containerName=azure-cosmosdb-emulator
set hostDirectory=%LOCALAPPDATA%\azure-cosmosdb-emulator.hostd
md %hostDirectory% 2>nul
docker run --name %containerName% --memory 2GB --mount "type=bind,source=%hostDirectory%,destination=C:\CosmosDB.Emulator\bind-mount" --interactive --tty -p 8081:8081 -p 8900:8900 -p 8901:8901 -p 8979:8979 -p 10250:10250 -p 10251:10251 -p 10252:10252 -p 10253:10253 -p 10254:10254 -p 10255:10255 -p 10256:10256 -p 10350:10350 microsoft/azure-cosmosdb-emulator

This will download an image of around 10Gb in size so make sure you have a good internet connection. A few things to note for this setup:

It will bind the ports used by CosmosDB from the container to your host machine. This means that you shouldn’t try to run the emulator on the host itself.
CosmosDB emulator will generate a certificate to a local folder. The command binds that local folder to %LOCALAPPDATA%\azure-cosmosdb-emulator.hostd. From your host machine you’ll be able to access this new certificate together with a powershell script to help you import this certificate.
A container named azure-cosmosdb-emulator will be created. If you try to run the last command a second time you’ll get an error. Instead, use the commands docker start azure-cosmosdb-emulator and docker stop azure-cosmosdb-emulator to handle your container.

Browsing to the emulator explorer

Since we linked port 8081 when starting the emulator container earlier on, we can now browse the emulator explorer just like we would when running the emulator on the host machine using the address https://localhost:8081/_explorer/index.html.

Using the right Windows container version

When I started to build this solution my Windows host only supported Windows containers of version 1803. This turned out to be a problem due to a bug which in some situations set the UTC time to be UTC-8 hours (Redmond time, hmmm?). In my case it caused the CosmosDB emulator (or maybe the client) to fail all calls since it only allows a time skew of 15 minutes. There was apparently quite some written on Internet about this (always nice to know you’re not the first one encountering this problem) and the solution was either to change how docker run executes the container or to upgrade Windows to higher version. The former solution would prevent me from using Visual Studio Docker tools and wasn’t a preferred option. I therefore opted for a Windows upgrade.

The current windows container being used in these examples is mcr.microsoft.com/dotnet/core/aspnet:2.2-nanoserver-1903 and the time bug has been fixed here.

Conclusions

Installing the docker image for CosmosDB Emulator includes a lot of fuss. It works just fine to connect to a standard Windows installation from the docker app so my recommendation is therefore to keep it simple.

Configuration providers in ASP.NET Core

johan.ohlin@outlook.com (Johan Ohlin) — Tue, 02 Apr 2019 00:00:00 +0000

Configuration providers in ASP.NET Core offers a pluggable architecture for using many different sources for your app settings.

This post builds upon two previous posts concerning basic configuration and injecting options.

Configuration providers

The configuration can be read from several different providers. These providers all provide key-value pairs of data that will be merged together.

Provider	Provides configuration from	Applied by default
Azure Key Vault Configuration Provider	Azure Key Vault	No
Command-line Configuration Provider	Command-line parameters	Yes
Custom configuration provider	Custom source	No
Environment Variables Configuration Provider	Environment variables	Yes (prefixed only)
File Configuration Provider	Files (INI, JSON, XML)	Yes
Key-per-file Configuration Provider	Directory files	No
Memory Configuration Provider	In-memory collections	No
User secrets (Secret Manager)	File in the user profile directory	Yes

Not all of these are applied by default. Some has to be manually configured and enabled. You can read more about how that’s done here{:target="_blank" rel=“noopener”}.

When more than one configuration service is enabled, the last configuration source specified wins and sets the configuration value.

Hierarchical configurations

Most providers handle configurations as key-value pairs. To mimic the hierarchical structure we have in the internal configuration object, the keys can describe a path instead of just a key. By default : is used to separate levels in hierarchy. However, in some environments a colon has other meanings as well and this can cause issues. It’s therefore recommended to use __ (duble underscore) instead.

This key example

`1`	`(Logging__LogLevel__Default = Info)`

Would then map to the following configuration setting

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  }
}

File Configuration

The built in support allows you to import JSON, XML and INI files into your configuration. Read this blog post for examples of how to use the standard appsettings.json file for defining your configuration.

ASP.NET Core also searches for a settings file with the current environment in the name, as in appsettings.{Environment}.json. The environment specific configuration file is imported after the generic one and will thus override the generic values.

The pre-defined environments are Development, Staging and Production, but you can specify environments yourself if needed. These environments are written with the first character as upper case and the rest lower case. This is important if you are using the code in case sensitive environments, i.e. Linux.

Environment Variables

Per default, only environment variables prefixed with ASPNETCORE_ will be included. The prefix will be removed before the variables are used in the hierarchy. The prefix can be changed to a custom string if needed (see example here).

To match the content of this appsettings.json file

{
  "FirstServiceSettings": {
    "AnotherSetting": 14,
    "StringSetting": "maybe"
  }
}

You need to write the environment variables this way

`1`	`ASPNETCORE_FirstServiceSettings__AnotherSetting=25`

If you use Azure and specify app settings for your web app then these will be injected (and have the priority) as environment variables. When you click Save, the Azure App will be restarted and after that the changed environment variables will be available for the app.

Customization

If you need to customize the orders in which the providers are processed (since an imported value will override any previously imported values) then you can change this in the Program.cs file. The following example shows how you can override and reconfigure the existing configuration.

public class Program
{
  public static void Main(string[] args)
  {
    CreateWebHostBuilder(args).Build().Run();
  }

  public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
    .ConfigureAppConfiguration((hostingContext, config) =>
    {
      var env = hostingContext.HostingEnvironment;

      config.SetBasePath(Directory.GetCurrentDirectory());
      config.AddXmlFile("settings.xml", optional: false, reloadOnChange: false);
      config.AddJsonFile("application.json", optional: false, reloadOnChange: true);
      config.AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true, reloadOnChange: true);
      config.AddEnvironmentVariables("ASPNETCORE_");
      config.AddCommandLine(args);
    })
    .UseStartup<Startup>();
}

It’s important to set the base path as the first step so the files will be searched for in the right place.

Injecting Options in ASP.NET Core

johan.ohlin@outlook.com (Johan Ohlin) — Sun, 31 Mar 2019 00:00:00 +0000

In ASP.NET Core there are some very interesting ways of handling and injecting options into classes. In this post I compare some of the different options you have at your disposal.

In a previous post I wrote the basics about how to configure options in ASP.NET Core. If you’re not familiar with this topic then I suggest you read through that blog first.

Comparison

There are a few different ways to handle option injection in your classes. They are all quite straight forward to use.

Interface	Automatic reloading	Works in a singleton service
IOption	No	Yes
IOption Monitor	Yes (but you have to hook into change event)	Yes
IOption Snapshot	Yes (re-calculated for each call)	No

IOption

If your options change seldom and you’re OK with restarting your app (or application pool) when you change your app settings then this could be your choice. Options are read at startup and there’s no overhead for re-reading the file or watching for changes for every request.

public class MyService
{
  private readonly MyServiceSettings settings;

  public MyService(IOptions<MyServiceSettings> options)
  {
    settings = options.Value;
  }
}

IOptionMonitor

This option keeps an eye on the file and calls OnChange when the file is changed. This makes it possible for you to make changes to your application.json file without having to reload the app.

public class MyService
{
  private MyServiceSettings settings;

  public MyService(IOptionsMonitor<MyServiceSettings> options)
  {
    settings = options.CurrentValue;
    options.OnChange(OnSettingsChange);
  }

  private void OnSettingsChange(MyServiceSettings settings)
  {
    this.settings = settings;
  }
}

IOptionsMonitor has a caching layer behind the scenes that stores the values. You can interact with this caching layer to clear the cache, forcing an update, but also to inject new values if needed. This will then trigger the OnChange event to be triggered in code where used.

IOptionSnapshot

The last option gives us the possibility to re-read the settings file for every new request. No need to handle change requests since you’ll always have a new file.

This is a scoped service and can’t be accessed from a singleton service. This might not be a problem to you, but it’s good to keep in mind. IOptionMonitor works just fine in a singleton.

public class MyService
{
  private readonly MyServiceSettings settings;

  public MyService(IOptionsSnapshot<MyServiceSettings> options)
  {
    settings = options.Value;
  }
}

IConfiguration

It’s also possible to inject the whole configuration object into your class.

public class HomeController : Controller
{
  private readonly SecondServiceSettings _settings;

  public HomeController(IConfiguration configuration)
  {
    _settings = new SecondServiceSettings();
    configuration.Bind("SecondServiceSettings", _settings);
  }
}

This is not recommended since it’ll break the separation of concerns that you should only have the options available that you need.

Which one to choose

If you read Microsoft’s documentation{:target="_blank" rel=“noopener”} you can see that most focus is being put on the IOptionMonitor alternative. This is probably due to the interaction possibilities you have with it. However it comes with the need to write a few extra lines of code to make use of the change requests.

IOption and IOptionSnapshot are also good options but they offer less functionality, which still might be good enough for your needs.

Configuration in ASP.NET Core

johan.ohlin@outlook.com (Johan Ohlin) — Mon, 25 Mar 2019 00:00:00 +0000

Configuration in your app can sometimes be a pain. Some values are set in code, some are extracted from the environment in which you’re running and some are secret and can’t be defined anywhere near a repository. ASP.NET Core helps you manage all these settings in a very smooth way

ASP.NET Core has a pluggable configuration system where configuration settings can be imported from a number of different sources. These sources are then merged together into one hierarchical configuration object.

When you create a new ASP.Net Core Web App in Visual Studio, it’ll automatically create a configuration file for you named appsettings.json. By default it only contains logging and CORS settings but we’re free to add any type of hierarchical configuratin that we need.

In this example I’ve added two extra sections (FirstServiceSettings and SecondServiceSettings) to the file that I’ll use as specific option groups for my web app.

{
  "FirstServiceSettings": {
    "AnotherSetting": 14
  },
  "SecondServiceSettings": {
    "MinRetries": 2,
    "MaxRetries": 40,
    "CostPerRetry": 0.02
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

Options pattern

Settings are grouped together as classes in what’s called the options pattern. By separating options you can decouple different parts of your app so it only knows the settings it needs to know, in accordance with the theory of separation of concerns{:target="_blank" rel=“noopener”}.

It’s not mandatory to create options classes for your options but it’s something you should consider. Here’s an example of a few settings classes that we’ll use in the examples through out this post.

public class FirstServiceSettings
{
  public string StringSetting { get; set; }
  public int AnotherSetting { get; set; }
}

public class SecondServiceSettings
{
  public int MaxRetries { get; set; }
  public int MinRetries { get; set; }
  public decimal CostPerRetry { get; set; }
}

Since the JSON file example previously shown only is one of many possible configuration providers, it’s not needed to include all the settings you need for your option classes. The JSON file might specify some basic values while a secrets manager brings in passwords.

Map classes to configuration

In the merged configuration settings, each option group that match a class is seen as a sub-option in the main hierarchy. In Startup.cs we therefore need to map a path to each of the option classes.

public Startup(IConfiguration configuration)
{
  Configuration = configuration;
}

public IConfiguration Configuration { get; }

public void ConfigureServices(IServiceCollection services)
{
  services.Configure<FirstServiceSettings>(Configuration.GetSection("FirstServiceSettings"));
  services.Configure<SecondServiceSettings>(Configuration.GetSection("SecondServiceSettings"));
  // ...
}

The option classes are now registered and we can use them in the code by [injecting them using dependency injection]({{ site.baseurl }}{% post_url 2019-03-31-injecting-options-in-aspnet-core %}).

Make options read-only

One problem with these option classes is that they are not read-only and can be changed locally where used (but still not globally). It is not possible for the configuration binder to set properties without a setter, but you can define the setter as private and still set these properties.

In this option class example below, both the public property with a private setter as well as the private property will be set with the values from the configuration settings.

public class ProtectedSettings
{
  public string HiddenSetting { get; private set; }
  private string VeryHiddenSetting { get; set; }
}

The default behaviour is to not change private properties, but by specifying the BindNonPublicProperties option you can override this behaviour.

public void ConfigureServices(IServiceCollection services)
{
  services.Configure<ProtectedSettings>(Configuration.GetSection("ProtectedSettings"), options =>
  {
    options.BindNonPublicProperties = true;
  });
  //...
}

The option values are now protected later on.

Configure options using a delegate

It’s also possible to set the configuration options in code by using a delegate.

services.Configure<SecondServiceSettings>(myOptions =>
{
  myOptions.MaxRetries = 55;
});

If you want to use both delegate and the configuration object when you set the values from the settings class you have to write a little extra code. The example below shows two ways of accessing specific values in the configuration object.

services.Configure<SecondServiceSettings>(delegateSettings =>
{
  delegateSettings.MaxRetries = 55;

  // Deep link to values one by one
  delegateSettings.MinRetries = Configuration.GetValue<int>("SecondServiceSettings:MinRetries");

  // Get the whole settings object and set them one by one
  var settings = new SecondServiceSettings();
  Configuration.Bind("SecondServiceSettings", settings);
  delegateSettings.CostPerRetry = settings.CostPerRetry;
});

You can of course also use a model mapper like AutoMapper, but we’re here quite early in the startup process so you might not want to do that here.

The delegate is not executed until the value object is requested in the injected option.

public class HomeController : Controller
{
  private readonly SecondServiceSettings \_secondSettings;

  public HomeController(IOptionsSnapshot<SecondServiceSettings> secondSettings)
  {
    _secondSettings = secondSettings.Value;
  }
  //...
}

In the example above, line 7 would trigger the delegate in the configuration.

More information

More detailed information about other useful scenarios can be found on the Microsoft Docs site under the topics options{:target="_blank" rel=“noopener”} and configuration{:target="_blank" rel=“noopener”}.

AutoMapper profile injections

johan.ohlin@outlook.com (Johan Ohlin) — Mon, 18 Mar 2019 00:00:00 +0000

I am a big fan of Jimmy Bogard’s AutoMapper. It helps you focus on solving your problem. But once in a while you encounter mapping scenarios that just are a bit more complex and can’t be solved out of the box.

I have a scenario in a system with subscriptions where each subscription can have different levels. In the domain model, I only store the subscription level id, but in the view model I’d like that to be translated into the actual name for the level.

For simplicity, I’ve only included the relevant properties in the models and code below.

public class SubscriptionDomainModel
{
    public int Id { get; set; }
    public int SubscriptionLevelId { get; set; }
}

public class SubscriptionViewModel
{
    public int Id { get; set; }
    public string SubscriptionLevelName { get; set; }
}

The default AutoMapper profile can handle all properties having the same name and type

public class SubscriptionViewModelProfile : Profile
{
    public SubscriptionViewModelProfile()
    {
        CreateMap<SubscriptionDomainModel, SubscriptionViewModel>();
    }
}

But the SubscriptionLevelId property needs custom code to be mapped - a resolver. Here are two different approaches to how that can be solved.

Resolving a static list

If the list of subscription levels is contained in code and accessible through a synchronous call then you can add an AutoMapper resolver and inject the class containing the list directly into it.

Here’s the simplified service containing the levels.

public interface ISubscriptionLevelService
{
    List<SubscriptionLevelDomainModel> GetSubscriptionLevels();
}
public class SubscriptionLevelService : ISubscriptionLevelService
{
    public List<SubscriptionLevelDomainModel> GetSubscriptionLevels()
    {
        return new List<SubscriptionLevelDomainModel> {
            new SubscriptionLevelDomainModel {
                Id = 1,
                Title = "Basic subscription"
            },
            new SubscriptionLevelDomainModel {
                Id = 2,
                Title = "Premium subscription"
            },
        };
    }
}

We can now create a resolver and inject the service into it for object lookup

public class SubscriptionLevelResolver : IValueResolver<
    SubscriptionDomainModel,
    SubscriptionViewModel,
    string
>
{
    private readonly ISubscriptionLevelService _service;
    public SubscriptionLevelResolver(ISubscriptionLevelService service)
    {
        _service = service;
    }

    public string Resolve(SubscriptionDomainModel source,
        SubscriptionViewModel destination,
        string destMember,
        ResolutionContext context
    )
    {
        var levels = _service.GetSubscriptionLevels();
        if (levels.Any(x => x.Id == source.SubscriptionLevelId))
        {
            return levels.Single(x => x.Id == source.SubscriptionLevelId).Title;
        }
        return $"Unknown level ({source.SubscriptionLevelId})";
    }
}

Finally, in the mapper profile we can now specify that the SubscriptionLevelId should be resolved using the new resolver.

CreateMap<SubscriptionDomainModel, SubscriptionViewModel>()
    .ForMember(d => d.SubscriptionLevel,
        opt => opt.MapFrom<SubscriptionLevelResolver>()
    );

Resolving an async service

So far so good. But what if your service makes an async call to database or cache to fetch a list of subscription levels? AutoMapper has no support for async calls due to the complexity that would bring to the usage of reflection and expression trees. You therefore have to solve this another way. My suggested solution is to inject the subscription level list when you do the mapping.

Injection of values is done by using the AutoMapper context. In the resolver, you can use the Items dictionary inside the context to send variables. In our solution, it could look like this:

public class SubscriptionLevelResolver : IValueResolver<
    SubscriptionDomainModel,
    SubscriptionViewModel,
    string>
{
    public string Resolve(
        SubscriptionDomainModel source,
        SubscriptionViewModel destination,
        string destMember,
        ResolutionContext context)
    {
        var levels = context.Items["SubscriptionLevels"] as List<SubscriptionLevelDomainModel>;
        if (levels != null && levels.Any(x => x.Id == source.SubscriptionLevelId))
        {
            return levels.FirstOrDefault(x => x.Id == source.SubscriptionLevelId)?.Title;
        }
        return $"Unknown level ({source.SubscriptionLevelId})";
    }
}

When requesting the mapping you now have to pass along the list of subscription levels.

var subscriptionViewModel = _mapper.Map<SubscriptionViewModel>(
    subscription,
    opt => opt.Items["SubscriptionLevels"] = subscriptionLevels
);

This works fine, but I’m not really happy with the way the list is passed in - it’s quite easy to forget to pass in the list and it’s also possible to misspell the key in the dictionary. To make it a bit more visible, you can add an extension method to the mapper that asks for a list when you try to do this specific mapping.

namespace AutoMapper
{
    public static class AutoMapperExtensions
    {
        public static SubscriptionViewModel Map<SubscriptionViewModel>(
            this IMapper map,
            SubscriptionDomainModel domainModel,
            List<SubscriptionLevelDomainModel> subscriptionLevels
        )
        {
            return map.Map<SubscriptionViewModel>(domainModel,
                opt => opt.Items["SubscriptionLevels"] = subscriptionLevels);
        }
    }
}

The extension is added to the AutoMapper namespace so it’ll be available each time you use the Map function. This is how you now can call the function, and it even comes up as one of the suggested ways.

var subscriptionViewModel = _mapper.Map<SubscriptionViewModel>(
    subscription,
    subscriptionLevels
);

Summary

AutoMapper is a really helpful tool when you need to map different data classes. The resolver makes it possible to convert complex scenarios and you can even inject services to use when converting. However, async is not supported in the resolver so you have to call async functions before and pass in the values you need.

Building a computer desk for the treadmill

johan.ohlin@outlook.com (Johan Ohlin) — Fri, 04 Jan 2019 00:00:00 +0000

Once in a while I have the opportunity to work from home. These days I barely leave the house due to the cold and rainy weather here in UK. It would be great if I could walk and work at the same time! I’ve seen some people buy a treadmill desk that seems to work really great. But these also cost a small fortune (£1500 - £3000). I already have a treadmill and decided to build a simple laptop desk with things I could find at a local DIY store (B&Q).

The total cost for legs, a shelf and some brackets ended up at £35. Many DIY stores can cut longer pieces of wood into the size you want, and for free (B&Q have this service).

To make the legs really stable I carved out a little from the them before attaching the cross-beam

Legs are ready and the glue is drying

The brackets cost only £2.50 each and give a much needed stability to the table

Since I have a Surface Pro laptop I need a little support at the back so the kickstand wont fall off the table.

The desk isn’t so deep, mainly because this was the only suitable shelf size they had in the store that was wide enough. The table would probably be more stable if desk was deeper and legs further apart on each side, but this chosen solution works well for me and the table can stay where it is even when the treadmill is raised up.

In the picture above, the table looks quite high. But when you stand on the treadmill you’re quite high up as well so it works really well when using it.

So, my desk is completed and it actually works really well to use. I was a little worried while building it that it would be somewhat wobbly. But that hasn’t been the case. It isn’t as fancy as the bought ones and I can’t lower or raise the table, but it surely is much more affordable to build it yourself. I recommend to give it a try.

Practical flexbox examples

johan.ohlin@outlook.com (Johan Ohlin) — Fri, 09 Nov 2018 00:00:00 +0000

The Flexbox CSS styling of web sites is gaining more and more popularity. This post is not a complete overview of what you can do with flexbox but rather a gathering of different flexbox techniques that I’ve found useful over the years.

In the initial examples below I’ll assume the following HTML snippet as a base.

<div class="sectionWrapper">
  <div class="sectionContent">Section longer 1</div>
  <div class="sectionContent">Section 2</div>
  <div class="sectionContent">S 3</div>
  <div class="sectionContent">Section 4</div>
</div>

Basic flexbox layout

Use flex-direction to swap between row and column. This indicates direction of items.

.sectionWrapper {
  display: flex;
  flex-direction: row;
}

If you line up container divs (i.e. rows in a grid) then you need to think to opposite - the attribute column means your container becomes rows, one of top of the other, in a column.

Fill space

As seen in the previous example, the divs are not filling up the whole row. This can be solved by increasing the space between the items using justify-content.

.sectionWrapper {
  display: flex;
  justify-content: space-between;
}

The result would look like this

Other options instead of space-between are space-evenly, space-around, flex-start and flex-end

Another way to fill the row is to increase the size of the divs which can be done by adding the flex-grow property.

1
2
3

.sectionContent {
  flex-grow: 1;
}

The divs are now distributed all over the row.

In a practical example we simulate four lists with drag-and-drop behaviour where the purple sections show the droppable areas. However, by default the divs only fill up the area where you have items inside them, which can make a column like S2 difficult to drop items into.

By adding flex-grow: 1 for the purple droppable div, we solve this problem.

The same technique can be used to push a footer at the bottom of a page, or a card. Simply let the middle content of the item have flex-grow:1 and the footer will be pushed down to the bottom

Fill space with same size for all divs

By default, flex-basis is set to auto to adjust for the different size of the elements inside, as can be seen here.

To make all columns have the same width we need to set the flex-basis, forcing all columns to have the same base.

.sectionContent {
  flex-grow: 1;
  flex-basis: 0;
}

The result will then look like this

Align content in center

Horizontal alignment has always been easy through auto margin. But vertical alignment has been a pain and always forced me to google it. With flex box style it’s so much easier.

.centerContent {
  display: flex;
  align-items: center;
  justify-content: center;
}

This is how the titles (and other parts) in the above examples got centered in the middle of the divs

Separate items

Normally, the divs are separated by the same amount of space. But by tweaking the margin, you can change that behaviour.

.sectionWrapper {
  display: flex;
  flex-direction: row;
}
.sectionContent {
  margin: 10px;
}
.sectionContent:last-child {
  margin-left: auto;
}

Divs overflowing on next row

By default, when flex-direction is set to row then all items are displayed on a single row. To wrap items on several rows, use the flex-wrap setting.

.overflowingList {
  display: flex;
  flex-direction: row;
  flex-wrap: wrap;
}

Any neat Flexbox snippets you think I should add?

Do you have any good suggestions of useful Flexbox examples that you think I should have added? Please write them to the comments below.

Sending emails with web hooks in Azure Function and Sendgrid

johan.ohlin@outlook.com (Johan Ohlin) — Sun, 05 Aug 2018 00:00:00 +0000

Sometimes you might need to send emails from an Azure Function, maybe a status email to admin or a notification to a user. In this example, I show you how to create an async function that can send SendGrid emails. By letting the function be triggered by an HTTP call you can easily connect other Azure function or flows and send emails as needed.

Create function

Create a new C# function with an HTTP trigger. Authorization level can be specified to function so it’s protected from unwanted calls. The function is also protected by HTTPS by default.

Replace the default code with the following snippet.

#r "SendGrid"
using System;
using System.Net;
using SendGrid.Helpers.Mail;

public static async Task<HttpResponseMessage> Run(
    HttpRequestMessage req,
    IAsyncCollector<Mail> mailCollection,
    TraceWriter log
)
{
    try
    {
        var email = await req.Content.ReadAsAsync<Email>();
        var message = new Mail
        {
            Subject = email.Subject
        };

        var personalization = new Personalization();
        personalization.AddTo(new Email(email.To));

        Content content = new Content
        {
            Type = "text/html",
            Value = email.Body
        };
        message.AddContent(content);
        message.AddPersonalization(personalization);
        await mailCollection.AddAsync(message);

        string msg = $"Sent email with subject '{email.Subject}' " +
                    "to Administrator";
        log.Info(msg);
        return req.CreateResponse(HttpStatusCode.OK, msg);

    }
    catch (Exception e)
    {
        string msg = $"Failed to send email with subject " +
                      "'{email.Subject}' to Administrator";
        log.Error(msg);
        return req.CreateResponse(HttpStatusCode.BadRequest, msg);
    }
}

public class EmailStructure
{
    public string To { get; set; }
    public string Subject { get; set; }
    public string Body { get; set; }
}

Update bindings

Click on View Files to the right and open the function.json file. Update the bindings to include the SendGrid configuration as in the example below. Note that the field apiKey should contain the text SendGridAttribute.ApiKey because it’s referring to an app setting for the function rather than the actual api key itself.

{
    "disabled": false,
    "bindings": [
    {
        "authLevel": "function",
        "name": "req",
        "type": "httpTrigger",
        "direction": "in",
        "methods": ["post"]
    },
    {
        "name": "$return",
        "type": "http",
        "direction": "out"
    },
    {
        "name": "mailCollection",
        "type": "sendGrid",
        "direction": "out",
        "apiKey": "SendGridAttribute.ApiKey",
        "from": "sender@mycompany.com"
    }]
}

Configure SendGrid

Configure a SendGrid service in Azure. The free tier allows you to send 25 000 emails a months which is more than enough for this sample application. After you’ve setup SendGrid in Azure you need to login to the SendGrid portal to create an API key. You can access this portal by clicking on the Manage button inside your newly created Azure SendGrid account.

Add application setting

Open Application Settings for the Function App (not the individual function, since many functions can run in a Function App). Add the application setting SendGridAttribute.ApiKey with the key you’ve created in the SendGrid system.

Get URL and send test email

Open the newly created Azure function and click on the Get function URL button. Select Function key and copy the URL created. Now you can send POST message with the following JSON data structure.

{
    "To": "some.person@some.email.com",
    "Subject": "Email alert",
    "Body": "Someone is sending you emails!"
}

Custom themes in Office UI Fabric for React

johan.ohlin@outlook.com (Johan Ohlin) — Wed, 01 Aug 2018 00:00:00 +0000

In a recent project, I’ve started to use Office UI Fabric as component library for a React application. This is an interesting piece of Microsoft work - who knew they would ever create open source React components?

The components are well made, but the documentation is lagging behind in good examples, a bit like the MSDN documentation - full of property specifications, but few fully fledged examples.

One neat piece of functionality when working with themes for Office UI Fabric is the Theme Generator. It gives you the possibility to specify your colours of choice and see the theme generated shades.

If I were to wish for something here it would be the possibility to define a secondary colour as well to create a complementary matching pair based on the colour wheel. However, that’s not how this theme works and you’re stuck with a monochromatic solution. The focus of this component library is to be functional and simplistic - something it does succeed well with.

The colours you’ve chosen are also analysed based upon how well they work together. A contrast ratio of less than 4.5 is pointed out and you are recommended to go back to the colour selection to pick other colours.

The theme generator produces different outputs for you to use, but for embedding themes into React applications the JSON option is the best. In the official documentation you can read about how themes can be imported and used. However, something is wrong in their examples, it just doesn’t work. Instead I had to do in the following way.

import { getTheme, loadTheme } from '@uifabric/styling';
import * as React from 'react';

loadTheme({
  palette: {
    "themePrimary": "#1490ef",
    "themeLighterAlt": "#f5fafe",
    "themeLighter": "#d7ecfd"
  }
});

class App extends React.Component {
  private theme = getTheme();

  public render() {
    return (
      <div className="App">
        <h1 style={\{color: this.theme.palette.themePrimary} }>It works</h1>
      </div>
    );
  }
}
export default App;
```

One important step here is that `getTheme()` is called inside a component. It doesn't necessarily have to, but the order in which things are called make a difference and `loadTheme()` has to be called before you call `getTheme()`. When all files are merged together, it's not easy to know in what order things are being loaded. But when you put the call inside the component, then you know for sure it'll happen after `loadTheme()` has been called.

These theme details, including other Office UI Fabric configurations, can then also be used if you need to integrate with styling frameworks like [Glamor](https://github.com/threepointone/glamor) or [Aphrodite](https://github.com/Khan/aphrodite).

The example below shows how an Aphrodite style can include pre-defined font styles as well as theme colours. Notice how the font is a collection of settings and has to be added using the spread operator.

```csharp
import * as React from 'react';
import { getTheme } from "@uifabric/styling";
import { StyleSheet, css } from 'aphrodite';

export const createStyles = () =>
{
  const theme = getTheme();

  return StyleSheet.create({
    header: {
      ...(theme.fonts.xxLarge as any),
      backgroundColor: theme.palette.themePrimary,
      color: theme.palette.white,
      padding: '20px'
    }
  })
}

export class HeaderComponent extends React.Component {
  private styles = createStyles();
  public render() {
    return (
      <header className={css(this.styles.header)}>
        Header for page
      </header>
    );
  }
}
```

There are many ways to structure your embedded CSS styles. By creating a separate `createStyles()` function you can easily separate it into its own style file, if you prefer such structure.

Diving into Azure

Create your own VS Code codespace using a custom build box

Setup the build VM

Generate key with password

Create SSH Key in Azure

Create VM

Create VM with Azure CLI

On new VM

Install docker

Install .Net 5 SDK and runtime

Install Azure CLI

Setup your local work computer

Configure SSH

Configure VS Code

Create a sample application

Conclusions

Using SGR5 in Windows Terminal

Deploying a worker service to Kubernetes

Create docker image

Push docker image to a container registry

Creating a Helm chart for deployment

Kubernetes health checks

Kubernetes deployment

Following the results in Kubernetes

Conclusions

Worker services in Kubernetes with health checks

Setting up the worker service

Adding a health check endpoint

Conclusions

Next article

Using Azure App Configuration in a Worker Service

Configure Azure App Configuration

Creating a new Worker Service project

Conclusions

Re-throwing exceptions - the right way

Option 1

Option 2

Option 3

Conclusions

Develop with CosmosDB in Docker

CosmosDB emulator on host

CosmosDB emulator as docker container

Browsing to the emulator explorer

Using the right Windows container version

Conclusions

Configuration providers in ASP.NET Core

Configuration providers

Hierarchical configurations

File Configuration

Environment Variables

Customization

Injecting Options in ASP.NET Core

Comparison

IOption

IOptionMonitor

IOptionSnapshot

IConfiguration

Which one to choose

Configuration in ASP.NET Core

Options pattern

Map classes to configuration

Make options read-only

Configure options using a delegate

More information

AutoMapper profile injections

Resolving a static list

Resolving an async service

Summary

Building a computer desk for the treadmill

Practical flexbox examples

Basic flexbox layout

Fill space

Fill space with same size for all divs

Align content in center

Separate items

Divs overflowing on next row

Any neat Flexbox snippets you think I should add?

Sending emails with web hooks in Azure Function and Sendgrid

Create function

Update bindings