Forem: Jim Mc̮̑̑̑͒G

How to save an audio file from Twilio Media streams to Azure storage.

Jim Mc̮̑̑̑͒G — Mon, 25 May 2020 08:37:18 +0000

This article was originally published at blogs.siliconorchid.com on 26-March-2020

In this article, we'll combine Twilio Media Streams and a .NET Core 3.1 Web App, to save a copy of a telephone conversation as a .wav audio file to Azure Storage.

Introduction

In July 2019, Twilio announced their new service "Media Streams" was available in public beta.

Twilio Media Streams are a really interesting service that further bring together the worlds of telephony and mainstream software development.

The Twilio service provides a way to stream the audio content of a live phone conversation into our own services.

What we then choose to do with this, is down to our own creativity - but suggested examples have been to integrate with voice-recognition and AI-related services such as sentiment-analysis etc.

If you're someone who just wants to see the code, skip straight over to my GitHub : SiliconOrchid/TwilioMediaStreams

Requirements

This article is not intended for beginners and assumes that you already have intermediate experience using:

C#, .NET Core and experience working with .NET Core Web Applications.
An account with Twilio and familiarity using the Twilio dashboard.
An account with MS Azure and experience with creating Azure resources.

If you are an existing .NET developer, but new to .NET Core, you may find resources such as the following useful:-

Microsoft : Get started with .NET Core using the .NET Core CLI

Microsoft : Dotnet New

This article has been produced on a Windows 10 system using VS2019 Community Edition. It has not been written to provide alternative guidance for users of other OS or IDE.

What will we be doing?

Create a webhook (an HTTP "handshaking" endpoint)

When we purchase a phone number from Twilio, their API platform allows us to define instructions to "do something" when that number is interacted with.

For this project, we want to instruct the Twilio service that when a user calls our number, we want to do the following:

read a brief message to the user
wire-up the call to a service that can receive Twilio Media Streams.
maintain the call for 60 seconds (unless the caller hangs up)

We achieve this by:

Providing a "webhook" (an HTTP endpoint) that the Twilio service is configured to request when a call is made to the Twilio number. This endpoint will return a set of instructions that are formatted in Twilio's bespoke TWIML format. That TWIML will look similar to the following:

<Response>
    <Start>
        <Stream url="yourWebhookUrl"/>
    </Start>
    <Say>Please record a message.</Say>
    <Pause length="60"/>
</Response>

Create a websocket service

Our solution will require us to provide a websocket service that will receive a stream of encoded byte data from Twilio.

Twilio provides this stream as a sequence of websocket messages, which are wrapped as JSON documents. You should read the official documentation about this subject here at Twilio : Voice Streams : Websocket Messages.

These documents contain various pieces of meta-data, but ultimately contain a payload of binary data encoded as base64 which represents part of the audio data. We need to:

Provide a websocket service for our ASP.NET website. We implement this using ASP.NET Core Middleware.

Tip: If you've not worked with websockets before, don't confuse the use of the word "streaming" with any experience you may have working with .NET streams (e.g. MemoryStream). Data transmitted using websockets is decomposed into discrete text-based packages called "messages" - it may help you to better picture what's going on, to think of these as a rapidly-received sequence of HTTP requests.

Create a buffering system

The need to have a buffer depends on our usage scenario. For example, if we are building a service that relays audio data immediately onto another service (e.g. a speech-to-text service), we wouldn't need to buffer any data.

However, in our demo scenario, we are writing a file to a storage medium. To do this, we need to have the complete file available to us.

We achieve this by buffering the received data in server memory until the transmission has ended.

A slight complication to this process is that unlike a regular HTTP handler (whether that be MVC or WebAPI), where a scoped instance of a Controller class handles a single request, our WebSocket middleware will be a singleton instance, dealing with multiple connections.

Because of this, we need a way to separate data being simultaneously received from different connections.

If we didn't do this, a single buffer for the single service would receive the data from multiple streams. Pretending for a moment that issues such as security and privacy aren't a concern … crudely, everyone's audio stream could be blended together in a jumbled mess and/or recordings become concatenated.

Create an audio file

Again, if we were simply relaying a stream of data onward to another service, other than defining what the expected encoding of the data should be, we don't need to become involved.

However, for this project, we have tasked ourselves with creating a .wav audio file, so we need to do a little more work. Fortunately, there are open-source libraries that do all the heavy-lifting for us.

We need to produce code that calls a third-party library that will assemble a .wav file of the appropriate encoding format, using the bytearray data previously collected by our buffer.

Create a storage handler

Finally, we want to write our newly-created audio file to cloud storage.

For the purpose of this article, we'll be using an Azure Storage account to save the blob

Primary resources/references

Primary resources that we will be building upon include:

Twilio have provided sample code for use with a number of tech-stacks and a selection of articles:

Twilio : TwiML Voice: (Beta)
Twilio's GitHub.
(Example using Node.js) : Twilio : Live transcribing phone calls using twilio media streams and google speech-to-text
(Example using Java) : Twilio : Transcribing phone calls using twilio media streams with Java, Websockets and Spring Boot

I would also recommend reading these articles by Jon McGuire, as aside from explaining many of the issues and problems we need to consider, he also talks about some of the frustrations that he found, as relates to the availability of documentation and learning resources:

Heads-up : Working with websockets in .NET isn't quite as straightforward as you might expect.

If you're a seasoned .NET developer and you hear about the topic of "websockets", your instinct may likely steer you in the direction of SignalR.

SignalR is terrific, but it solves a different problem. SignalR can be thought of as a wrapper of several technologies - of which websockets represent a major component. It primarily serves the purpose of connecting web-browser clients to a back-end service. Other problems it solves include the maintenance of robust connections and the use of fallback techniques to enable browsers that don't natively support websockets, to still benefit from real-time connections.

For Twilio Media Streams, we need to use websocket connections in a server-to-server configuration. SignalR isn't the right tool for that job.

What makes developing a websocket solution more difficult than it needs to be, is that most resources related to using websockets in .NET either direct us towards SignalR or don't provide examples that would be appropriate for enterprise use.

Regardless, the key to getting this working is that we need to create ASP.NET Core middleware that manages the websocket connections and implements any specific functionality that we require.

You can read more about middleware here at Microsoft : ASP.NET Core Middleware

Use NGrok whilst developing external-facing web services.

I recommend (as does Twilio in their many articles) using the tunnelling/proxy utility NGrok during development.

NGrok is super-useful as it lets us run our web server locally, whilst exposing our endpoints publically to the internet, using a subdomain of ngrok.com.

For development and testing the integration of our service, with other services such as Twilio, this is a time-saving godsend, as it means that we can quickly iterate and debug, without having to mess around with firewalls and port-forwarding on our router.

My recommendation is to follow the instructions in this article Twilio : How to use ngrok with Windows and Visual Studio to test webhooks, which will take you through the steps needed to install and use it.

Briefly, once NGrok is installed:

we will need to know both the exact local Url and Port number of our locally-hosted development service.
use the ngrok command as below. Note that:
- we specify only the hostname and port
- we do not specify the protocol (i.e. no "http://" etc)
- we do not specify any Url fragments.

ngrok http -host-header="localhost:5000" 5000

Gotcha : Update NGrok to latest version. I wasted hours on this project, assuming that my own code wasn't working, when in fact I was being caught out by a glitch in an older version of NGrok. Briefly, the symptoms where :

the client could connect and send messages to the server successfully.

The server was unable to broadcast messages back to any of the connected clients.

I was previously using NGrok v2.2.8 and the problem was resolved by updating the local NGrok client to v2.3.35 (latest at time of writing)

Let's get started!

Create Azure Resources

I recommend that we create a separate Resource Group to organise the resources of our project. You can read about that at Microsoft : Manage Azure Resource Manager resource groups by using the Azure portal

To develop this project we only require an Azure Storage account

You will need the Azure Storage connection string later, so for convenience, you should keep the portal open in the background, so you can easily cut+paste these settings later. The storage connection string can be found in the "Access Keys" section.

If you plan to deploy your project to an Azure App service, this may be a convenient time to also create that resource now - but we will only be testing using a local copy in this article.

Get a Twilio Phone number and configure the webhook

If you don't already have a Twilio number that you can use for testing purposes, you should go ahead and obtain one now. The following resources will help you here:

When you have your phone number, you should set the webhook to match the domain of our Azure WebApp endpoint. In this demo, we will call that route that GET method to the route /handshake, so go ahead and enter a Uri that looks similar to this:

https://yourwebapp.azurewebsites.net/handshake

Create the project

Template a new solution

Use Microsoft templating to create a new API ASP.NET Core 3.1 web application. For the demo, we will name it TwilioMediaStreams. We can leave the default options selected, such as SSL support.
Add references to the following NuGet packages (versions indicated were those used at time of writing):
- NAudio v1.10.0 (Mark Heath & Contributors)
- WindowsAzure.Storage v9.3.3 (Microsoft)
Remove any default template-generated items, such as "weatherforecast":
- /Controllers/WeatherForecastController.cs
- /WeatherForcast.cs
For convenience, you may also prefer to change the default launchUrl settings in launchSettings.json from "weatherforecast" to "handshake".
There is code in the startup.cs file that was added during templating, that we won't need to use. Therefore edit the code so that it looks like the following: (for simplicity just cut+paste the following):

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

namespace TwilioMediaStreams
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            app.UseHttpsRedirection();
            app.UseRouting();
            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }
}

Set up configuration

In this demo, we'll be using the commonly used IOptions pattern to provide configuration. You can read more about configuration in my article Introduction to .NET Core configuration

In the root of the project, create a new folder Models
In this new folder, create a new class ProjectSettings.cs and populate it like this:

namespace TwilioMediaStreams.Models
{
    public class ProjectSettings
    {
        public string TwilioMediaStreamWebhookUri { get; set; }
        public string AzureStorageAccountConnectionString { get; set; }
        public string AzureStorageAccountContainerName { get; set; }
    }
}

Edit appsettings.json so that it includes the following configuration section:-

  "ProjectSettings": {
    "TwilioMediaStreamWebhookUri": "wss://yourappname.azurewebsites.net/ws",
    "AzureStorageAccountConnectionString": "DefaultEndpointsProtocol=https;AccountName=yourStorageAccount;AccountKey=yourKey;EndpointSuffix=core.windows.net",
    "AzureStorageAccountContainerName": "filecontainer"
  }

You should go ahead and copy in the configuration settings that correlate to the Azure resources you created earlier. You can change the "ContainerName" to something else if you prefer.

Gotcha: Do not use capital letters in your filecontainer name.

Finally, modify the class startup.cs so that the configuration model is registered, like this:

public void ConfigureServices(IServiceCollection services)
{
    services.Configure< TwilioSettings>(Configuration.GetSection("TwilioSettings"));
    services.AddControllers();
}

Create webhook for Twilio to use

When your Twilio phone number receives a call, Twilio will need a "webhook" to provide further instructions to their service.

These instructions take the form of "TWIML", which is an XML document that we need to supply.

We do this by creating a simple REST method

Create a new empty API Controller class called BasicController and add the following code:

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Options;
using TwilioMediaStreams.Models;

namespace TwilioMediaStreams.Controllers
{
    [ApiController]
    public class BasicController : ControllerBase
    {
        private readonly ProjectSettings _projectSettings;

        public BasicController (IOptions<ProjectSettings> projectSettings)
        {
            _projectSettings = projectSettings.Value;
        }

        [HttpGet]
        [Route("/handshake")]
        public IActionResult HandShake()
        {
            return Content($@"<Response><Start><Stream url=""{_projectSettings.TwilioMediaStreamWebhookUri}""/></Start><Say>Please record a message.</Say><Pause length=""60""/></Response>", "text/xml");
        }
    }
}

Gotcha: Make sure to define the content-type of text/xml - Twilio doesn't like plain text, even if that text happens to be valid TWIML.

Finally, pay attention to the line [Route("/handshake")] - this route needs to match the endpoint that we identified as the webhook in the Twilio control panel.

Recreate the WebsocketManager project

For our project, we're going to use an implementation of a websocket manager by Radu Matei.

You can read about this project at Creating a WebSockets middleware for ASP .NET Core 3

There technically exists a NuGet package for this project, but it hasn't been updated recently and doesn't play nicely with .NET Core 3.x. Also, that package includes dependencies on Newtonsoft.Json, that we don't want to bring into our project, because we're using the System.Text.Json library instead.

However, Radu has updated his project on GitHub to .NET Core 3.x, so we'll be using that version of the code instead.

Within the TwilioMediaStreams solution (not the web app project of the same name), create a new .NET Standard 2.0 Class Library project, naming it WebsocketManager.
Create four classes named as follows. Cut+Paste the entire code, for each of the linked GitHub pages:
- WebSocketConnectionManager.cs ⭠ Get the raw code from GitHub
- WebSocketHandler.cs ⭠ Get the raw code from GitHub
- WebSocketManagerExtensions.cs ⭠ Get the raw code from GitHub
- WebSocketManagerMiddleware.cs ⭠ Get the raw code from GitHub
Finally, make a project reference to WebsocketManager, from the MediaStreamSandbox web app project by right-clicking on the project and going "add > reference".

Scaffold the code of our project

We'll start by creating the structural outline of our project. Later in the article, we'll return to flesh-out the details, along with any necessary explanations.

Within the TwilioMediaStreams web project, create a new folder called Services.
Within the Services folder, create a new class called MediaStreamHandler and populate it with the following code:

using System;
using System.Collections.Generic;
using System.IO;
using System.Net.WebSockets;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

using Microsoft.Extensions.Options;
using Microsoft.WindowsAzure.Storage.Blob;

using WebSocketManager;
using TwilioMediaStreams.Models;


namespace TwilioMediaStreams.Services
{
    public class MediaStreamHandler : WebSocketHandler
    {
        private readonly ProjectSettings _projectSettings;

        private Dictionary<string, List<byte[]>> dictionaryByteList = new Dictionary<string, List<byte[]>>();


        public MediaStreamHandler(WebSocketConnectionManager webSocketConnectionManager, IOptions<ProjectSettings> projectSettings) : base(webSocketConnectionManager)
        {
            _projectSettings = projectSettings.Value;
        }

        public override async Task OnConnected(WebSocket socket)
        {
            throw new NotImplementedException();
        }

        public override async Task ReceiveAsync(WebSocket socket, WebSocketReceiveResult result, byte[] buffer)
        {
            throw new NotImplementedException();
        }

        private void AddPayloadToBuffer(string socketId, string payload)
        {
            throw new NotImplementedException();
        }

        private async Task OnConnectionFinishedAsync(WebSocket socket, string socketId)
        {
            throw new NotImplementedException();
        }

        private async Task ProcessBufferAsync(string socketId)
        {
            throw new NotImplementedException();
        }

        private byte[] CreateCompleteAudioByteArray(string socketId)
        {
            throw new NotImplementedException();
        }
    }
}

Next, also in the folder Services, create a new class file called StorageHandler.cs and copy in the following code:

using System;
using System.Threading.Tasks;

using Microsoft.WindowsAzure.Storage;
using Microsoft.WindowsAzure.Storage.Blob;

using TwilioMediaStreams.Models;

namespace TwilioMediaStreams.Services
{
    public static class StorageHandler
    {
        public static async Task<CloudBlockBlob> SetupCloudStorageAsync(ProjectSettings projectSettings)
        {
            throw new NotImplementedException();
        }
    }
}

Finally, again still in the Services folder, create a class called AudioHandler.cs and copy in this code:

using System.IO;

using NAudio.Utils;
using NAudio.Wave;


namespace TwilioMediaStreams.Services
{
    public static class AudioHandler
    {
        public static void GenerateAudioStream(byte[] buffer, MemoryStream memoryStream)
        {
            throw new NotImplementedException();
        }
    }
}

The solution file structure should now look like this:-

Layer in the implementation code of our project

Next, let's turn our attention to the detail of the code.

The buffer

If you recall from earlier, we said that we need to buffer data for each websocket connection separately. We address this requirement by using a Dictionary, like this:

private Dictionary<string, List<byte[]>> dictionaryByteList = new Dictionary<string, List<byte[]>>();

We should explain how this is going to be used:

We'll be using the randomly created "websocket id" as the dictionary key.
We'll be receiving small "payloads of data" from the websocket messages data, in the form of byte-arrays.
Byte-arrays are immutable, meaning that we can't simply keep appending new bytes onto the end of a single byte-array (i.e. we could not just use Dictionary<string, byte[]>).
To work around this problem, we use a List<T> to create a "list of byte-arrays".

Starting websocket connections

You should modify the placeholder code in MediaStreamHandler to look like this:

public override async Task OnConnected(WebSocket socket)
{
    await base.OnConnected(socket);
    string socketId = WebSocketConnectionManager.GetId(socket);
    dictionaryByteList.Add(socketId, new List< byte[]>());
}

What's happening here is that when we establish a new websocket connection, we get the id of the connection and create a new entry in the dictionary.

Receiving websocket messages

You should modify the placeholder code in MediaStreamHandler to look like this:

public override async Task ReceiveAsync(WebSocket socket, WebSocketReceiveResult result, byte[] buffer)
{
    string socketId = WebSocketConnectionManager.GetId(socket);

    using (JsonDocument jsonDocument = JsonDocument.Parse(Encoding.UTF8.GetString(buffer, 0, result.Count)))
    {
        string eventMessage = jsonDocument.RootElement.GetProperty("event").GetString();

        switch (eventMessage)
        {
            case "connected":
                break;
            case "start":
                break;
            case "media":
                string payload = jsonDocument.RootElement.GetProperty("media").GetProperty("payload").GetString();
                AddPayloadToBuffer(socketId, payload);
                break;
            case "stop":
                await OnConnectionFinishedAsync(socket, socketId);
                break;
        }
    }
}

This code is run every time we receive a websocket message (so expect this to be triggering continuously when a stream is being received).

You should refer to this part of the technical reference : Twilio : Websocket messages

Briefly, a message sent by Twilio is a JSON string, which contains various pieces of meta information and depending on the type, the payload itself. The Twilio messages are grouped into four main types which can be identified by examining the root-level property event :

connected - Twilio : Connected Message.
start - Twilio : Start Message.
media - Twilio : Media Message.
stop - Twilio : Stop Message .

In our demo code, we parse the JSON using the newer technique that uses System.Text.Json and JsonDocuments (where previously we may have done almost the exact same thing using NewtonSoft.Json and JObject).

Our demo code has switch placeholders for connected and start, but we have decided not to do anything with them. In a more advanced version of the code, we could do things such as dynamically using the media format encoding-type and sample-rate dynamically, but in this demo we have left it hardcoded elsewhere.

The key points to note in the switch block is that :

for media message types, we extract the stringified payload from the message and pass it to another method called AddPayloadToBuffer.
for stop message types, we call the OnConnectionFinishedAsync method which performs processing on the buffer and attempts to clean up.

Adding the payload to a buffer

You should modify the placeholder code in MediaStreamHandler to look like this:

private void AddPayloadToBuffer(string socketId, string payload)
{
    //We convert the base64 encoded string into a byte array and append it to the appropriate buffer
    byte[] payloadByteArray = Convert.FromBase64String(payload);
    dictionaryByteList[socketId].Add(payloadByteArray);
}

Perform tasks when the stream closes

You should modify the placeholder code in MediaStreamHandler to look like this:

private async Task OnConnectionFinishedAsync(WebSocket socket, string socketId)
{
    // extract buffer data, create audio file, upload to storage
    await ProcessBufferAsync(socketId);

    // instruct the server to actually close the socket connection
    await OnDisconnected(socket);

    // clean up buffer 
    dictionaryByteList.Remove(socketId);
}

This method is orchestration code, which triggers the onward processing of the buffer and attempts to clean up resources.

Orchestrate the creation of an audio file and uploading to storage

You should modify the placeholder code in MediaStreamHandler to look like this:

private async Task ProcessBufferAsync(string socketId)
{
    byte[] completeAudioBuffer= CreateCompleteAudioByteArray(socketId);

    CloudBlockBlob blob = await StorageHandler.SetupCloudStorageAsync(_projectSettings);

    using (MemoryStream memoryStream = new MemoryStream())
    {
        AudioHandler.GenerateAudioStream(completeAudioBuffer, memoryStream);

        // make sure the memory stream is returned to its beginning, ready to stream to storage
        memoryStream.Seek(0, SeekOrigin.Begin);

        //upload memory stream to cloud storage
        await blob.UploadFromStreamAsync(memoryStream);
    }
}

The code in this method is largely related to the orchestration of other tasks. Main activities include :

creating a single byteArray from the buffer of many smaller chunks, by invoking the CreateCompleteAudioByteArray method.
setting up the connection to cloud storage.
calling the static method AudioHandler.GenerateAudioStream that generates the audio file.
uploading the audio file, contained in a MemoryStream, to cloud storage.

Flatten the list of audio data chunks into a single bytearray

You should modify the placeholder code in MediaStreamHandler to look like this:

private byte[] CreateCompleteAudioByteArray(string socketId)
{
    //get the relevant dictionary entry
    List< byte[]> byteList = dictionaryByteList[socketId];

    //create new byte array that will represent the "flattened" array
    List< byte> completeAudioByteArray = new List< byte>();

    foreach (byte[] byteArrayin byteList)
    {
        foreach (byte singleByte in byteArray)
        {
            completeAudioByteArray.Add(singleByte);
        }
    }

    //collate the List< T> of byte arrays into a single large byte array
    byte[] buffer = completeAudioByteArray.ToArray();
    return buffer;
}

Implement audio file writer

You should modify the placeholder code in AudioHandler to look like this:

public static void GenerateAudioStream(byte[] buffer, MemoryStream memoryStream)
{
    // define the audio file type
    var waveFormat = WaveFormat.CreateMuLawFormat(8000, 1);

    // use WaveFileWriter to convert the audio file buffer and write it into a memory stream
    using (var waveFileWriter = new WaveFileWriter(new IgnoreDisposeStream(memoryStream), waveFormat))
    {
        waveFileWriter.Write(buffer, 0, buffer.Length);
        waveFileWriter.Flush();
    }
}

This class is responsible for calling the NAudio library to write an audio file into the MemoryStream.

In this class, we hardcode the audio format selection to use MuLaw - this is a standard encoding format used in telephony. Similarly, we hardcode that the audio sample rate to be 8000 (Khz) - which matches the quality provided by Twilio in the Media Stream.

Finally, it's worth mentioning that at no point do we write temporary files to disk - everything is handled as an in-memory stream.

Implement Azure Storage handler

You should modify the placeholder code in StorageHandler to look like this:

public static async Task SetupCloudStorageAsync(ProjectSettings projectSettings)
{
    // new random filename
    string fileName = $"{Guid.NewGuid()}.wav";

    // set container name
    var containerName = projectSettings.AzureStorageAccountContainerName;

    // create storage account object
    CloudStorageAccount storageAccount = CloudStorageAccount.Parse(projectSettings.AzureStorageAccountConnectionString);

    // create storage account client
    CloudBlobClient client = storageAccount.CreateCloudBlobClient();

    // create reference of storage account container
    CloudBlobContainer container = client.GetContainerReference(containerName);

    // create container if it doesn't already exist
    var isCreated = await container.CreateIfNotExistsAsync();

    // set the permissions to blob
    await container.SetPermissionsAsync(new BlobContainerPermissions { PublicAccess = BlobContainerPublicAccessType.Blob });

    CloudBlockBlob blob = container.GetBlockBlobReference(fileName);

    // MIME type used for MULAW wav files,
    blob.Properties.ContentType = "audio/wav";  
    return blob;
}

Register the middleware and finish application configuration

Finally, we need to wire everything together. In the startup.cs code, make the following changes:

using TwilioMediaStreams.Models;
using TwilioMediaStreams.Services;
using WebSocketManager;


public void ConfigureServices(IServiceCollection services)
{
    services.Configure(Configuration.GetSection("ProjectSettings"));
    services.AddControllers();
    services.AddWebSocketManager();
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    var serviceScopeFactory = app.ApplicationServices.GetRequiredService();
    var serviceProvider = serviceScopeFactory.CreateScope().ServiceProvider;

    app.UseHttpsRedirection();
    app.UseRouting();
    app.UseWebSockets();
    app.MapWebSocketManager("/ws", serviceProvider.GetService());
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Test the code

With all the code in place and necessary configuration added, we can now go ahead and test our solution.

If you haven't done so already, you should start NGrok and run our web project locally.
We can now grab our telephone and place a call to our Twilio number.
If things are working correctly, we should hear the message defined in the TWIML that we listed in BasicController.Handshake() (so if you cut+paste the example code exactly, we should hear the message "Please record a message.")
Now that we have established that we have called the correct number, we can amuse ourselves by making a selection of farmyard animal impressions and then hanging-up.

At the point that we hang up the call, our service will generate the audio file and save it to Azure Storage.

We now want to download the file and make sure that everything worked.

There are a couple of ways to view blobs in containers, but a simple way is to navigate to the Storage Account using the Azure portal.

Having selected the storage account, locate and click the option "Storage Explorer (preview)" (which by default can be found near the top of the left-hand blade).
Locate the item "Blob Containers", in the central blade, and expand the option using the caret.
We should see the container that we defined "filecontainer" - click on this.
We should now see a list of any files that have been generated. They will have GUID filenames, but should still be easily recognisable by the ".wav" file extension.
Right-click the file to download.
Play the file using a media player.

Wrapping up

The code provided in this article is "demoware" and is not something to drop into a production system without further work. There are a number of areas that I would suggest focussing on, to improve the project:

Security and authentication
Limiting access to handshake method (e.g. with a token)
Error handling
Unit tests
Using the caller ID
Diligence to security and privacy related to data received from different callers.
Taking better care to ensure that connections are closed and that memory used by the buffer is cleaned up afterwards.
Inspecting the metadata in the start message and setting audio encoding dynamically, based on that information.

Disclosure

No third party (i.e. Microsoft or Twilio) compensate me for my promotion of their services in this article. However, I have been recognised by Twilio as someone who promotes their services and have been titled "Twilio Champion". Additionally, my partner Layla Porter is an employee of Twilio Inc, in the capacity of a developer evangelist. Therefore I have a strong bias to recommend their services.

[Configuration in Azure Functions Series - Part 4] Azure App Configuration and Azure Key Vault

Jim Mc̮̑̑̑͒G — Mon, 09 Dec 2019 10:27:11 +0000

This article was originally published at blogs.siliconorchid.com on 1-Nov-2019

This is part four of a series exploring .NET Core configuration, with an emphasis on Azure Functions. In this article, we look at using other configuration providers in your Azure Function project, specifically Azure App Configuration and Azure Key Vault

In part 1 of this series, we introduce the subject of configuration and review how ASP.NET Core configuration works.

In part 2 of this series, we look at how configuration in Azure Functions (v2) works and talk about some of the issues.

In part 3 of this series, we show how you could include ASP.NET Core configuration into an Azure Function project.

In part 4 of this series, we look at using other configuration services, specifically Azure App Configuration and Azure Key Vault

Overview

Back in part one of this series, we learned that .NET Core configuration is created from multiple sources called Configuration Providers and that these can be combined together in Layers.

Because of the flexibility that this model provides us with, we can take advantage of increasingly specialised services. In this final article of the series, we'll explore two such Azure services that we can integrate into our architecture: Azure App Configuration & Azure Key Vault

Azure App Configuration

You can read the official documentation here: Microsoft Documentation : What is Azure App Configuration?

Azure App Configuration is a cloud service that is used to store non-secret configuration settings in a centralised location. These configuration settings can then be shared between multiple applications, including a global context.

Usually, when researching how to use ASP.NET Core and Azure Functions, a vast majority of the documentation and examples will steer us into storing our configuration settings directly onto the host server (whether this is an Azure AppService or a traditional VM server).

Whilst there is absolutely nothing wrong with this option, for certain systems that comprise of many related, but separate, services (for example, a globally distributed solution of Azure Functions spread across multiple Azure Regions, this can lead to us having to enter copies of exactly the same configuration settings into multiple different places. Usually, where we find duplication, we find a risk of errors being introduced.

The official documentation for Azure App Configuration is really comprehensive and provides tutorials specific to Azure Functions, so we should just go ahead and follow those guides:

Azure Key Vault

You can read the official documentation here: Microsoft Documentation : What is Azure Key Vault?

Azure Key Vault complements Azure App Configuration by being the configurable and secure place that we should use for application secrets.

This option, in particular, is an interesting proposition, as it uses an Azure Active Directory to provide access control to secrets, from both users (i.e. developers) and resources (i.e. an App Service). For example:

The built-in integration with Visual Studio means that if we are working on a project that requires significant security controls, we can perform tricks such as granting developers usage of credentials, without ever directly revealing them.
We can explicitly grant access to a Secret Setting, by a specific Azure resource. Maybe this could be useful to minimize the risk of a credential intended for our production environment, accidentally being used in a development/testing system (e.g. because of a cut/paste mistakes) etc.

The official documentation is good, but unlike with Azure App Configuration, there are no guides that are specific to Azure Functions - so we'll be stepping through some steps to demonstrate how we can integrate Azure Key Vault into a demo project.

You will most likely find these supporting documents helpful.

Let's setup an Azure Key Vault!

This tutorial assumes that we already know how to:

create new Azure Functions projects using our IDE of choice
create new Azure Functions AppService in the Azure Portal
publish our Azure Functions project to Azure.

1) Create a new HTTP-Triggered Azure Function from the templates.

First, create a new HTTP-Triggered Function from the templates. For the purpose of this demo, we can leave everything, including the project and function names, to their defaults (i.e. Function1 etc).

2) Add extension packages

We need to add the following NuGet packages - we can use the Visual Studio package manager, or edit the .csproj file manually like this:-

<ItemGroup>
    <PackageReference Include="Microsoft.Azure.Functions.Extensions" Version="1.0.0" />
    <PackageReference Include="Microsoft.Extensions.Configuration.AzureKeyVault" Version="2.2.0" />
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="1.0.29" />
  </ItemGroup>

3) Create a new Resource Group in Azure

Using the Azure Portal, create a new Resource Group to keep all of the parts of our demonstration together. I used the name SiliconVaultDemoRG, but you can choose your own.

4) Create a new Azure Functions AppService in Azure.

Using the Azure Portal, create a new Function App resource. I used the name SiliconVaultDemoFunctionApp, but you can choose our own. Select the Runtime Stack to be .NET Core, the Region to be near to you, accept the automatically generated StorageAccount, and leave the Plan Type with the default of Consumption Plan.

5) Set AppService to have a System-Assigned Identity

When the AppService has been provisioned, select the Identity option and enable the System Assigned Identity. Make sure that we click Save. This will register the AppService within an Azure Active Directory. We'll be assigning this newly created identity to our Azure KeyVault resource in a few moments.

6) Create a new Azure Key Vault resource in Azure.

Using the Azure Portal, create a new Azure Key Vault. I chose to use the name SiliconVaultDemoKeyVault, but you can choose your own. Select a Region near to you and leave the pricing tier as Standard. Note that this is a paid-for service, but depending on our usage, the costs are relatively negligible - we can check the costs here.
Don't click the create button just yet, and instead select the Next: Access Policy button.

7) Grant permission to the new AppService identity.

Whilst displaying the "Access Policy" view, we should see our own user-identity appear in the current access policy list (the account that you used to log into the Azure Portal). We need to add in the identity of the AppService now.

Click the Add Access Policy option.

Completely ignore the options for Configure from template, Key Permissions and Certificate Permissions.
Click on the Secrets Permission dropdown and choose just the sub-options Get and List.
Click the Select Principle option and in the dialogue that appears, search for the name of the ServiceApp that we created earlier. For me, I added SiliconVaultDemoFunctionApp here.
Click Add to save the new policy record.
Click Review and Create to create the new Key Vault resource (along with the settings).

8) Make a note of service address

With the Azure Key Vault resource now provisioned, go ahead and open the new resource.

Select Overview and look at the dialogue for a DNS Name. For me, this value is https://siliconvaultdemokeyvault.vault.azure.net/. Make a note of this, as we'll be using it in a few moments.

9) Create a new secret setting

Next, Select Secrets option and click the Generate/Import button.

We need to create a new secret setting, so leave Upload Options set to Manual, provide a Name of our-secret and provide a value of:

This is a secret from Key Vault

Leave all other settings at their default (i.e. don't set an expiration date), and go ahead and click the Create button.

10) Add startup code

In our Azure Function project, we need to add startup code which tells our application how to connect to our new Azure Key Vault.

Create a new class in the project called startup.cs, which contains the following code (we will need to substitute the Azure Key Vault URL as necessary):

using Microsoft.Azure.Functions.Extensions.DependencyInjection;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

[assembly: FunctionsStartup(typeof(Startup))]
namespace FunctionApp1
{

    public class Startup : FunctionsStartup
    {
        public override void Configure(IFunctionsHostBuilder builder)
        {
            var config = new ConfigurationBuilder()
                   .AddAzureKeyVault($"https://siliconvaultdemokeyvault.vault.azure.net/")
                   .Build();

            var ourSecret = config["our-secret"];

            builder.Services.AddSingleton(ourSecret);
        }
    }
}

It is worth noting that although our example DI code, above, is deliberately crude, it does still demonstrate how we can go about retrieving the secret-settings just once (at instance startup), rather than repeatedly hitting the Azure Key Vault on each and every function operation (and unnecessarily driving up usage demand and costs, to that resource).

11) Update the http-triggered function code

In the file Function1.cs replace the entire code with the following:

using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;

namespace FunctionApp1
{
    public class Function1
    {
        private readonly string _ourSecret;


        public Function1(string ourSecret)
        {
            _ourSecret = ourSecret;
        }

        [FunctionName("Function1")]
        public  async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = null)] HttpRequest req,
            ILogger log)
        {
            return new OkObjectResult($"We retrieved the following value from Azure Key Vault :  {_ourSecret}");
        }
    }
}

12) Login locally to "Az Functions" CLI

A cool feature of Azure Key Vault is that Active Directory users who have been granted permission to the Key Vault, can develop locally using the secrets stored in the vault. This means that we don't need to specify those values, at all, in the local.secrets.json file.

We can read how to integrate Visual Studio at Microsoft Documentation : Add Key Vault to your web application by using Visual Studio Connected Services

To make this security integration work between Azure Key Vault and the Azure Functions CLI, we first need to make sure that we are logged in. Use the following command and enter the same credentials that we used in the Azure Portal:

az login

You could add other users to the Azure Active Directory, and grant these different users (aka "principles") permissions to view the secrets. That is beyond the scope of this article.

13) Test our local development version.

Making a note of the appropriate HTTP-Triggered Url (for me, this was http://localhost:7071/api/Function1), we should see the secret configuration information pulled from the Azure Key Vault and displayed as an HTTP response, like this:

We retrieved the following value from Azure Key Vault :  This is a secret from Key Vault

14) Deploy code to AppService and test cloud version.

Use "right-click deployment" to publish the app to the Azure Functions AppService that we created earlier. Using the appropriate URL (for me, this was https://siliconvaultdemofunctionapp.azurewebsites.net/), demonstrate that the deployed version also works.

Azure Key Vault References

You can read the official documentation here : Microsoft Documentation : Use Key Vault references for App Service and Azure Functions

With perfect timing, late in the writing process of these articles (Oct 2019), Microsoft announced that Key Vault References in App Service and Azure Functions are now generally available
.

"References" are a convenient improvement over the previous approach (described in the previous section) as it means that we no longer have to explicitly add additional code into our application to read settings from Azure Key Vault.

Instead, we:

continue to use an Azure Active Directory managed-identity for our application (as previously).
where we need to access a secret stored in Azure Key Vault, we can replace the AppService configuration item with a specially formed "Reference String".

You should carefully read the official documentation for "Reference Strings" here, as you are presented with a couple of requirements and a choice of string-style.

There are two ways to write a "Reference String", here are examples of both, based on the example earlier in this article:

@Microsoft.KeyVault(SecretUri=https://siliconvaultdemokeyvault.vault.azure.net/secrets/our-secret/ec96f020xxxxxxxxxxxxxxxxxxxxxxxx)


@Microsoft.KeyVault(VaultName=https://siliconvaultdemokeyvault.vault.azure.net;SecretName=our-secret;SecretVersion=ec96f020xxxxxxxxxxxxxxxxxxxxxxxx)

The Azure Portal provides a convenient "cut+paste" facility, which you may find a convenient option. We can find this screen by clicking, first on the name of the secret and then clicking a second time on the version.

It doesn't appear that Azure Key Vault References can be used for local development. There is no obvious place where the reference string could be used, so we need to stick to using local.settings.json as usual. This exact question has been asked on GitHub quite some time ago, during the beta phase, but at time of writing remains unanswered. I'm sure this will be a useful feature that gets added in the future.

That's all

So, we're finally at the end of the series. If you've managed to read all the way through - congratulations! This series has taken a surprising amount of time to put together, so I really hope that this information is helpful to someone! If you have found it useful, please share this on social media, that way we can increase the chance of others in the developer community possibly finding the answers they've been looking for.

Disclosure

No third party (i.e. Microsoft) compensates me for my promotion of their services in any way.

Thumbs Up

A big thank you to Microsoft ~~Cloud Advocate~~ Azure Functions PM, Anthony Chu for volunteering his time and literally burning the midnight oil to provide a technical review. Some of the stuff I waded into was out of my depth and I really appreciated a voice from within Microsoft to help me out.

Thanks to Twilio Evangelist Layla Porter for supporting me once again, with her document-reviewing talents.

[Configuration in Azure Functions Series - Part 3] Add ASP.NET Core configuration into an Azure Function project

Jim Mc̮̑̑̑͒G — Mon, 09 Dec 2019 10:26:58 +0000

This article was originally published at blogs.siliconorchid.com on 1-Nov-2019

This is part three of a series exploring .NET Core configuration, with an emphasis on Azure Functions. In this article, we look at how we can add ASP.NET Core configuration into an Azure Function project and use IOptions<> to inject strongly-typed configuration objects into our functions.

In part 1 of this series, we introduce the subject of configuration and review how ASP.NET Core configuration works.

In part 2 of this series, we look at how configuration in Azure Functions (v2) works and talk about some of the issues.

In part 3 of this series, we show how you could include ASP.NET Core configuration into an Azure Function project.

In part 4 of this series, we look at using other configuration services, specifically Azure App Configuration and Azure Key Vault

Should you even attempt to use ASP.NET Core configuration, using IOptions<>, in an Azure Function?

This may seem like a very odd question to bring up straight away, especially when this article seems to be presenting a working solution.

However, as a caveat before you rush to try this code out in your own solution, you really need to go into this with your eyes open, as the situation can get muddy very quickly.

If you go ahead and use the code in this article, you'll end up with two somewhat disjointed configuration systems working in parallel. This isn't ideal and will quite likely lead to confusion amongst your development team and conflict within your code.

However, an option that uses file-based configuration may be a solution that works well for some of you, particularly if you are working with a large number of separate configuration items, deployed in a number of different places.

As a reminder from part 1, this series has been written from the perspective of the developer who may already be accustomed to developing with ASP.NET Core, and is wanting to learn about the slightly different way that Azure Functions v2 goes about handling application configuration. This is why we draw parallels to ASP.NET Core throughout this article on Azure Functions.

ASP.NET Core Configuration. In part 1 of this series, we covered how ASP.NET Core provides a relatively flexible system of configuration. Specifically good reasons include:
- a baseline file-based configuration, in the form of the file appsettings.json, that deploys to all environments.
- an abstraction of key-value pairs, that allow us to easily define structured configuration settings using json.
- support for binding of configuration to strongly-typed objects, using the Options Pattern.
- support for easy inclusion of those objects into our own code, using dependency injection of IOptions<>.

Azure Functions Configuration. In part 2 of this series, we covered how Azure Functions were created to address several different requirements; they needed to be simple to use, cross-language and self-contained. They were not intended to require the additional complication of having to setup and configure the host (as we do with ASP.NET Core). We also talked about the fact that the runtime of Azure Functions has baked-in behaviour which means that some aspects of configuration need to be provided in a fairly prescribed way:
- each Function method is defined by an Attribute (that defines its type) that is hardcoded to accept certain parameters which are used by the runtime/bindings. These typically comprise of a setting name rather than the setting value.
- other configuration-settings, that are used within the body of the Function code itself, can be requested as needed, typically using Environment.GetEnvironmentVariable("SomeConfigurationSetting")
- specific to the use of local.setting.json; configuration settings are expected to be located in the Values node as flat key-value pairs. We cannot introduce nested JSON structures within the Values node, nor can we use certain characters to define hierarchy. We can use a single-underscore to provide improved legibility.
- out of the box, because there is no file-based baseline, all configuration needs to be defined repeatedly in different environments. i.e. all of the configuration-settings need to be listed in the local.settings.json - and then repeated again in the Azure AppService configuration. In a more complex distributed system,with duplicate instances of an AppService in multiple different Azure Regions, those configuration-settings need to be duplication for each instance.

Alternatively, if we wanted to share a common source of configuration, a solution that is readily supported, is to use Azure App Configuration (we'll cover this in part 4).

Does this even work?

ASP.NET Core and Azure Functions have approaches to configuration that are compatible - but they don't really coexist together:

We can't supply configuration to the Azure Functions runtime without using the provided method Attributes. As just mentioned, those Function Attributes (usually) dictate that we supply string literal arguments for setting-names, not setting-values. There is no opportunity to take advantage of strongly-typed IOptions<> here.
The baked-in behaviour means that the runtime will only be looking for configuration in the places that it supports, such as local.settings.json. The Azure Functions runtime cannot see configuration from file sources that we define ourselves in the host startup.

To illustrate how this becomes a problem, let's return to the sample code for CosmosDBTrigger, that we looked at earlier in part2 of the series. We're going to try to combine it with an unexpected configuration source. In this code sample, if we replace the CosmosDBTrigger attribute parameter at line 7 with ConnectionStringSetting = "cosmosConnectionString"

For reader convenience, here's that code again with the change highlighted:

public static class Function1
{
    [FunctionName("Function2")]
    public static void Run([CosmosDBTrigger(
        databaseName: "databaseName",
        collectionName: "collectionName",
        ConnectionStringSetting = "cosmosConnectionString",
        LeaseCollectionName = "leases")]
           IReadOnlyList input, ILogger log)
    {
        if (input != null && input.Count > 0)
        {
            log.LogInformation("Documents modified " + input.Count);
            log.LogInformation("First document Id " + input[0].Id);
        }
    }
}

It would now be fair to assume that next, we should add a corresponding setting into the root node of our [ASP.NET Core style] appsetting.json file, like this:-

{
  "cosmosConnectionString": "<an-actual-connectionstring>",
  "anotherUnrelatedConfigurationSetting" : "anotherValue"
}

For the sake of this example, let's assume that this appsetting.json file has been correctly configured in the host startup, using the steps that we'll describe a little later in this article. We should also assume that we haven't confused matters by defining a duplicate of the setting, in a location that is expected, such as local.settings.json. The purpose of this test is to attempt to use, solely, the appsettings.json file.

If we now go ahead and try and run this, the Azure Functions will throw a wobbly, as the runtime does not know about this configuration source, even though we defined it in the host startup.

It's easy to sound flippant when referring to "the baked-in behaviour" of the Azure Functions runtime, but we should be really mindful not to trivialise what Azure Functions, as a wider platform, is actually doing behind the scenes.

According to this GitHub issue, which discusses a scenario that is very similar to the one presented in this article, Microsoft Developer Fabio Cavalcante offered this advice which is totally worth quoting here, as it provides further insight into how the platform works:-

"...some infrastructure pieces, particularly in the consumption model, need to monitor trigger sources and some configuration options that control the Function App behavior. One example of such component is the scale controller.
In order to activate and scale your application, the scale controller monitors the event source to understand when work is available and when demand increases or decreases. Using Service Bus as an example; the scale controller will monitor topics or queues used by Service Bus triggers, inspecting the queue/topic lengths and reacting based on that information. To accomplish this task, that component (which runs as part of the App Service infrastructure) needs the connection string for each Service Bus trigger setup and, today, it knows how to get that information from the sources we support. Any configuration coming from other providers/sources is not visible to the infrastructure outside of the runtime."

How could this approach using supplemental configuration sources be useful to me?

As an example of where additional settings could be useful, let's refer back to the code sample for a CosmosDbTriggered Function, back in part 2. In that example, provided by the MS templates, we can see that there are baked-in settings for wiring everything up to the CosmosDb listener.

It's likely that we'll want our function to perform a task such as adding a message to a completely separate ServiceBus Queue service. To make this work, we would need to supply configuration information relevant to that service. Traditionally at this point, we would be adding multiple separate lines of code into our Function that uses things such as Environment.GetEnvironmentVariable("ServiceBusUrl"); etc.

By instead supplying our Function code with a strongly-typed IOptions<> class, we can benefit from the aforementioned advantages associated with using ASP.NET Core style configuration.

Do I have to use a separate AppSettings.json file?

We can choose any filename we like, it doesn't specifically need to be appsettings.json. If we wanted to, we could even identify local.setting.json as the configuration source and shoehorn-in extra JSON nodes - I really wouldn't recommend doing this though! The key to making this work is to correctly identify the file in the startup class, using .AddJsonFile("appsettings.json", false), which is then read by the host.

However, be mindful that a key reason for adopting this approach is so that we have the option to use appsettings.json as a baseline configuration that can be deployed to different environments.

Dependency Injection in Azure Functions

You can read the official documentation here: Use dependency injection in .NET Azure Functions

The Azure Functions team are always working super-hard on improving the platform. It was announced at Build 2019 that Azure Functions had been updated to support native dependency injection (DI).

In one fell swoop, many of the things possible in ASP.NET Core became available for use in Azure Functions also.

Originally, Azure Function classes were required to be static classes. One of the notable recent changes made to support DI, is that Azure Functions can now be created as instance methods.

This then means that, combined with the new native dependency injection framework, we can inject objects into the constructor of our Function class instances.

Of specific interest to us, is the ability to inject IOption<> objects into out Function classes and work with them, just like we do with ASP.NET Core

Let's do it!

1) Explicitly tell the compiler which version of .NET Core SDK to use

This demo was created using .NET Core v2 - specifically SDK 2.2.402
/ Runtime 2.2.7, which was the last version released, prior to being superseded by the newer .NET Core v3.

When testing this demo, I had recently installed the .NET Core v3 SDK - which had just been made GA (at the time of writing). The default behaviour for the compiler is to use the most recent version of the SDK installed.

Using the .NET Core 3 SDK, I experienced an incompatibility/bug which caused the demo to fail during the build.

Very briefly, it was "blowing up" with the error : Could not load file or assembly 'Microsoft.AspNetCore.Mvc.Abstractions.... I ran out of time attempting to fix this - but this may be a problem which is already resolved, by the time you read this article.

In the meanwhile, to work-around the problem, we need to install and target a specific version of the SDK.

To achieve this:

download and install the last release of the v2.2.x SDK from Microsoft.
after installing, you can verify which SDK's you have installed by using the command dotnet --info
add a new file global.json into the solution-level folder of the demo (i.e. one above the project folder) and edit it with the following:-

{
  "sdk": {
    "version": "2.2.402"
  }
}

2) Set Framework Version and Add Nuget Packages in the project

Update the TargetFramework to netcoreapp2.2 (edit the .csproj)

We use this complete list of packages - versions used as indicated:

Microsoft.NET.Sdk.Functions (v1.0.29)
Microsoft.Azure.Functions.Extensions (v1.0.0)
Microsoft.AspNetCore.App (v2.2.6)

Do not confuse Microsoft.AspNetCore.App with Microsoft.NetCore.App

3) Update `local.settings.json` with a setting

The goal here is not really to use local.setting.json, but it will help to demonstrate that the configuration systems can work side-by-side in certain cases.

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet"
        "LocalSettingValue" : "Setting From local.settings.json"
    }
}

4) Create `appSettings.json` and populate

This will depend on your own project, but this is an example of what the configuration could look like:

{
    "ConfigurationItems": {
        "CommonValue": "Setting From appsettings.json",
        "SecretValue": "Do not save secret values in appsettings"
    }
}

You need to ensure that appsetting.json will be included as a deployable artefact of the build:

If you are using Visual Studio, from Solution Explorer, right-click and select Properties. Under "Copy to Output Directory", select "Copy always".
Alternatively, for developers using other code editors, you can edit the .csproj like this:-

<ItemGroup>
    <None Update="appsettings.json">
        <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </None>
</ItemGroup>

5) Create user secrets

From the Solution Explorer, go ahead and right-click on the project file,
Select "Manage User Secrets". A new secrets.json file will open - populate it with the following code:

{
    "ConfigurationItems": {
        "SecretValue": "Secret Setting From User Secrets"
    }
}

As a reminder from part 1 of this series, behind the scenes, the "Manage User Secrets" option will:

create a new key within the .csproj file, with the name UserSecretsId and a new GUID value.
create a new folder in your OS user-profile which mirrors the GUID. Within this folder, is where you can find the actual secrets.json file - although Visual Studio makes it easy to open this.

6) Create a Model which will bind to configuration

We're going to take our string-based configuration file and bind the values to a strongly-typed object. We should make a model class for this purpose:

    public class ConfigurationItems
    {
        public string CommonValue { get; set; }
        public string SecretValue { get; set; }
    }

7) Create a startup class

A project created from an Azure Functions template is minimal and doesn't include a Startup.cs class, so let's add that in next.

using System;
using System.Reflection;

using Microsoft.Azure.Functions.Extensions.DependencyInjection;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

using FunctionApp1;
using FunctionApp1.Models;

[assembly: FunctionsStartup(typeof(Startup))]
namespace FunctionApp1
{
    public class Startup : FunctionsStartup
    {
        public override void Configure(IFunctionsHostBuilder builder)
        {
            var config = new ConfigurationBuilder()
                   //.SetBasePath(Environment.CurrentDirectory)  ← do not use
                   .SetBasePath(Directory.GetCurrentDirectory())
                   .AddJsonFile("appsettings.json", false)
                   .AddUserSecrets(Assembly.GetExecutingAssembly(), false)
                   .AddEnvironmentVariables()
                   .Build();         

            builder.Services.Configure<ConfigurationItems>(config.GetSection("ConfigurationItems"));

            builder.Services.AddOptions();
        }
    }
}

Take care not to use .SetBasePath(Environment.CurrentDirectory). This is provided in most examples you'll find on the web. This works fine for development, but does not work when you publish to Azure. Instead, you should use this: .SetBasePath(Directory.GetCurrentDirectory())

Also take care not to omit the [assembly: ...] attribute, found adjacent to the namespace section in the example above, otherwise your startup class will not actually be invoked at startup. The project will still build without it though, which could lead to confusion.

If you've been looking at other guides related to this subject on the web,, you may have found code examples which use WebJobsStartup instead of FunctionsStartup and IWebJobsBuilder instead of IFunctionsHostBuilder … these are constructs that come with ASP.NET Core. As far as I can tell, the Azure Functions team has added a Functions variant in mid-April 2019, which looks to be a wrapper of IWebJobsStartup etc - check out the source code for azure-functions-dotnet-extensions.

8) In your Azure Function class

Finally, in our Function class, we can now inject your strongly-typed configuration options, like this:

using System;
using System.Threading.Tasks;

using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Options;

using FunctionApp1.Models;

namespace FunctionApp1
{
    public  class Function1
    {
        private readonly ConfigurationItems _configurationItems;

        public Function1(IOptions<ConfigurationItems> configurationItems)
        {
            _configurationItems = configurationItems.Value;
        }


        [FunctionName("Function1")]
        public  async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = null)] HttpRequest req
            )
        {
            string localSettings = Environment.GetEnvironmentVariable("LocalSettingValue"); // Included so as to demo regular approach
            string commonValue = _configurationItems.CommonValue;
            string secretValue = _configurationItems.SecretValue;

            return new OkObjectResult($"Local Value : '{localSettings}' | Common Value : '{commonValue}' | Secret Value : '{secretValue}'");
        }
    }
}

When working with an IOptions<T> type, don't forget to include .Value to get to the actual configuration settings.

9) Run the program

We should see output like this:-

Local Value : 'Setting From local.settings.json' | Common Value : 'Setting From appsettings.json' | Secret Value : 'Secret Setting From User Secrets'

In the final part of this series, we look at using other configuration services, specifically Azure App Configuration and Azure Key Vault.

NEXT: Read Part 4

[Configuration in Azure Functions Series - Part 2] A deeper dive into Azure Functions configuration

Jim Mc̮̑̑̑͒G — Mon, 09 Dec 2019 10:26:39 +0000

This article was originally published at blogs.siliconorchid.com on 1-Nov-2019

This is part two of a series exploring .NET Core configuration, with an emphasis on Azure Functions. In this article, we review how configuration in Azure Functions is recommended to be used, how it differs from ASP.NET Core and some of the potential issues and confusions surrounding its use.

In part 1 of this series, we introduce the subject of configuration and review how ASP.NET Core configuration works.

In part 2 of this series, we look at how configuration in Azure Functions (v2) works and talk about some of the issues.

In part 3 of this series, we show how you could include ASP.NET Core configuration into an Azure Function project.

In part 4 of this series, we look at using other configuration services, specifically Azure App Configuration and Azure Key Vault

As a reminder from part 1, this series has been written from the perspective of the developer who may already be accustomed to developing with ASP.NET Core, and is wanting to learn about the slightly different way that Azure Functions v2 goes about handling application configuration. This is why we draw parallels to ASP.NET Core throughout this article on Azure Functions.

Configuration, the Azure Functions v2 way

Let's now focus our attention towards Azure Functions.

The starting point for the Azure Function documentation can be found here: Microsoft Documentation: Azure Functions documentation

Unlike the original Azure Functions v1, with the newer Azure Functions v2, we can develop our solution using .NET Core.

Azure Functions v2 can actually be written in a number of different languages, which again illustrates that ASP.NET Core and Azure Functions have evolved over time as different products.

If you are familiar with ASP.NET Core, it may feel appropriate, given the common language and other similarities, that we should just be able to both define and consume configuration in exactly the same way.

However, with Azure Functions this is not the case - it's a totally different runtime - and it often goes about things differently.

For example, as ASP.NET Core developers, our instinct will most likely be to develop the code locally (using an IDE such as Visual Studio or Rider) and ultimately, build and deploy our work someplace (let's assume an Azure WebApp) as a separate process.

In contrast, with Azure Functions, local development is not the defacto workflow. Microsoft's original intent was to create standalone units of code that could be edited directly within the Azure Portal, using a much wider range of programming languages, with the hosting and scaling aspects completely abstracted away.

It is only in the past year, with the release of Azure Function v2, that we now have the option to develop locally, using Azure Functions Core Tools and deploy compiled code to the cloud. The same runtime is used both locally for development and for deployment in the cloud.

We are reminded of these origins, by the fact that we can still take our C# code and copy it into Azure, in the form of C# script (.csx) files.

What does serverless really mean?

If you've looked into Serverless computing before, you'll most likely be familiar with the long-running joke, made by most presenters of Serverless Technology, that "of course there are servers".

From a marketing perspective, the Serverless mantra suggests that self-contained units of code are untethered from our conventional concept of a host (especially when using the consumption model) and that Functions exist in isolation, with everything they need, in terms of configuration, either hard-coded or made available through a simplified configuration system.

We need to clarify that in reality, multiple Functions do in fact, still just run on individual AppService hosts.

Even without modification, it is the host that facilitates the various triggers. If we peek under the hood of the Functions host code we can see that really, it's just an ASP.NET Core app!

There is, of course, much more to Azure Functions than just AppService hosts, as the runtime of the wider platform is aware of which triggers need to be monitored (e.g. monitoring a Service Bus Queue) and manages the appropriate provisioning and scaling of hosts) - but for the purpose of this article, we're only really interested in thinking of a single host in isolation.

As with an MVC/WebAPI application, running on a more conventionally-provisioned and long-running Azure WebApp host, this means that an individual Function can in fact have access to any longer-running services and resources if needed.

We can readily demonstrate this by introducing an appropriate startup class to the project. We can then dive in and write code that does tasks such as setting up our own common services, which then exist for the lifecycle of that host.

By doing this, Functions start to look much more like an ASP.NET Core application running on comparatively short-lived server instances.

A distinction is that unlike ASP.NET Core, Azure Functions effectively have controllers that can be written in a wide range of different languages.

Why do I need to know this?

The relevance of knowing that we have the option to access the host (and that we can configure it, just like any other .NET Core application) is that this means that in theory, we could define alternative configuration-providers.

This opens the door to using the ASP.NET Core style of configuration. We'll be looking at this subject properly, in part 3 of this series.

However, before we start diving into that particular subject, let's back up and talk about how we are supposed to be using configuration, in Azure Functions, under conventional circumstances...

Different types of Azure Function

Let's start by looking into how Azure Functions are used from a high-level.

You can read the official documentation on this subject here: Microsoft Documentation: Azure Functions triggers and bindings concepts

The type of a Function is determined by its Trigger and Bindings.

a trigger is what causes a function to run (e.g. an HTTP-trigger).
the binding is a way to connect the input and/or output of the Function to some other resource (e.g. outputting a result to a queue).

Microsoft provides the platform with support for a wide variety of different Triggers and Bindings.

It's possible to define your own Function types, but that is out of scope for this article. Instead, check out Jason Roberts: Creating Custom Azure Functions Bindings

In code, the type of a particular Function is declared by using a parameterised C# Attribute.

These parameters vary from type to type, but typically they are the place where information related to configuration can be identified.

The following sample of code was produced directly by the template for the CosmosDbTrigger function:-

public static class Function1
{
    [FunctionName("Function1")]
    public static void Run([CosmosDBTrigger(
        databaseName: "databaseName",
        collectionName: "collectionName",
        ConnectionStringSetting = "connectionstringsettingname",
        LeaseCollectionName = "leases")]
           IReadOnlyList input, ILogger log)
    {
        if (input != null && input.Count > 0)
        {
            log.LogInformation("Documents modified " + input.Count);
            log.LogInformation("First document Id " + input[0].Id);
        }
    }
}

At first glance, we could be forgiven for thinking that the above-highlighted code is expecting us to directly hard-code all of the configuration information, including the connection string to the Cosmos Database.

Thankfully, this is not the case, as the values being requested are usually the key-name that correlates to an item in configuration.

It's a mildly ambiguous situation, so it helps to be warned that you need to pay attention to the naming of the parameters. In this example, it doesn't say ConnectionString, it says ConnectionStringSetting.

With that said, it's not uniformly the case that parameters can always be expected to relate to a configuration-key.

In the above example, some of the values (databaseName, collectionName and leases) are expected to be supplied as hard-coded string literal values. We could say that this is not ideal, however, it should be possible to layer-in our own supplemental configuration and replace the string literals demonstrated in line-5, above, with a call to something like this:

databaseName : Environment.GetEnvironmentVariable("<myDatabaseName>")

What are the prescribed configuration sources?

You should refer to Microsoft Documentation: Manage your function app: Application settings.
and Microsoft Documentation: Work with Azure Functions Core Tools : Local settings file

So what can we take away from the docs?

In Azure Functions, there is no baseline configuration which is common to all environments (i.e. no appsettings.json or equivalent).
- If you recall our earlier learning, that not all Azure Function implementations are even deployed from a local development version, then we could say that this is understandable - because the focus has originally been about editing standalone solutions in the cloud, not about deploying multiple versions with different configurations.
Because there is no baseline configuration to be deployed, when hosting in an Azure App Service, we must use App Service Configuration to specify each and every key.
- If we have a relatively large number of configuration items, entering via the Azure Portal is likely to be laborious and error-prone, so automated environment scripting may be an option to improve this issue.
The configuration file for local development is local.settings.json. This is intended for all local settings, including any secrets that we need to use.
- ASP.NET Core normally uses a default builder in the application startup, to enable us to work with appsettings.json. In contrast, when using Azure Functions, the ability to read settings from local.settings.json is an example of behaviour that is baked-into the runtime. This was exemplified in the previous code sample, where, simply by identifying the configuration-item name, this was enough to for the Function to automatically locate and use the appropriate configuration source.
We can still layer-in configuration from other configuration providers, such as Azure App Configuration and Azure Key Vault.

Opinion: Compared to the exhaustive information found in Microsoft Documentation: ASP.NET Core Configuration, the equivalent documentation for Azure Functions, as available at the time of writing, is not as insightful. This is not to say that the documentation isn't useful - I just found it to be somewhat terse, short on links to other resources and doesn't provide a great deal of guidance for beginners.

What do we use for local configuration?

The official documentation Microsoft Documentation: Work with Azure Functions Core Tools: Local settings file
tells us that when developing locally, we should be using local.settings.json.

We are advised that the purpose of local.settings.json is (quote):

"stores app settings and connection strings that are used when running locally. This file contains secrets and isn't published to your function app in Azure."

Summarising from various documents, Microsoft has communicated that:

We should be using the Values section of local.settings.json for our local application settings, secret or otherwise. Here is an example in the docs.
- The runtime supports a handful of expected nodes (e.g. Host and ConnectionStrings are indicated in the docs) and ignore any custom nodes or structures that we include in the file.
- Settings found in this Values node equate to counterparts located directly in the root of an Azure AppService Configuration collection.
- When hosted in Azure, there is no need to attempt to mirror the JSON structure found in local.settings.json by specifying a parent node called "Values". I.e. none of those key-names needs to include any hierarchy delimiters, such as Values__MySetting.

Great. So now we are clear about where we should be saving local configuration settings, right?

Not quite! At this point, the documentation becomes a bit disjointed and suggests a different approach.

According to Microsoft Documentation: Quickstart: Create an Azure function with Azure App Configuration and Microsoft Documentation: Azure Functions C# developer reference, the demonstrated way to store configuration during local development makes no mention of local.settings.json and instead uses Environment Variables.

Environment Variables aren't new to this story, because if you recall from part 1 of this series, they were identified as one of several possible Configuration Providers.

The suggestion to use Environment Variables for local development, was likely intended as a way to maintain consistency with how apps are configured when deployed to the cloud.

Environment Variables are used as a primary configuration choice for Azure Functions because they are consistently available across the various languages and environments that Functions support. For example, you'll find them used in places such as containers.

These instructions show you how to set these values using the CLI for different platforms.

On Windows, you can also access these settings by visiting System Properties → Environment Variables and adding/editing values from there.

But wait, there are even more Environment Settings!

Remember back in part 1, we said that it's easy to be overwhelmed with too many options?

In addition to OS Environment Settings, Visual Studio also provides even more "Environment Settings" for use when debugging:

In Visual Studio Solution Explorer, right-click on the Functions project and select the Properties option.
Select Debug - we are presented with a dialogue box with several options. One of these options is Environment Variables.

If you fill out this section with configuration information, the settings get saved not to the environment-settings of the operating system, but as part of yet another type of configuration file: properties/launchsettings.json.

The file could look like this:

{
  "profiles": {
    "HTTPFunction": {
      "commandName": "Project",
      "environmentVariables": {
        "OurCustomSetting2": "settingsfromVS"
      }
    }
  }
}

Something to watch out for, is that:-

Unlike OS Environment Variables, this file will usually be included in version control - so don't use it to save secrets!
As far as configuration files go, this is probably not an obvious place to expect to find settings, so it's difficult to recommend using this option.

Enough already - what should I use?

Microsoft presents us with several different options for local configuration, so which one should we use?

The answer to that question inevitably stumbles firmly into the usual territory of "it depends, there is no right answer".

I personally would recommend using local.settings.json over Environment Settings, as this is generally more in keeping with documentation and examples. However, this choice is not without other considerations, which we'll talk about next:

What's the issue with local.settings.json?

It's widely accepted that you should not keep secrets in version control.

However, as we discussed earlier, in Azure Functions, Microsoft advises us to use local.settings.json for local secrets. This is a file that is located within a folder that we can normally expect to be version-controlled.

In my opinion, this brings potential complications and compares poorly to alternative options, specifically User Secrets, which locate the file secrets.json in the developers OS user-profile, completely away from the rest of the project code.

If you use a Microsoft template to create a new Azure Function project, it's rather easy to overlook that there is a .gitignore file included in the root of the project. To be clear, this will be in addition to the .gitignore that will quite likely already be present in the root of our solution.

Even more easy to overlook, is the fact that amongst the large list of common-looking exclusions, there is an entry near the top of that file, which is used to explicitly exclude local.settings.json from version control.

In theory, this exclusion addresses the problem of not including the file in version control.

I believe this poses some potential issues:

What happens when someone on your development team is not aware of this subtle exclusion, and then deletes this customised .gitignore from the project (e.g. "why have we got a duplicate of the .gitignore, when we've got the same one correctly at solution level?")?
- Your secrets are at risk of being unintentionally introduced into version control.
If the local.settings.json is not included in version control, and a team member clones the repo to work afresh on the project - how are they easily supposed to know what configuration items are meant to be part of the project's configuration (without having to hunt around)?
- I've seen the answer to this in several demonstration projects - which is to include the file local.settings.sample.json in the project, as a way to convey the configuration schema.
  
  This solution is a somewhat awkward workaround, which as far as I can tell, is undocumented as a recommended practice. It also requires developers to purposefully update this "sample" file, as opposed to updating an actual working version (as we would, if working with an ASP.NET Core appsettings.json)
  
  This problem of "what are the baseline configuration-settings?" is not unique to local.settings.json as it also rears its head, in just the same way, when using Environment Settings.

Opinion: I should stress that the above is just an opinion and that there is nothing wrong with using local.settings.json with its accompanying use of a version-control exclusion rule. It is simply that everyone in our development team needs to be briefed about the nuances and workarounds.

Note: Whilst researching these articles, I discovered that I am pretty late to the game with my learnings, observations and opinions. A concisely written article by Tom Faltesek, covered many of the issues that I wanted to write about, a whole year beforehand (2018).

How do we manually read configuration settings?

We've learned that Function attributes are used as a mechanism to specify certain configuration-settings, which typically are required as binding parameters.

However, there are plenty of other scenarios where we need to request configuration-settings from within the body of our own code. For example, we may want our function to add some information to a queue, so how do we go about retrieving a connection string (to that queue resource) in the body of our Function?

Referring back to those same two documents; Microsoft Documentation: Quickstart: Create an Azure function with Azure App Configuration and Microsoft Documentation: Azure Functions C# developer reference, the demonstrated way to retrieve configuration during local development is to use this piece of code:

var configValue =  System.Environment.GetEnvironmentVariable("<app setting name>", EnvironmentVariableTarget.Process);

This does imply that we need to use a string literal value for the configuration-setting key, everywhere that it needs to be requested. We could say that this is a somewhat brittle way to write code (we all make typos and this kind of bug can be hard to spot).
- One way to slightly mitigate against this, is to use a static class with const strings - as exemplified in this earlier article under the heading "GlobalConstants.cs".
Although the method name GetEnvironmentVariable() sounds like it may only work for retrieving Environment-Variables specifically, this in fact is not the case and this single command can be used to retrieve configuration from all of your sources, whether they be Azure AppService configuration, or the local local.settings.json.

How do we add structure to our configuration settings?

When we talk about configuration sections (aka "Hierarchical values"), we're referring to the ability to group similar pieces of configuration together in groups.

When we are working with ASP.NET Core, with its default use of an appsettings.json file, the structure of such "configuration sections" are clearly visible to both view and work with.

For example, an appsetting.json file could look like this:

{
"EmailSettings": {
     "ApiKey": "secretKeyValue",
     "FromAddress": "do-not-reply@test.com"
     }
}

However, because the use of a JSON file is an abstraction, when we need to work with other configuration-providers, this structure needs to be mapped down into a single string (a basic key/value pair).

This is where things can start to get a little confusing, because the various Microsoft services don't always work in quite the same way.

It's an issue which is further compounded by environment diversity (i.e. Windows, Linux, Containers, etc), so our options for what does and doesn't work will vary.

Usually, hierarchy can be described by using some combination of the delimiting characters : (colon), __ (double-underscore) and/or -- (double-dash).

In most cases, the _ (single-underscore) character can be used to punctuate long strings, to make them more human-readable. This could be used as a way to make related configuration-settings appear to be grouped together (e.g. EmailSettings_ReplyAddress and EmailSettings_ApiKey), but it has no impact other than cosmetic.

Be aware that you may need to experiment, as the official guidance shows there are a mixture of approaches. Let's look at some examples:

ASP.NET Core. In the guide Configuration in ASP.NET Core : Conventions, the following advice seems to be the most encompassing and most relevant for a majority of scenarios (quote):

"Within the Configuration API, a colon separator (:) works on all platforms. In environment variables, a colon separator may not work on all platforms. A double underscore (__) is supported by all platforms and is automatically converted into a colon. In Azure Key Vault, hierarchical keys use -- (two dashes) as a separator. You must provide code to replace the dashes with a colon when the secrets are loaded into the app's configuration.
"

Later in the same document, in the section Environment Variables Configuration Provider, the advice is refined, by noting that the Bash console may not support colons.

"When working with hierarchical keys in environment variables, a colon separator (:) may not work on all platforms (for example, Bash). A double underscore (__) is supported by all platforms and is automatically replaced by a colon."

So, that means that the Azure AppService Application settings that correlates to the JSON example we just looked at, would have keys that look like this (the screenshot demonstrates both the use of a colon and double-underscore):

Azure Functions In the guide Work with Azure Functions Core Tools : Local settings file we are advised that when working with local.settings.json, things don't quite work the same and that we can't describe hierarchy (quote):

" Setting names can't include a colon (:) or a double underline (__). These characters are reserved by the runtime."

It's worth underlining (ahem ;-) ), that in the case of Azure Functions, we can still use the _ (single underscore) character to help to improve legibility. You can see an example of this if we provision a new Azure AppService. Out of the box, it comes with a selection of settings already populated, including for example, FUNCTIONS_WORKER_RUNTIME.

Azure Key Vault. We'll be looking at Azure Key Vault more closely in part 4 of this series, but in the context of this particular topic, it's worth noting that Azure Key Vault introduces its own unique set of restrictions. The advice given in Azure Key Vault Configuration Provider in ASP.NET Core : Secret storage in the Production environment with Azure Key Vault
, is (quote):-

"Azure Key Vault secret names are limited to alphanumeric characters and dashes. Hierarchical values (configuration sections) use -- (two dashes) as a separator. Colons, which are normally used to delimit a section from a subkey in ASP.NET Core configuration, aren't allowed in key vault secret names. Therefore, two dashes are used and swapped for a colon when the secrets are loaded into the app's configuration."

Wrapping up part two

If you're adopting Azure Functions having previously worked with ASP.NET Core, it pays to be aware of the subtle differences. Hopefully, this article will have helped you to navigate this adjustment.

To summarise:

When it comes to configuration, Azure Functions are a little bit opinionated because of baked-in behaviour in its runtime. This applies both to where configuration-settings are expected to be found and also how they should be consumed.
The Azure Functions configuration system doesn't support hierarchical configuration-settings. The various configuration-providers have differing character restrictions for setting-names, so test that your choices can be used in the environments that you intend to use.
Azure Functions still have a host. In the startup, we can define services just as we can like any other .NET Core app.
There are nuances that come with using local.settings.json that your team needs to be aware of.
This article is based upon Azure Functions v2, so may be outdated in the near future as an announcement has been made that Azure Functions v3 is on the immediate horizon, with support for .NET Core 3 having already been rolled out.

In part 3 of this series, we'll look in detail at the code needed to recreate ASP.NET Core style configuration, by being able to read configuration JSON files and inject strongly-typed configuration models into your Azure Functions.

NEXT: Read Part 3

[Configuration in Azure Functions Series - Part 1] Introduction to .NET Core configuration

Jim Mc̮̑̑̑͒G — Mon, 09 Dec 2019 10:24:54 +0000

This article was originally published at blogs.siliconorchid.com on 1-Nov-2019

This is part one of a series exploring .NET Core configuration, with an emphasis on Azure Functions. In this article, we introduce the subject of configuration in general and look at how ASP.NET Core configuration is recommended to be used.

In part 1 of this series, we introduce the subject of configuration and review how ASP.NET Core configuration works.

In part 2 of this series, we look at how configuration in Azure Functions (v2) works and talk about some of the issues.

In part 3 of this series, we show how you could include ASP.NET Core configuration into an Azure Function project.

In part 4 of this series, we look at using other configuration services, specifically Azure App Configuration and Azure Key Vault

Overview

Welcome to this series of four articles where we'll be covering the topic of application configuration, looking at both ASP.NET Core and Azure Functions v2.

The series has been written from the perspective of the developer who may already be accustomed to developing with ASP.NET Core, and is wanting to learn about the slightly different way that Azure Functions v2 goes about handling application configuration.

We'll cover how and why things are different, possible sources of confusion and provide some working examples. In the final part, we'll look at how to integrate powerful Azure services that can help to improve your application configuration.

Throughout this series, please be conscious that we will be referring to the following with deliberate distinction:

.NET (AKA ".NET Framework") is a Windows-only software framework, dating back to 2002.

ASP.NET is a server-side web application framework, that expands upon the original .NET framework.

.NET Core is a higher-performance, cross-platform and open-source software framework, introduced in 2016.

ASP.NET Core is a server-side web application framework, that expands upon the newer .NET Core software framework.

Azure Functions v1 is Microsoft's initial offering of a "serverless" platform, released in November 2016. It supports a number of languages, including .NET, but not .NET Core.

Azure Functions v2 is the second iteration of the "serverless" platform, released in September 2018. It shifted the underpinning software framework from .NET to .NET Core.

Unless specified otherwise, assume that any mention of Azure Functions in this series, relates specifically to v2

Introduction

Configuration - Where have we come from?

If you've worked as a developer using Microsoft technologies for a number of years, it is most likely that you will have developed web applications using the ASP.NET Framework. In which case, you will be familiar with the venerable web.config file.

For the benefit of new developers, it may be useful to know that this configuration system dates all the way back to the release of the original ASP.NET, back in 2002. For a very long time now, it has been the defacto, convention-based, way to manage configuration.

Configuration in a web.config file mixes server settings and application settings together in a file that looks partly like this:-

<configuration>
 <appSettings>
  <add key="connectionString"
   value="Server=localhost;UID=sa;PWD=secret;Database=Northwind" />
 </appSettings>
</configuration>

To access configuration settings in our application code, we would add something like the following, directly in the place where it was needed:

var connectionString = ConfigurationSettings.AppSettings( "connectionString" )

Configuration - Where are we now?

With the 2016 release of .NET Core and ASP.NET Core, the way application configuration was supported changed significantly and, as developers, the scope of what we needed to know about this subject broadened greatly.

This is particularly true when it comes to the topic of "where should different types of configuration information be stored - and where should it not be stored?".

With the relatively recent release of Azure Functions v2 in September 2018, Microsoft shifted from using the .NET Framework, to instead use .NET Core.

For the ASP.NET Core developer in particular, there is now a synergy that makes the adoption of Azure Functions a really appealing proposition.

However, when it comes to the subject of configuration, the shift from ASP.NET Core to Azure Functions isn't entirely frictionless. It is this main theme, that we will attempt to address in this series.

Whilst researching these articles, two observations became apparent:

Although Microsoft promotes a harmonised technology stack, there is a slight lack of cohesion/consistency between their products. This is noticeable when you are familiar with some of the conventions found in ASP.NET Core and arrive at Azure Functions expecting things to work in exactly the same way.
Because there are many options to tackle, what is essentially the same basic task, it's easy to feel overwhelmed with choice.

These observations are truly not intended as a criticism of Microsoft, but it is indicative that their products are created, maintained and supported by a large number of people across several different teams. Furthermore, each product requires many people to create and maintain comprehensive documentation, with a consistent and cohesive message that dovetails with other documents - this alone is not a trivial task!

This series is the outcome of having collated various sources of documentation together. Hopefully it will be a useful guide for developers shifting between, or integrating, the various technologies that we'll look at.

Modern .NET Core configuration, in general

If we distil the subject of configuration down to its most basic concept, the .NET Core libraries provide us with an API that offers a collection of key/value pairs.

Configuration information is combined together from separate layers, from one or more different sources known as Configuration Providers.

Where we require an environment-specific piece of configuration (e.g. a feature switch setting), or secrets (e.g. a sensitive API key to another service), we can supplement or replace a configuration resource with information from additional other sources of configuration.

Configuration Providers are (usually) registered in the initialisation code of our project and locate the required information under the direction of the application and the specific environment within which our program is running.

According to the official documentation, at the time of writing, the list of possible configuration providers include:

Configuration providers (for example Azure Key Vault) are integrated to our project by adding the appropriate Nuget Package and registering that provider into the WebHost Builder in startup.cs class. We'll explain exactly how to go about doing this, in part four of this series.

Configuration, the ASP.NET Core way

You can read the official and in-depth documentation regarding ASP.NET configuration here: Configuration in ASP.NET Core.

When we create a .NET Core WebApp (either MVC or WebAPI) - and assuming that we use the default templates - we'll find ourselves working with a file-based configuration-source called appsettings.json.

Broadly speaking, appsettings.json should be considered as the baseline configuration resource for our web application.

Configuration-settings in appsettings.json are read using the File Configuration Provider - specifically the JSON Configuration Provider.

Use of this file-based source is not a baked-in behaviour of the ASP.NET Core runtime - it is facilitated by calling the method CreateDefaultBuilder from within the application startup code program.cs. This "default builder" loads configuration from the various sources in a certain order - refer to the section
Default configuration for more info.

appsettings.json is structured JSON, so this allows us to freely add groupings to our configuration information. For example:

{
"EmailSettings": {
     "ApiKey": "secretKeyValue",
     "FromAddress": "do-not-reply@test.com"
     },
"FeatureSwitches": {
    "EnableFeatureOne": true,
    "EnableFeatureTwo": false,
     },
}

We can expect appsettings.json to be deployed to all environments. For example, when we build/publish (locally or to Azure), this file is literally copied as a deployment artefact.

Because the configuration is layered, appsettings.json is used first and is then overlaid with replacement values from other configuration providers, such as the User Secrets provider.

N.B. To clarify: when we create those additional configuration resources, we only need to specify the individual keys to be overwritten - we don't need to create an entire copy of each and every item in the baseline configuration.

Which options are commonly used with ASP.NET Core?

We listed all of our choices just a moment ago, but let's look a little more closely at some of the options that are commonly used:-

Environment-specific appsetting variants (file-based sources) such as appsettings.development.json or appsettings.production.json, are an overlay of the baseline file-based configuration. They are used selectively at runtime, depending on the name of the Environment that has been set.

As with the primary file, appsetting.json, these remain intended for non-secret settings and are included in version control.

You can read about environments here at Microsoft Documentation : Use multiple environments in ASP.NET Core.

Environment-specific appsetting variants should not be confused with the similar-sounding Environment Variables. We do however need to define the "environment name" using the Environment Variable ASPNETCORE_ENVIRONMENT.

We can set any name that we like, but the ASP.NET Core framework only natively supports three variants: Development, Staging and Production. If no value is set, Production is used as default.

In development, you will typically find ASPNETCORE_ENVIRONMENT declared in the file properties/launchsettings.json

When we talk about "native framework support", we're referring to the fact that we have built-in features that allow us to react selectively to the stated environment. As examples of how this is consumed, consider this C# code in the startup.cs class and also an example of a Razor tag :-

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

<environment include="Development"><p>Development mode</p></environment>
<environment include="Staging"><p>Staging mode</p></environment>

To make use of these variants, we simply need to include appsettings.development.json or appsettings.staging.json files in our project. We can include appsettings.production.json in our project if we want to purposefully separate production settings from a default baseline configuration.

Tip: If you cannot see these files in Visual Studio, be aware that the Solution Explorer collapses the variants - click the caret next to the file to expand the view:

User Secrets for local development secrets. The secrets.json file is stored outside of our project code, within our Operating System user profile. This keeps it completely away from version control and provides access control via our operating system.

If you aren't familiar with User Secrets, head over to this beginner-friendly article for an introduction and step-by-step instructions.

If you create a new MVC/WebAPI project from the MS templates and right-click on the project file, you will find the option "Manage User Secrets".

If you repeat this exercise, by creating an empty Azure Function (or indeed, just a Console App), you will find the "Manage User Secrets" option doesn't display.

The key to enabling this menu option is the presence of the package Microsoft.Extensions.Configuration.UserSecrets. Adding either this package or the Microsoft.NETCore.App meta-package, to your project, will enable the option in the menu.

Behind the scenes, when you use this menu item, VS will have added a new <UserSecretsId> node and Guid value into your .csproj. At the same time, a new folder that matches the Guid, will have been created inside your user profile. Inside this folder we can expect to find the file secrets.json which will partly mirror the structure of the appsettings.json.
```
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>netcoreapp2.2</TargetFramework>
<AzureFunctionsVersion>v2</AzureFunctionsVersion>
<UserSecretsId>550b1379-cb4e-42ec-aa0c-72a5ac8f3700</UserSecretsId>
</PropertyGroup>
```
```
C:\Users\<your username>\AppData\Roaming\Microsoft\UserSecrets\<UserSecretsId>
```
It is this separation of files, well away from the rest of your source code, that gives us a clear delineation between files that should be secret and those that should be in version control.

Azure AppService Application settings for PaaS cloud deployment. For a majority of scenarios, this is where all of our environment-specific configuration is defined when deployed to an Azure AppService.

If you aren't familiar with Azure AppService Application settings, check out Microsoft Documentation: Configure an App Service app in the Azure portal.

Azure AppService support the concept of separate "deployment slots", which offer us the option of multiple similar environments (e.g. production, UAT and a test versions) - each with slot-specific configuration if required.

Take care not to confuse "Azure AppService Application settings" with the similarly-named "Azure App Configuration", as this is another Azure service. We'll look at this service in part 4 of this series.

With regards to secrets specifically, we could safely add these configuration items into Azure AppService Application settings. There is nothing inherently insecure about doing this (from an external-intrusion perspective) as values are encrypted at rest.

However, a potential concern is that anyone with legitimate permission to access the Azure AppService, will also be able to view these secrets. This may be an issue depending on your organisation (a problem solved by using Azure Key Vault, which we'll look at in part 4 of this series).

Tip: As an alternative to editing values directly into the Azure Portal, this AzureTipsAndTricks article shows us how to update Azure settings, in Visual Studio, when publishing.

Keep it secret. Keep it safe!

The appsettings.json file can be expected to be included in version control, so it must not include secrets (e.g. things such as a database connection string that includes a login credential).

Although the actual secret value should itself not be included in version control, it is recommended that you still retain the configuration-item key in the appsettings.json. Instead of providing the actual secret value, we can add a message with some variant of "do not include here").

By doing this, we can use appsetting.json as a working manifest of sorts, listing all expected configuration items for the project, along with the expected structure. Although we provide unusable key-values, we can trust that this will still work fine, as the actual working values will be substituted at runtime.
This provides a way to clearly communicate amongst your development team, which configuration items are supposed to be present. It also could be said that regularly seeing this message serves to reinforce the need for the development team to think about where they store configuration items.

To illustrate this, an appconfig.json and secrets.json pair could look like this:-

Firstly, the appconfig.json:-

{
"Logging": {
    "IncludeScopes": false,
    "LogLevel": {
        "Default": "Debug",
        "System": "Information",
        "Microsoft": "Information"
    }
},
"ConnectionStrings": {
    "DefaultSql": "Do not specify here. Set in Azure AppConfiguration or User Secrets",
    "AzureStorage": "UseDevelopmentStorage=true"
},
"EmailSettingsConfig": {
    "ApiKey": "Do not specify here. Set in Azure AppConfiguration or User Secrets",
    "FromAddress": "do-not-reply@test.com"
}

Combined with a secrets.json:-

{
"ConnectionStrings": {
    "DefaultSql": "Server=tcp:[serverName].database.windows.net;Database=myDataBase;
User ID=[secretDbLogin]@[serverName];Password=secretPassword;Trusted_Connection=False;
Encrypt=True"
},
"EmailSettingsConfig": {
    "ApiKey": "secretAccountKey"
}

Strongly-typed Configuration models

A really nice feature that ASP.NET Core introduced, alongside the use of appsettings.json, was support for the Options Pattern.

This lets us bind nodes within configuration files to strongly-typed C# objects (models) and then make them available for consumption by our application using the IOptions interface.

By using dependency injection, we can conveniently insert these populated models into the constructor of classes as required. If you are familiar with the subject of unit testing, you will appreciate that this is a very good thing.

Benefits of this way of working include:

It's super easy to organise/group related configuration items together, by using hierarchy to nest them under a parent item in the config file.
The configuration binding code can typically be confined to a single place in our project (e.g. the startup class), avoiding code sprawl.
- String literal bugs (e.g. the silly mistakes that we all make, such as typo's in a key name) are reduced or even avoided. Where they are a problem, they tend to show up sooner in the development process. This is because an error in a centralised part of the codebase tends to be noticed quickly, because it usually impacts many parts of our application. This is when compared to having our wider codebase littered with references to configuration that rely on string literal values.
When we start working with strongly-typed configuration objects, rather than crude string values, we can then start to do useful things such as using dependency injection to insert populated configuration models into our consuming code.

We'll examine the actual code for all of this, in part 3 of this series

Update Nov2019 : Shortly after publishing this article, Steve Collins of stevetalkscode.co.uk reached out, as he has recently been speaking and blogging about the subject of configuration himself. You can find his slide deck here. You may find it useful to explore his blog about configuration-bridging, as it covers the subject of using IOptions<> compared to directly binding an object to configuration.

In part 2 of this series, we look at how configuration in Azure Function works and talk about some of the issues.

NEXT: Read Part 2

Draw sketches from SVG, using Line-us robot and .NET Core Console application

Jim Mc̮̑̑̑͒G — Mon, 28 Oct 2019 10:04:01 +0000

This article was originally published at blogs.siliconorchid.com on 26-Jul-2019

Over the past few months, I've largely been blogging about how to use various cloud services. This is typically the stuff that you could be using in a commercial setting.

Programming is something that can be a hobby for some people, not just a career skill. For this article, I thought we should do something a little different and just play with code for fun. I've chosen to look at something that is IoT related and produces "physically visible" results.

We're going to experiment with a small piece of kit called the Line-us which originated from a 2017 Kickstarter campaign.

Line-us is a device that holds a pen on the end of a small robotic arm and draws doodle-style sketches. The device has built in Wifi and internet-connectivity, making it easy to connect to.

What will we be doing?

For this project, we're going to write a .NET Core Console App that converts an SVG vector image into G-Code.

G-Code is a simple instruction language typically used by industrial CNC machines.

We'll transmit the G-Code instructions, using TCP networking, to the Line-us and sit back as a drawing appears on a piece of paper!

Prerequisites

A Line-us robot
There will be an assumption that you have familiarity working with:
This project uses .NET Core 2.x, so you'll need to have installed the .NET Core 2.x SDK, as appropriate to your platform. .NET Core is cross-platform, which means this project will work on Windows, Mac and Linux.
You'll need something to edit and build your project. This demo was primarily created using .NET Core 2.2 on a Windows 10 system using Visual Studio 2019 Community edition. There is no reason why you cannot use other platforms, code editors and CLI tools - my recommendation would be to use Visual Studio Code.
You'll need to clone the sample code that accompanies this article from here : https://github.com/SiliconOrchid/DrawWithLineUs

The road from photo to robot-drawn sketch

The Line-us is not a printer. It is a line-drawing machine, more akin to a plotter. Everything will be monochromatic and based purely on strokes of a pen on a page.

Your source material will still most likely be a bitmapped image, but there are a number of transformations that this image will need to undergo, before it can be sketched on paper by the Line-us.

Let's overview the steps we need to take:

First, an image needs to be processed into an approximation of a black-and-white line drawing.

You can use an online utility of a photo-editing program for this step.
- A quick search for "online photo to line-art" will return a wide selection of free online conversion tools. I tried both RapidResizer Stencil Maker and Snaptouch Sketch with good results.
- I also used Adobe Photoshop to process a photo. If using a photo-editor, I suggest:
  - start by adjusting the image contrast heavily
  - then apply an "edge-detection" filter.

Next, the processed bitmap needs to be converted into an SVG vector image.

I used the open-source utility Potrace. Be mindful that Potrace only accepts images in the .BMP file format, so you will need to export your modified artwork into this format.
- Using Potrace, I used the command potrace.exe -s lovebird_processed.bmp, where the -s switch is used to declare that you want to output an .SVG file.

Finally, the SVG needs to be converted into G-Code.

Our project will not create a solution that addresses the first two items in the above list - but we will write code to read an SVG file.

The following image is a photo of the actual hardcopy that is produced by the Line-us!

The Line-us coordinate system

Line-us has a small robotic arm, which holds a pen at its end. It can draw on a sheet of paper which is clamped immediately adjacent to the body of the device.

The robotic arm can position the pen in 2-axes of movement (X and Y coordinates). The pen can also be raised or lowered (the Z coordinate) by way of a cam mechanism that moves the body of the unit up and down.

The arm only has a limited range of reach, meaning that although the device can draw in a sweeping arc around the body, the available "rectangular" area is limited to something about the size of a postcard.

The coordinate system originates at the fulcrum of the robotic arm and covers the following range of values :-

X-axis: 0 to 2000 (with only 650 to 1775 in the main drawable area)
Y-axis: -1600 to 1600 (with only -1000 to 1000 in the main drawable area)
Z-axis 0 to 1000 (with 0 being pen-fully-down and 1000 being pen-fully-up

According to the documentation, each 100 units corresponds to 5mm of travel.

The following diagram has been duplicated from the Line-us documentation on GitHub and clearly illustrates the range of motion and the drawable area:-

What is G-Code?

G-Code is typically used to instruct CNC machines (computer-controlled lathes and cutters, etc).

G-Code started life in the 1950's, became standardised in the 1970's and has more recently evolved to support more complex logic, that is required by increasingly advanced industrial machines.

The Line-us however, is a relatively straightforward device and does not have a complex set of drawing features or commands.

The Line-us firmware only supports a small set of G-Code commands, which you can find here:

Line-us G-Code Spec on GitHub

The "language" of the commands is straightforward - for example, if we wanted to reset the pen to a "home" position, we need to send the device nothing other than the command "G28".

In this project, we're going to use a subset of just two commands! These are:-

G00 - Rapid Repositioning - Moves the pen as quickly as possible to new coordinates. In our code, we use this to reposition the pen after a line has been drawn, ready to start drawing the next one. Example G00 X1000 Y1000 Z1000
G01 - Linear Interpolation - This is what we use to draw a line between two points. Example G00 X1200 Y1200 Z0

A limitation to be aware of, is that the Line-us provides no native support for drawing true curves (usually described as beziers). The Line-us can only draw straight lines, directly from one point to another.

In practice however, this doesn't seem to pose a problem for our project, as many SVG source-images will be created from relatively small shapes, meaning that the lack of true curves isn't really apparent. Also, remember that this is a fun toy for drawing "wonky" pictures - it's not meant to be perfect.

Manually test Line-us

Before we get stuck into any coding, we should ensure that our Line-us is working correctly and that we can communicate with it from your computer.

We'll check this by performing a manual test, which will verify that you have a working network connection and that our Line-us is responding to commands as expected.

We're not going to cover the setup and configuration of the Line-us device itself in this article, as there is already ample support provided by the manufacturers documentation and a community forum. For this article, we will assume that we have already successfully added the device to our WiFi network.

We need to know what the local IP address of the Line-us is, so if you haven't already, connect to your network router and make a note of the IP that has been assigned.

Introducing and setting-up Telnet

We're going to use Telnet to communicate with the Line-us during our manual test.

Younger readers, in particular, may not be familiar with Telnet, so briefly, Telnet is one of the oldest protocols on the Internet. It is used to connect to a remote system, over TCP, and provides a bi-directional text-based interface. You tend not to find it used much these days, as it is insecure and has been replaced with SSH

To use Telnet, you will need a Telnet client installed on your system.

Telnet for Windows users A Telnet client is included with Windows, but nowadays is disabled by default. To use it, we'll need to re-enable it.
- In the Windows Start search bar, type "turn win" and select the "Turn Windows Features On or Off" option.
- In the "Windows Features" window that opens, scroll down the list and enable the "Telnet Client" option.
- Windows will install the feature and Telnet will now be available on the command prompt.

Telnet for Mac users The Telnet Client has been removed from recent versions of MacOs.
- Follow the instructions in this guide to install Telnet on a Mac.

When I first encountered Telnet as a teenager, I would use it to connect to "MUDs" (multi-user dungeons) which were online multi-user text-based adventure games!

Connect to the Line-us

With the Telnet client installed, open a command prompt and enter the following command. You will need to substitute the local IP address in the example, with the one you identified from your own router:

Telnet 192.168.1.200 1337

The number 1337 is the port number that Line-us uses by default and must be included.

If the connection is successful, you will hear/see the robot twitch its arm and a message similar to the following will be returned to the console:

hello VERSION:"3.0.0 Feb 10 2019 10:25:48" NAME:line-us SERIAL:155xxxxx

At this point, we are successfully connected to the Line-us in a two-way conversation. The Line-us has accepted our connection, responded with a "hello" and is now awaiting for further instructions.

Start by sending some test commands. Simply enter the following, ensuring that you use capital letters were shown (and press enter):-

G28 - you should see the arm recenter to the home position. The pen will also be raised.
- With the Line-us raised, this is a perfect opportunity to correctly set the pen height. The Line-us instructions recommend placing a UK £1 coin or two stacked US Dimes (which for the benefit of readers in other countries, is approx 3mm thick) underneath the tip of the pen and then tightening the clamp in this position.
G01 X1600 Y-800 Z1000 - this should move the arm noticeably.

If you can see an obvious result, then we're all set to progress.

Quick start to using the code

Aside from a small configuration edit, you should be able to clone the project from GitHub, add the Line-us to your network and just run the code.

Before running the project, open the file ....\DrawWithLineUs\Config\ProgramConfig.cs and update the configuration values.

You will need to change the path to a sample SVG image.
You will need to change the IP address, to whatever your router has assigned to your own Line-us.
If you want to actually send commands to the Line-us, you should set Testmode to be false. Alternatively, if you just want to check that the code works and emits results to the console window, leave it set to true.

Overview of the solution

You should clone the solution from https://github.com/SiliconOrchid/DrawWithLineUs and refer to the code as we go along.

Our C# .NET Core solution is primarily a console app called DrawWithLineUs.

The app can be broadly categorised into the following areas:

Configuration/Enumerations - static classes that contain const fields, for items such as the "drawable canvas area".
Models - classes that are used to model things such as the list of coordinates.
Services - classes that contain the main program logic. Exploring this area further, there are four services that provide the following functionality:
- SVGService - has the job of extracting data from an SVG file and turning it into a list of coordinates.
- GeometryService - is concerned with activities such as determining the extremities of points within an image and calculating an appropriate scaling, so that our image can be resized into the drawable area.
- GCodeService - responsible for converting a list of C# types into appropriate G-Code strings.
- CommunicationService - this class is responsible for handling the network communication and transmitting bytes back and forth between your app and the Line-us.

Designed to use Dependency Injection

The application uses .NET Core's built-in dependency injection.

Services are written so that they implement interfaces. Using the DI framework, the services can easily be added to a class via its constructor. If you are unfamiliar with this type of code, you can learn about Dependency Injection here.

A majority of the code in Program.cs is related to the configuration of the DI system.
Most of the code that relates to the app logic, can be found in the file ConsoleApplication.cs.

Code written in this way, lends itself better to unit testing. The source code comes supplied with a small set of unit tests that can be found in ....\DrawWithLineUs\DrawWithLineUs.Console.Test\

Reading SVG data

Scalable Vector Graphics (SVG) are an open standard which was created by the W3C and dates back to 1999. Unlike other image formats which are binary files, an SVG is nothing more than a text file containing XML. This means they can be readily viewed and edited in any text editor and can easily be read and parsed using .NET libraries.

The SVG description language is extensive and beyond the scope of this article. However, for our purposes, we can focus on a relatively small subset.

There is a huge caveat, regarding the code in this solution, that should be made clear.

This article is intended to be an exploration of the Line-us, so we are not attempting to write a fully-featured SVG parser.

Therefore, we are assuming that we will only be using SVG images that have been created using Path elements. I have only tested using SVG files that are the output from a Potrace conversion (which seems to generate images using only Path elements).

This means that you cannot expect to get results from all SVG files. This is because an SVG file can be created using many different elements, including basic shapes such as Rectangles, Circles, Ellipses, etc.

However, there is absolutely no reason why this project couldn't be forked and expanded upon to support SVG more fully! You could even submit a PR to my repo!

The following code snippet shows the first couple of lines of an example SVG file.

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
"http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
<svg version="1.0" xmlns="http://www.w3.org/2000/svg"
width="850.000000pt" height="650.000000pt" viewBox="0 0 850.000000 650.000000"
preserveAspectRatio="xMidYMid meet">
<g transform="translate(0.000000,650.000000) scale(0.100000,-0.100000)"
fill="#000000" stroke="none">
<path d="M6627 5334 c-13 -13 -7 -23 23 -39 40 -21 50 -19 21 4 l-25 19 30 -5
c20 -4 26 -2 19 5 -13 14 -59 25 -68 16z"/>
<path d="M5360 5695 c0 -9 -4 -13 -10 -10 -5 3 -10 1 -10 -4 0 -6 6 -11 14
-11 17 0 29 27 16 35 -6 4 -10 -1 -10 -10z"/>
<path d="M5440 5665 c-6 -8 -10 -20 -7 -27 4 -8 8 -4 13 10 5 18 9 20 15 10 7
-10 9 -9 9 5 0 21 -13 22 -30 2z"/>
<path d="M6478 5673 c7 -3 16 -2 19 1 4 3 -2 6 -13 5 -11 0 -14 -3 -6 -6z"/>
<path d="M5571 5653 c0 -12 2 -13 6 -5 4 10 8 10 19 1 18 -15 18 -29 -1 -29
-23 0 -18 -16 10 -28 20 -9 23 -9 18 4 -4 10 0 12 11 8 9 -3 2 10 -16 30 -35
40 -48 45 -47 19z"/>

[… truncated for brevity …]

For our purposes, we can disregard entirely the first few lines and concentrate purely on the <path/> nodes. Specifically, we are only interested in the d (data) attribute, so our code will need to be able to parse and extract this information.

Understanding an SVG Path

Mozilla provides an excellent guide to reading SVG Paths

Next, let's concentrate on the structure of the actual data in the <path/>. On first inspection, it looks to be nothing more than a long list of numbers.

These numbers are always found in pairs representing X and Y values.

If you look more closely, you may spot that these numbers are interspersed with the occasional letter. These letters mean:

M - Start of the path
l - Start a sequence of lines : Unless changed, all subsequent number-pairs will relate to lines.
c - Start a sequence of curves : Unless changed, all subsequent number-pairs will relate to curves.
z - End of a path

The first pair of numbers immediately following an "M" are the absolute X/Y starting coordinates of a path.

All subsequent number-pairs are the delta (the change) from the previous position and not an absolute coordinate. In order to derive absolute coordinates, we would need to track the change(s) all the way back to the starting pair.

Recalculating these delta points as absolute coordinates will be one of the requirements of our code.

Lines comprise of a single pair of numbers. The number-pair being inspected is the ending-point of the line. The starting-point will be the ending-point of the previous step.
Curves comprise of three pairs of numbers, which describe the shape of a bezier curve. The first two pairs relate to control-points that influence the shape of the curve, whilst the third pair is the ending-point.

In the image below, point A represents the starting point of the curve (the previous step), point B represents the first pair of digits, point C the second pair of digits and finally, point D represents the third and final pair (the end point).

Line-us cannot draw curves

Importantly, Line-us does not understand curves and only works with straight lines.

This means that when we encounter a path element that describes a curve, we simply have to ignore the first two pairs of values and simply extract the end-point. For our solution, a curve will effectively be the same thing as a straight-line.

This inevitably means that our image will not be the same as the source SVG and may appear jagged. However, in practice, this wasn't really noticeable because most of the paths in the test images were so small that even straight-lines held up acceptably well to scrutiny.

Let's look at the code!

Program entry point

As previously mentioned, the file Program.cs mostly contains the setup for Dependency Injection, so instead you should look to the file ConsoleApplication.cs for the entry point into the program.

Within this file, you will find a clearly named set of method calls. These address each of the four main steps that our program needs to perform:-

public void Run()
{
    GetCoordinatesFromSVG(); // extracts a list of coordinates from the source file
    ApplyGeometry(); // rescales the coordinates, to fit within the drawable area
    GenerateGCode(); // produces a list of G-Code from the list of coordinates
    Draw(); // Sends the G-Code to the  Line-us
}

SvgService

The SvGService is probably the most complex part of the project, so don't worry if you find it a bit confusing!

The code is located here: ....\DrawWithLineUs\DrawWithLineUs\Service\SvgService.cs

The SvgService is responsible for:

Opening the SVG file specified in configuration and reading the XML content, by using System.Xml.XmlReader
Locating only the path XML nodes from within the document and returning a string - we ignore anything else in the XML.
For each path, tracking and extracting the appropriate coordinates that comprise the path.

Extracting XML data is a relatively straightforward problem to address, as the .NET framework has a library that does all of the heavy-lifting. The code looks like this:-

using (XmlReader reader = XmlReader.Create($"{PathToSourceSVG}", settings))
{
    while (reader.Read())
    {
        switch (reader.Name.ToString())
        {
            case "path":
                listPathNodes.Add(reader.GetAttribute("d"));
                break;
        }
    }
}

Extracting the appropriate coordinates that comprise a path is not entirely straightforward, so let's look at this code closely.

Our program is initially presented with a long, single string that represents the "raw" data that has been extracted from the XML source.
The first thing we need to do, is to chop this up into a List of individual words, using the .NET String.Split() method.

As a reminder, in an earlier section, we looked at how each SVG Path is made up of lines and curves. We looked at how the data description uses the characters l and c as delimiters. We learned that lines comprise of a single pair of numbers, whilst a curve comprises three pairs of numbers. Finally we learned that we can't actually take advantage of curves, so we are only interested in extracting the third pair of digits.

The XML data is not usable to us in its original form. We need to model the data by using C# objects that store a list of paths, each of which contains a nested-list of absolute coordinates (not just the delta, as found in the XML). These coordinates will eventually be used to drive the Line-us robot arm.

We use the model ...\DrawWithLineUs\Model\CoordinateStructure.cs as a container for this information. Rather than store the X/Y coordinates into separate int fields, we can use .NET's System.Drawing.Point struct, as it is intended for this kind of use.

public class CoordinateStructure
{
    public List<Point> ListPoints { get; set; }
    public List<PointF> ListRescaledPoints { get; set; } //using PointF for better precision, having been scaled

    public CoordinateStructure()
    {
        ListPoints = new List<Point>();
        ListRescaledPoints = new List<PointF>();
    }
}

We then need to parse through the list of words. We use the term words here deliberately, because they are not necessarily just numbers. For example, a word may include a letter like this: l-25, which conveys the double meaning that we are starting a new sequence of lines and that the first X value is "negative 25".

Your first idea may be that, because numbers always appear as pairs of X/Y values, that we just need to iterate over the list of words, incrementing our index value of 2 on each pass of the loop. However, this doesn't work, because curves require us to skip the index forward by 6.

The increasing complication is that a path can contain a mixture of both lines and curves (we'll call this a "variant"), but it doesn't tell us which variant we are looking at each time - only when a change happens. This means that we also need to track what the current variant is, as we iterate.

We use the variable currentSvgPathVariantEnum to persist the variant that is currently in effect.
- We have used the enumeration SvgPathVariantEnum to make it clearer, in the code, which type of variant we are working with.
We use a while loop, which ultimately keeps iterating forward over the words, until we reach the end of the list.
Within the while loop, we use the method GetCurrentPathVariant(...) to test the current word to see if it contains the characters i or c. If either of these are found, we update the variable currentSvgPathVariantEnum.
Still within the while loop, we use the method ExtractCoordinate(...) to extract the appropriate set of delta numbers.
- The index used to extract the number will vary, depending on whether we are looking at a line or a curve. We use a Regular Expression to strip out any letters. This code looks like the snippet just below:-
- In addition to extracting the delta numbers, we pass in the previous absolute coordinates, combine this with the new delta values, and ultimately return new absolute coordinates as a Point struct.

string coordX;
string coordY;
switch (currentSvgPathVariantEnum)
{
    case SvgPathVariantEnum.Line:
        coordX = Regex.Replace(listWords[i], "[^0-9.+-]", "");
        coordY = Regex.Replace(listWords[i + 1], "[^0-9.+-]", "");
        break;
    case SvgPathVariantEnum.Curve:
        coordX = Regex.Replace(listWords[i + 4], "[^0-9.+-]", "");
        coordY = Regex.Replace(listWords[i + 5], "[^0-9.+-]", "");
        break;

...

Finally within the while loop, we use the method IncrementCurrentPathIndex(...) to determine the correct number by which we should increment the loop's index (i.e. either 2 or 6).

The service ultimately returns a list of the container objects : List<CoordinateStructure>.

The partial code listing of the main method looks like this (check the source on GitHub for the class in its entirety):

public List<CoordinateStructure> ExtractCoordinates(List<string> listPathNodes)
{
    // an array of arrays (which contain point coordinates, which are constructed from the list of offsets in the SVG
    List<CoordinateStructure> listCoordinateStructures = new List<CoordinateStructure>();

    Console.WriteLine($"Parsing nodes...");
    foreach (var pathNode in listPathNodes)
    {
        var coordinateStructure = new CoordinateStructure();

        var listWords = pathNode.Split(" ");

        // extract start coordinates
        int coordStartX = int.Parse(Regex.Replace(listWords[0], "[^0-9.+-]", ""));
        int coordStartY = int.Parse(Regex.Replace(listWords[1], "[^0-9.+-]", ""));
        coordinateStructure.ListPoints.Add(new Point(coordStartX, coordStartY));


        int i = 2; // don't start at very beginning, skip over the first pair of values as these are always the "starting position"
        SvgPathVariantEnum currentSvgPathVariantEnum = SvgPathVariantEnum.Unset;

        while (i < listWords.Length)
        {
            //check to see if the "variant" has changed (is this a line or curve, or are we carrying on from the last previously set variant?)
            var newPathVariant = GetCurrentPathVariant(listWords, i);
            if (newPathVariant != SvgPathVariantEnum.Unset)
            {
                currentSvgPathVariantEnum = newPathVariant;
            }

            // depending on the "variant" extract the appropriate coordinates and add this to "coordinateStructure.ListPoints" collection. 
            Point previousPoint = coordinateStructure.ListPoints[coordinateStructure.ListPoints.Count - 1];

            Point? nextPoint = ExtractCoordinate(previousPoint, listWords, i, currentSvgPathVariantEnum);

            if (nextPoint is null)
            {
                // skip over, as point was a "MoveTo" command.
            }
            else
            {
                coordinateStructure.ListPoints.Add((Point)nextPoint);
            }

            //depending on the current variant, increment the current index appropriately (either by 2 for a line, or 6 for a curve)
            i = i + IncrementCurrentPathIndex(currentSvgPathVariantEnum);
        }

        listCoordinateStructures.Add(coordinateStructure);
    }
    return listCoordinateStructures;
}

GeometryService

The Line-us only accept coordinates within a certain range of values (refer to the diagram earlier in the article).

The SvgService however, may return coordinates with large values that exceed the bounds of the drawable area.

We need to be able to rescale the image so that everything fits correctly - this is where the GeometryService comes in.

This service is responsible for:

Iterating through each and every single point returned from the SvgService and determining the coordinate extremities (in your mind, you can picture this as a rectangle which goes around the very edge of your image).
- We use the class BoundingBox to model this result. This class has methods to return the height and width of this box.
We compare the width and height of this box against the height and width of the Line-us available drawing area. From this, we can determine an appropriate scaling ratio.
We then reiterate through all points a second time, apply the scaling factor to resize/reposition them.
- The recalculated coordinates are stored back into the instance of the model CoordinateStructure, except that this time they are store into ListRescaledPoints.
- The fields inside ListRescaledPoints are of type PointF (for a floating-point point, rather than integer point). This is so that we don't accidentally lose precision, should we end up scaling a very differently sized image. We want to preserve the accuracy of the new points as much as possible, up until the point that we export GCode.

GCodeService

This service is responsible for:

Iterating the list of rescaled coordinates (having just been rescaled by the GeometryService). The data is passed to this service via a populated instance of the CoordinateStructure class.
Producing a list of appropriate GCode commands that will be later sent to the device.

By the time we come to use the GCodeService, we've done all the hard work of preparing lists of data that represent multiple paths each containing multiple points.

All that is left for us to do, is pay attention to what the pen of the robot is doing, by lifting it off the page and moving it to the start of each new path.

When we start drawing a new path, we reposition the pen to the new starting coordinates.
Lower the pen ready to start drawing.
Move it to each point in sequence.
We then raise the pen at the end of the sequence, ready for the move to the start of the next path.

Because our rescaled coordinates have been stored as a PointF (a floating-point precision point), we need to convert back to an int when producing our GCode.

Tip: try and use enums or static classes to describe fixed values

As a developer, something you should avoid the anti-pattern of using magic numbers or hardcoding of strings that, although make sense at the time you write the code, are not apparent to other people (or indeed yourself in the future, when you forget the details!).

As such, you should aim to make the meaning of your code as clear as possible by using easily-understood words in code. You can usually use enumerations or static classes to help you here.

So in the case of our GCode, we could easily have written the snippet above so it looked like this...

listGCodes.Add($"G01 x{(int)step.X} y{(int)step.Y} z0\n");

… but how would someone who is new to the project, who is reading your code, know that "G01" means "Linear Interpolation" - or that the Z axis of zero means "pen down". To get meaning, they would have to stop what they're doing and cross-reference with the documentation.

Instead, we can improve the meaning in our code like this:-

public static class GCodes
{
    public const string RapidReposition = "g00";
    public const string LinearInterpolation = "g01";
}

public static class Pen
{
    public const int PenUpIndex = 1000;
    public const int PenDownIndex = 1;
}

With awareness of the above, we can instead write our code that produces GCode for the path like this:-

private static void SequencePath(List<string> listGCodes, CoordinateStructure sequence)
{
    foreach (var step in sequence.ListRescaledPoints)
    {
        listGCodes.Add($"{GCodes.LinearInterpolation} x{(int)step.X} y{(int)step.Y} z{Pen.PenDownIndex}\n");
    }
}

If you are not entirely familiar with some of the syntax in the example above, we are using C#6 String Interpolation to build our string (where previously, you may have used String.Format() to achieve the same outcome).

CommunicationService

This service is responsible for:

Establishing a TCP connection between your computer and the Line-us, by using the .NET library System.Net.Sockets.
Receiving the initial "hello" back from the Line-us, signalling the device is ready to start a two-way communication.
Converting GCode into a byte-array and sending the command.

The class in its entirety looks like this:-

public class CommunicationService : ICommunicationService
{
    public void ConnectToLineUs(out TcpClient client, out NetworkStream stream, string lineusIP, int lineusport)
    {
        IPAddress lineusipaddress = System.Net.IPAddress.Parse(lineusIP);
        client = new TcpClient();
        client.Connect(new IPEndPoint(lineusipaddress, lineusport));
        stream = client.GetStream();
        SayHello(stream);
    }

    private void SayHello(NetworkStream stream)
    {
        Byte[] data = new Byte[256];
        int bytes = stream.Read(data, 0, data.Length);
        String responseData = System.Text.Encoding.ASCII.GetString(data, 0, bytes);
        Console.WriteLine($"Received: {responseData}");
    }

    public void Transmit(NetworkStream stream, string instruction)
    {
        //Console.WriteLine($"Sent: {instruction}");
        byte[] data = System.Text.Encoding.ASCII.GetBytes(instruction);
        stream.Write(data, 0, data.Length);

        data = new Byte[256];

        int bytes = stream.Read(data, 0, data.Length);
        string responseData = System.Text.Encoding.ASCII.GetString(data, 0, bytes);
        Console.WriteLine($"Received: {responseData}");
    }
}

Wrapping up

Line-us is a nice little machine, thoughtfully designed and easy to use. It sidesteps much of the complications that come with "rolling your own" hardware systems.

It's very much something I could envisage being used as a way to get kids interested in programming and for me, mildly echoes the LOGO programming that I was shown in school, a generation ago.

I'm hoping this article can re-assert that programming can be just for fun and hopefully inspire folks to try something different.

If you've discovered this article through a search, coming as someone wanting to learn about Line-us, then hopefully this has been useful to you as an example of C# code.

Where to next?

Check out this things-to-do link by line-us.com for inspiration.

Here are some ideas for you to improve this project:

Extend the SVG parser to support more shapes - not just paths.
Extend the code to support multi-colour painting - check out the following image (from line-us press images):

How to extract a phone number from an image using Azure cognitive services and Twilio number lookup

Jim Mc̮̑̑̑͒G — Thu, 24 Oct 2019 10:53:11 +0000

This article was originally published at blogs.siliconorchid.com on 6-Mar-2019

In this article, we’re going to create a solution that extracts any potential phone numbers that appear in an image file. Having extracted potential numbers we'll then attempt to verify that they are valid phone numbers.

Introduction

The past couple of years have turned out to be really interesting times for developers.

We've witnessed the rise of powerful Software-as-a-Service (SaaS), that can be accessed using nothing more than a simple HTTP API call. SaaS has been transformative in the way that we work and can result in the creation of some very potent software. The big tech companies, like Microsoft and Google, have been giving us cheap access to amazing computing resources to solve problems that, only a decade ago, would have been a serious technical hurdle for regular developers to overcome.

In this article, we're going to explore some of these awesome services and have a bit of fun. This will involve connecting together some of these APIs together in a way that could solve the sort of business-requirement that a real-world application could need solving.

Imagine you want to take a photograph of a business card, or maybe a poster you see at a convention, using your cellphone. You then want to be able to automatically extract a list of phone numbers from that image. That would be pretty useful right?

We'll achieve this using the following technologies:

.Net Core 2.x WebApi project
Azure Cognitive Services
Twilio Lookup API.

From a high-level, we're going to perform these steps:

We'll use the Azure Text Recognition API to process an image and return a collection of words.
We'll then review code that attempts to extract "candidate" phone numbers from this list of words, discarding non-numbers and attempting to combine number fragments.
Finally, we'll use a Twilio API to perform a check on the candidate phone number to verify if it is actually a real number.

As these blogs are partly intended to be an exploration into C# coding, we'll also touch on something called method-chaining which, depending on the context of use, could be a useful way to improve your code. We'll also make use of asynchronous programming for more efficient use of time when calling API services.

Azure Cognitive Services

Microsoft offers a powerful set of AI-driven services that they call Cognitive Services. These fall into the categories of speech, vision, language understanding and search.

In this article we'll be interested in consuming the Computer Vision
service and specifically the Text Recognition API(s).

There are actually two separate flavours of text-recognition APIs available. At the time of writing, they are still currently in preview:

A service for extracting typed text from an image.
A service for extracting handwritten text from an image. This API is slightly more complicated to consume, because the service takes marginally longer to process and does not yield an immediate response to the API request. Therefore we need to code a polling mechanism to receive a result.

According to the documentation, a limitation of the handwritten recognition, is that currently it only supports English language. However, given that our goal is only to extract phone numbers, this shouldn't pose any problem for us (later in the article, we'll be writing code that will discard anything that doesn't look like a phone number anyway).

Twilio Phone Number Lookup.

We'll also be calling an API provided by Twilio to lookup and verify phone numbers.

This is extremely useful, as it means that we'll be able to go beyond the usual guess-work that is typical when working with phone numbers and be able to return a list of genuinely validated numbers.

The Problem - Validating Phone Numbers Is Hard.

Validating phone numbers is a deceptively tricky problem to address. The complexity of phone number validation can change depending upon the audience/localisation that your software will be serving:

If you are writing a solution for a domestic audience, you may be able to apply a relatively strict set of validation rules because you can reasonably expect a number to be in a particular format. In this scenario, use of something like a regular expression, could be a suitable way to validate a number.
If your application will require you to accommodate and validate international numbers, each with their own combination of valid numbers - and potentially alphanumeric text, then a strict pattern match solution just isn't going to cut it.

Even if you attempt to get creative with a set of complicated logic rules, you run the risk of not properly accounting for regional variations (and thereby risk rejecting potentially valid numbers).

At this point I would strongly refer you to read the Twilio Voices Blog Validating phone numbers effectively with C# and the .NET frameworks, which covers many of the issues you'll need to consider when capturing phone number data, along with potential solutions to the validation problem.

We'll be taking advantage of Twilio's Lookup API for number validation. The Lookup API accepts a phone number, attempts to match it against the phone network databases, and responds with appropriate information.

The solution presented in this article is far from perfect and is not intended to be a solution that will work well for everyone. However, what I have put together here is intended to be inspirational and I am certain that there will be elements that you will be able to take away and adapt into your own code.

Introducing the E.164 convention

You should be mindful that the Twilio Lookup API cannot magically figure out what a partial, or unusually formatted, phone number should be.

Part of our challenge will be that we need to supply a number to their API in a correctly formatted international convention known as E.164.

Whilst the E.164 format itself is straightforward, a difficulty we face is that the string of text extracted from the image is unlikely to be in this format. For example, it is highly likely that it will not contain the international dialling code.

So a hurdle with our code, is that we may need to get creative with how we go about "filling in the blanks"!

The problem of internationalisation is a tricky one;

If your software is serving only a domestic audience, you could potentially cut corners and make a sweeping presumption that you should add a fixed international prefix code (assuming the prefix is not already present).
If your software is serving an international audience, you may need to provide a mechanism to obtain this information from the user - for example:
- in a UI where a user uploads an image, perhaps they will be required to select a country from something like a dropdown.
- you could possibly determine the user's geographic location (e.g. using a geolocation API from a device, or perhaps a more crude IP based lookup).

Prerequisites

There will be an assumption that you have familiarity working with:
You'll need to have installed the .Net Core 2.x SDK, as appropriate to your platform.
You'll need something to edit and build your project.
- This demo was primarily created using .Net Core 2.1 on a Windows 10 system using Visual Studio 2017 Community edition. There is no reason why you cannot use other platforms, code editors and CLI tools - my recommendation would be to use Visual Studio Code.
You'll need to download the sample code that accompanies this article.
- Project source can be downloaded from here : https://github.com/SiliconOrchid/PhoneExtractVerify
You will need an Azure account with an active subscription.
- Specifically, you'll need to create Computer Vision services. If you are a new subscriber, you can get access to this service for free (at time of writing).
You will need a Twilio account with an active subscription. You'll need this to access the Lookup API.
- If you don't have a Twilio account or are completely new to their service, then check out their .NET Core quickstart tutorial.

Setup Azure Computer Vision

Log onto your Azure Portal
Create a new Resource Group for this project and name it "PhoneNumberRecognitionDemo":

To add a Computer Vision resource to your subscription simply by search for "computer vision" in the Azure marketplace:

Configure the Computer Vision resource:
- Give your resource a name that will make it easy to recognise (I chose to PhoneNumberRecognitionDemo_CV, using the suffix "_CV" for "Computer Vision").
- Choose a data centre nearest to your location that supports Computer Vision (Noting that this service is not available in all Azure data-centres).
- Choose the 'F0' Pricing tier. This is the free version, but our limited usage in the demo will be fine at that level.

Wait a few moments while the resource deploys.
Open up the Computer Vision resource and navigate to the "Keys" section. We'll need to copy these credentials into our project's configuration a bit later, so keep this window open.

Setup Twilio

Log onto your Twilio Portal (or create a free trial if you don't already have one).
We need to locate the ACCOUNT SID and AUTH TOKEN values, which are prominently located on the home page.
- The only slightly non-obvious thing that I encountered, as a brand-new Twilio user, was that in order to see any of your api keys, you must first have created at least one project, for these values to show. When I first started, I bypassed Twilio's "My New Learn & Explore Project" introduction, meaning that I could not find the credentials.
When you have found the credentials, keep the webpage open so that we can copy the keys into our application configuration.

Clone The Sample Repository

In order to more easily follow-along with this tutorial, you should clone the source code from here : https://github.com/SiliconOrchid/PhoneExtractVerify

Let's Talk About App Configuration

Both the Azure and Twilio APIs require you to provide credentials in order to use their respective services.

Note that we don't actually save any credentials directly in our code (otherwise this sensitive information will end up in version-control). Instead we will be using appsettings.json combined with User Secrets:

the ....\src\PhoneExtractVerify.Api\appsettings.json file is used to provide structure.
User Secrets and most likely Azure Appsettings (if you're planning to host this solution in Azure).

If you're not familiar with the concept of User Secrets, I could recommend that you read this blog as an introduction.

Let's look at the appsettings.json file:

{
"Logging": {
  "LogLevel": {
    "Default": "Warning"
  }
},
"AllowedHosts": "*",

"TwilioCredentials": {
  "AccountSid": "Set In Secrets or Environment",
  "AuthToken": "Set In Secrets or Environment"
},

"AzureComputerVisionCredentials": {
  "UriBase": "https://westeurope.api.cognitive.microsoft.com/vision/v2.0/ocr",
  "SubscriptionKey": "Set In Secrets or Environment"
}
}

You can ignore the first few lines of this file that are related to logging. The parts we're interested in are the entries for TwilioCredentials and AzureComputerVisionCredentials.

The appsettings.json file makes it clear that you shouldn't be saving any sensitive information directly into this file.
The UriBase for the Azure credentials is dependent on your own Azure subscription. In the sample code, this is westeurope, but you will need to change this if you are using a different region. The URI to use is available to cut+paste out of the Azure Console, along with your other credentials.

The appSettings correlate to two strongly typed models within our code. These models are populated by binding to the configuration source and are then consumed by injecting them into the service class:-

....\src\PhoneExtractVerify.Api\Models\AzureComputerVisionCredentials.cs
....\src\PhoneExtractVerify.Api\Models\TwilioCredentials.cs

The code for binding data to the configuration models can be found up in the solution startup. If you look at ...\PhoneExtractVerify\src\PhoneExtractVerify.Api\Startup.cs, the two lines with service.Configure do all the binding magic:

public void ConfigureServices(IServiceCollection services)
{
  services.Configure<TwilioCredentials>(Configuration.GetSection("TwilioAccount"));
  services.Configure<AzureComputerVisionCredentials>(Configuration.GetSection("AzureComputerVisionCredentials"));

Run the application

We'll examine the code itself shortly, but first, let's run the program and see an actual result!

The system is accessed using an HTTP endpoint, so assuming your code is now cloned and configured, all you need to do now is build and run the project.
Here are a pair of sample images that you could use to perform the tests:

We need to POST an image to our API, so I recommend that you use a tool such as Postman to make the request:
- Set the HTTP action to POST.
- Provide a URL to the correct endpoint (taking care to provide the right port number) - e.g. https://localhost:44367/api/PhoneReader.
- Set the body of the post to be a binary type (i.e. not form-data, etc).
- Choose an image file to send (use the "typed" sample provided above if you like).
- If everything has worked, you should get an HTTP200 (ok) response from the API, along with any verified phone numbers:

The screenshot above shows that our API correctly returns two phone numbers +441234567890 and +447700123456. These have been correctly extracted from the image and subsequently verified as real telephone numbers by the Twilio Api lookup.

Integrate With Azure Computer Vision

Next, let's start looking at the code by examining the service class responsible for communicating with the Azure Text Recognition API. In your code editor, open up this file:-

....\PhoneExtractVerify.Api\Services\AzureComputerVisionHelperService.cs

AzureComputerVisionHelperService Constructor of the class is concerned with the IoC injection of configuration settings.

public class AzureComputerVisionHelperService : IAzureComputerVisionHelperService
{
  private AzureComputerVisionCredentials _azureComputerVisionCredentials;

  public AzureComputerVisionHelperService(IOptions<AzureComputerVisionCredentials> azureComputerVisionCredentialsConfiguration)
  {
      _azureComputerVisionCredentials = azureComputerVisionCredentialsConfiguration.Value ?? throw new ArgumentException(nameof(azureComputerVisionCredentialsConfiguration));
  }

Reading Printed Text

The AzureComputerVisionHelperService ExtractPrintedText(...) method performs the work of talking to the Azure API for recognising printed text in an image.

The complete documentation for how to use this API can be found at Microsoft Computer Vision Quickstart (For Printed Text).

We provide credentials to use the service in the API request header.
We supply the image (as a byte array) as content.
The method asynchronously returns the JSON response from the API call.

We'll talk about that JSON response in a moment.

Below is the code that talks to the image-recognition API:

public async Task<string> ExtractPrintedText(Byte[] imageBytes)
{
  try
  {
      HttpClient client = new HttpClient();

      client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", _azureComputerVisionCredentials.SubscriptionKey);

      HttpResponseMessage response;

      using (ByteArrayContent content = new ByteArrayContent(imageBytes))
      {
          content.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
          response = await client.PostAsync(_azureComputerVisionCredentials.UriBase, content);
      }

      return await response.Content.ReadAsStringAsync();
  }
  catch (Exception e)
  {
      Console.WriteLine(e.Message);
      return "";
  }
}

Reading Handwritten Text

The AzureComputerVisionHelperService ReadHandwrittenText(...) method performs the work of talking to the Azure API for recognising handwritten text in an image.

The complete documentation for how to use this API can be found at Microsoft Computer Vision Quickstart (For Handwritten Text).

The code for talking to the "Handwriting Recognition" API has a fair bit more code than the equivalent "Typed Text" version. The principle reason is that the "Typed Text" version of the API returns data along with the API response. In contrast, the "Handwritten Version" of the API requires more processing effort by the service, which could take a relatively long time to return a result. As such, this API does not return an immediate result with the API request.

Instead, this API returns a dynamically generated URL as the response. This URL then needs to be polled repeatedly, until the service eventually provides you with a result.

We provide credentials to use the service in the API request header.
We supply the image (as a byte array) as content.
We check the initial API response for a valid response - if all is OK, we look at the response header as it will contain a URL value (in the code below, this is stored in the variable operationLocation )
We create a loop that iterates once every second, up to a maximum of 10 attempts. Each iteration will poll the operationLocation for a result. We assume that if there is no result after 10 seconds, that there has been a problem with the API service and log an error message to the console.
If we receive a result during the poll, the json data is returned from the method.

Below is the code that talks to the image-recognition API (it is more or less cut & paste directly from the MS quickstart guide):-

public async Task<string> ReadHandwrittenText(Byte[] imageBytes)
{
  try
  {
      HttpClient client = new HttpClient();
      client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", _azureComputerVisionCredentials.SubscriptionKey);
      string requestParameters = "mode=Handwritten";
      string uri = _azureComputerVisionCredentials.UriBase + "?" + requestParameters;

      HttpResponseMessage response;
      string operationLocation;

      using (ByteArrayContent content = new ByteArrayContent(imageBytes))
      {
          content.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
          response = await client.PostAsync(uri, content);
      }

      if (response.IsSuccessStatusCode)
      {
          operationLocation = response.Headers.GetValues("Operation-Location").FirstOrDefault();
      }
      else
      {
          string errorString = await response.Content.ReadAsStringAsync();
          Console.WriteLine($"ReadHandwrittenText : Response:{JToken.Parse(errorString).ToString()}");
          return string.Empty;
      }

      string contentString;
      int i = 0;
      do
      {
          System.Threading.Thread.Sleep(1000);
          response = await client.GetAsync(operationLocation);
          contentString = await response.Content.ReadAsStringAsync();
          ++i;
      }
      while (i < 10 && contentString.IndexOf("\"status\":\"Succeeded\"") == -1);

      if (i == 10 && contentString.IndexOf("\"status\":\"Succeeded\"") == -1)
      {
          Console.WriteLine("ReadHandwrittenText : Timeout error.");
          return string.Empty;
      }

      return contentString;

  }
  catch (Exception e)
  {
      Console.WriteLine("\n" + e.Message);
      return string.Empty;
  }
}

Extracting words from the response

The AzureComputerVisionHelperService ExtractPrintedWords(...) method performs the work of extracting a collection of words from the JSON data returned from the API request.

The data returned by either of the text-recognition APIs is a relatively complex json string (partial example below). The string contains a great deal of information including the actual words, the location of those words within the image and how the words may be grouped together (as part of a sentence, etc).

In many scenarios, all of this information could be very useful - but for this project, we really don't need anything other than a list of the actual words.

So, with this understanding, we can write a piece of code that simply iterates over the data structures, and discards pretty much everything other than the data nodes containing the actual words themselves.

The variable listDistinctWords is used to store a list of extracted words.
We convert the JSON string into a C# dynamic object .

Using a dynamic type is not without issues (for example, you lose compile-time type-safety), but for our demonstration code, it is a convenient way to address the problem of mapping and working with the complex object that is provide in the JSON response.
The JSON response has 3 basic structures : regions, lines and words. We need to iterate through each of these structures and return only the word.text value. The following is a short snippet of the json response, creating using the sample images provided earlier:

{
  "language": "en",
  "orientation": "Up",
  "textAngle": 0.0,
  "regions": [
      {
          "boundingBox": "81,229,1020,455",
          "lines": [
              {
                  "boundingBox": "84,229,989,53",
                  "words": [
                      {
                          "boundingBox": "84,231,72,51",
                          "text": "My"
                      },
                      {
                          "boundingBox": "182,240,106,32",
                          "text": "new"
                      },
                      {
                          "boundingBox": "314,229,162,53",
                          "text": "phone"
                      },
  ... (clipped for brevity)

The method then simple returns a collection of words:-

public List<string> ExtractPrintedWords(string jsonResponse)
{
  List<string> listDistinctWords = new List<string>();

  dynamic jsonObj = Newtonsoft.Json.JsonConvert.DeserializeObject(jsonResponse);

  foreach (var region in jsonObj.regions)
  {
      foreach (var line in region.lines)
      {
          foreach (var word in line.words)
          {
              listDistinctWords.Add(Convert.ToString(word.text));
          }
      }
  }

  return listDistinctWords;
}

Integrate With Twilio Lookup

Dependency on Twilio API Wrapper

The interaction with the Twilio API is simplified because it provides helper libraries that can easily be added to your project.

Using NuGet, add dependencies to these packages: Twilio and Twilio.AspNet.Core.

 If you prefer, you can add these references directly to the following file:-

....\PhoneExtractVerify\src\PhoneExtractVerify.Api\PhoneExtractVerify.Api.csproj:

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.App" />
  <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.1.1" />
  <PackageReference Include="Twilio" Version="5.14.0" />
  <PackageReference Include="Twilio.AspNet.Core" Version="5.9.7" />
</ItemGroup>

The Twilio helper service

Next, we'll look at the service class responsible for communicating with the Twilio API.

In your code editor, open up this file:-

....\src\PhoneExtractVerify.Api\Services\TwilioHelperService.cs

TwilioHelperService Constructor

The constructor for this class is really straightforward, so let's just quickly note:

we are injecting a populated model containing the credentials to be used with the Twilio API.
we are initialising an instance of the TwilioClient with the credentials.

namespace PhoneExtractVerify.Api.Services
{
  public class TwilioHelperService : ITwilioHelperService
  {
      private TwilioCredentials _twilioCredentials;

      public TwilioHelperService(IOptions<TwilioCredentials> account)
      {
          _twilioCredentials = account.Value ?? throw new ArgumentNullException(nameof(account));

          TwilioClient.Init(_twilioCredentials.AccountSid, _twilioCredentials.AuthToken );
      }
   ...

TwilioHelperService VerifyWithTwilioAsync(...) method

This method is responsible for transmitting a single "candidate phone number" (a string) to the Twilio Lookup API.

Our interaction with the Twilio API has been simplified, because we're using that Twilio API helper library.

The majority of the code in this class is testing the response to the API and performing logging to help us diagnose any problems that may arise.

private async Task<string> VerifyWithTwilioAsync(string numberToTest)
{
  try
  {
      var twilioPhoneNumberResource = await PhoneNumberResource.FetchAsync(
              pathPhoneNumber: new Twilio.Types.PhoneNumber(numberToTest)
          );

      if (twilioPhoneNumberResource == null || twilioPhoneNumberResource.PhoneNumber == null)
      {
          Console.WriteLine($"TwilioHelperService : Using number '{numberToTest}', Twilio Api response was null");
          return String.Empty;
      }

      Console.WriteLine($"TwilioHelperService : Using number '{numberToTest}', Twilio Api returned valid object:  National Format : '{twilioPhoneNumberResource.NationalFormat}' . Carrier : '{twilioPhoneNumberResource.Carrier}' . Phone Number :  {twilioPhoneNumberResource.PhoneNumber}");
      return twilioPhoneNumberResource.PhoneNumber.ToString();
  }
  catch (Exception ex)
  {
      Console.WriteLine($"TwilioHelperService : Exception : {ex.Message}");
      return String.Empty;
  }
}

TwilioHelperService ProcessListCandidateNumbersAsync(...) method

This method is responsible for iterating a collection of "candidate phone numbers" and calling the previously discussed VerifyWithTwilioAsync method repeatedly.

Notice that this method wraps each separate API call in an asynchronous task and then awaits, using Task.WhenAll(...), for all of the API calls to complete - before progressing. This allows us to fire of a number of API calls in parallel, which makes more efficient use of time.

The resultant collection of strings contains a list of phone numbers that have been validated by the Twilio API. The method then returns the collection.

public async Task<List<string>> ProcessListCandidateNumbersAsync(List<string> listCandidatePhoneNumbers)
{
  List<string> listVerifiedNumbers = new List<string>();

  var listTasks = new List<Task<string>>();

  foreach (var candidatePhoneNumber in listCandidatePhoneNumbers)
  {
      var task = VerifyWithTwilioAsync(candidatePhoneNumber);
      listTasks.Add(task);
  }

  foreach (var taskResult in await Task.WhenAll(listTasks))
  {
      if (!string.IsNullOrEmpty(taskResult))
      {
          listVerifiedNumbers.Add(taskResult);
      }
  }

  return listVerifiedNumbers;
}

The Mediator Service

The mediator service is the glue of the project and is responsible for orchestrating the multiple steps we need to take.

In your code editor, open up this file:-

....\src\PhoneExtractVerify.Api\Services\MediatorService.cs

It could be very tempting to put the kind of code in this class directly into the WebAPI controller method. However, by locating this orchestration code into its own class, we greatly improve the separation-of-concerns and make our code much clearer. This means that the WebAPI is responsible only for things which it should be concerned with (e.g. validating input parameters and returning http responses).

MediatorService Constructor

The constructor of the class MediatorService injects the components that we will be using:

namespace PhoneExtractVerify.Api.Services
{
  public class MediatorService : IMediatorService
  {
      private readonly IWordProcessingService _wordProcessingService;
      private readonly ITwilioHelperService _twilioHelperService;
      private readonly IAzureComputerVisionHelperService _azureComputerVisionHelperService;

      public MediatorService(IWordProcessingService wordProcessingService, ITwilioHelperService twilioHelperService, IAzureComputerVisionHelperService azureComputerVisionHelperService)
      {
          _wordProcessingService = wordProcessingService ?? throw new ArgumentNullException();
          _twilioHelperService = twilioHelperService ?? throw new ArgumentNullException();
          _azureComputerVisionHelperService = azureComputerVisionHelperService ?? throw new ArgumentNullException();
      }
   ...

MediatorService ProcessPhoneNumber(...) method:

This method is responsible for calling all of the various activities needed to process data from an image and ultimately into a filtered list of words.:-

In this demo code, we've provided versions for either "printed" text or "handwritten" text. Depending on which one you want to use, you should comment/uncomment the appropriate code.

As a suggestion, you could modify the code, so you provide additional switching to select the appropriate usage (e.g. a Url parameter in the calling Api, etc)

Calls the RecognisePrintedText method of the "Azure Computer Vision Helper" service, first providing an image (which will be provided by the WebAPIcontroller method) and storing the JSON response in the variable jsonresponse.
Calls either the ExtractWordsFromPrintedResult or ExtractWordsFromHandwrittenResult from the "Azure Computer Vision Helper" service - this processes the JSON object to return a simple list of words, which gets saved in the variable listAllWords.
Calls the "Word Processing" service to extract a list of "candidate phone numbers" from the complete list of words returned from the image OCR. There are a number of chained methods in this activity, each performing a step in the overall processing. We'll examine the "Word Processing Service" in detail later in this article, but for the moment, let's just press onwards so that we get to see a result.
Calls the "Twilio Helper" service to validate the candidate phone numbers.

The code listing looks like this:-

public async Task<List<string>> ProcessPhoneNumber(byte[] imageBytes)
{
  // Call the Azure Computer Vision service (for Printed Text) and extract words from response.
  string jsonResponse = await _azureComputerVisionHelperService.RecognisePrintedText(imageBytes);
  List<string> listAllWords = _azureComputerVisionHelperService.ExtractWordsFromPrintedResult(jsonResponse);

  // -or-  if you want to use a handwritten image, swap out the above lines for the following:

  // Call the Azure Computer Vision service (for Handwritten Text) and extract words from response.
      //string jsonResponse = await _azureComputerVisionHelperService.RecogniseHandwrittenText(imageBytes);
      //List<string> listAllWords = _azureComputerVisionHelperService.ExtractWordsFromHandwrittenResult(jsonResponse);


  List<string> listCandidatePhoneNumbers = _wordProcessingService
      .AddWords(listAllWords)
      .GetCandidatePhoneNumbers()
      .ExtractWordsWithNumbers()
      .ReformatAsUKInternational()
      .GetMinLengthNumbers()
      .ListProcessedWords;

  List<string> listVerifiedPhoneNumbers = await _twilioHelperService.ProcessListCandidateNumbersAsync(listCandidatePhoneNumbers);

  return listVerifiedPhoneNumbers;
}

The WebAPI Controller

The WebAPI class is our entry point to this project. It provides a tidy way to interact with our code using an HTTP endpoint.

In your code editor, open up this file:-

....\src\PhoneExtractVerify.Api\Controllers\PhoneReaderController.cs

We inject the mediator class, which has responsibility to call the various processes that we need to run.
The API method itself, Post(), is responsible for:-
- receiving an HTTP post containing an image.
- confirming whether the rest of our code has run successfully and returning an appropriate HTTP response.

[Route("api/[controller]")]
[ApiController]
public class PhoneReaderController : Controller
{
  private readonly IMediatorService _mediatorService;

  public PhoneReaderController(IMediatorService mediatorService)
  {
      _mediatorService = mediatorService ?? throw new ArgumentNullException();
  }


  [HttpPost]
  public async Task<ActionResult> Post()
  {
      // Read the image from the POSTed data stream, into a byte array
      byte[] imageBytes;
      using (var ms = new MemoryStream(2048))
      {
          await Request.Body.CopyToAsync(ms);
          imageBytes = ms.ToArray();
      }

      try
      {
          List<string> listVerifiedPhoneNumbers = await _mediatorService.ProcessPhoneNumber(imageBytes);
          return Ok(string.Join(" - ", listVerifiedPhoneNumbers));
      }
      catch
      {
          return StatusCode(500);
      }
  }
}

Processing Scanned Numbers Into E.164 Format

By now you have hopefully either run the project and seen a result, or at least have a good feel for the various moving parts.

This section addressed two key points:

We're going to be using something called method chaining. You can read more about this in another of my articles here : C# Method Chaining. Very briefly, the idea behind this approach is that you can pass the output from one method, directly to another, using an easy-to-use syntax.
This article is going to touch on a specific-regional phone-number format. Because I'm based in the UK, my demonstration is going to explain how UK phone number formatting works and will include demo code that addresses this. You should view this as "a business logic problem" and adapt your own code to suit your localisation.

I've deliberately left the explanation of this "WordProcessing" service until later in this article, because I wanted you to learn about the overall program structure and the APIs first, without getting you overly bogged-down in detail which is more "business logic" orientated.

A Brief Introduction To UK Phone Number Formatting

In the UK, the phone number system has a few variations:

The basic phone number is a six-digit numeric-only number - e.g. 123456.
- You could telephone this "short" number and (assuming it is connected) you would get through to the geographically local landline (someone in your town or city).
You might be calling someone elsewhere in the country or on a mobile phone network. To achieve this, you need to include what we call the "area code" (or "prefix code").
- An example landline number would now look like this: 01234 123456.
- Mobile (cellphone) numbers typically start with "07" rather than "01", so a mobile number could be: 07700 123456.
In the UK, we also have the concept of non-geographic and premium numbers. These have a slightly shorter prefix - e.g. 0800 numbers are typically toll-free, 0845 are non-geographic but charged at local call rates. E.g. 0845 123456
The UK international dialling code is +44. If you are calling a UK number from abroad - or more relevantly to our scenario, wanting to use the international E.164 format - you must drop the leading zero from the national version of the number.
- This means that the national number 01234 123456 becomes +44 1234 123456 ... or more correctly (without spaces) +441234123456.

The above covers the basic number system. However, when you start to venture into printed media (such as adverts, posters or business cards etc), phone numbers can become more arcane as they rely on human interpretation to decode.

For example, it is very common in the UK to include parenthesis and spacing to make it easier for a human to read - for example "(01234) 567890". To adapt this style of number into E.164 format, we would need to do a couple of things:

We need to remove the non-numeric characters. In the example above, the parentheses and spaces needs to be removed.
The leading zero is used when dialling domestically, but not internationally, so we also need to drop that.
Assuming that we know for a fact that this number is from the UK (and truthfully, we are making a big assumption, as there is nothing in the example itself that tells us that this number is from the UK), we need to add the international dialling code. So we prefix with +44.
We should end up with the number +441234567890

The WordProcessingService

The WordProcessingService class is responsible for processing a string. The class has various methods that refine the results. The overall goal of the service is to take a collection of any possible words that originate in a scanned image, and return a list of strings that could be a candidate phone number.

In your code editor, open up this file:-

....\src\PhoneExtractVerify.Api\Controllers\PhoneReaderController.cs

WordProcessingService Class variables

The various methods in this class chain results together, so rather than passing values around to each method as an argument, we use private member variables that each method modifies.

The first couple of items are configuration items (such as international dialing prefix). Arguably this sort of thing could be extracted out into configuration, but given the relatively specific purpose of the code in this class, it's doing no harm to leave it here.

We publicly expose ListProcessedWords as a collection of refined values.

namespace PhoneExtractVerify.Api.Services
{
  public class WordProcessingService : IWordProcessingService
  {
      private static string _countryPrefix = "+44";
      private static int _minWordLength = 10;
      private List<string> _listProcessedWords;


      public List<string> ListProcessedWords
      {
          get { return _listProcessedWords; }
      }

WordProcessingService AddWords(...) method Most of the methods in this class read and write from the private member variable _listProcessedWords. We need a way to pass an initial value into the chain, which is the purpose that AddWords(...) serves.

You can see an example of use, described earlier, in the MediatorService ProcessPhoneNumber(...) method, but to briefly recap, we call the AddWords(...) method first providing a collection of words as an argument and then append the other method calls.

Superficially, AddWords(...) does nothing more than take the argument and assigns it to the private member variable.

public WordProcessingService AddWords(List<string> listWords)
{
  _listProcessedWords = listWords;
  return this;
}

WordProcessingService GetCandidatePhoneNumbers(...) method

The problem we are trying to solve with this method, is that when the Azure OCR service is run on an image, it returns a list of words that are separated by numbers.

It has no way of recognising that a number separated by spaces is actually intended to be a single phone number, so the result is that it returns multiple separate words. In other words, our phone number has become fragmented.

A single number fragment on its own is of no use to us, so we need a way to re-assemble those fragments back together.

The code in this method achieves this, by iterating over all the words in the collection in sequence. It works by making a note of whether the previous word it looked at in the sequence, was a number (or contains the "+" symbol). If the previous word and the current word both contain a number within the word, the code will combine the two into a new string and insert this new value into the collection.

The inclusion of the "+" symbol when checking for words containing digits, was something I added when testing. I noticed that some OCR passes separate the "+" as a distinct word - separated from the the international code - which caused problems.

This code will combine new words containing numbers together, until it encounters a word-only word, or reaches the end of the list.

The code trails on (and includes) the newly-created compound number, meaning we can build up longer strings of adjacent numbers

So, this is probably best explained by showing you an example. The following words are extracted from the Azure OCR process :

"call", "me", "on", "+44", "1234", "567", "890", "or"

Running the above list through our method, creates the following list as an output:

"call", "me", "on", "+44", "1234", "+441234", "567", "+441234567", "890", "+441234567890", "or"

In a later step, we'll discard most of the unwanted number fragments, but the key thing is that we have reassembled the four separate numbers fragments ("+44", "1234", "567" and "890") into a new word "+441234567890" - which will be useful to us.

Also worth noting, is that we need to be accepting of numbers that aren't purely integers. For example the international dialling code fragment with typically contain a plus symbol (e.g. "+44"), so we need to allow this to be included.

public WordProcessingService GetCandidatePhoneNumbers()
{
  bool IsTrailingNumber = false;

  List<string> listCombinedNumberWords = new List<string>();

  foreach (var word in _listProcessedWords)
  {
      listCombinedNumberWords.Add(word);

      if (word.Any(char.IsDigit) || word.Contains("+"))
      {

          if (IsTrailingNumber)
              listCombinedNumberWords.Add($"{listCombinedNumberWords[listCombinedNumberWords.Count - 2]}{word}");

          IsTrailingNumber = true;
      }
      else
      {
          IsTrailingNumber = false;
      }
  }

  _listProcessedWords = listCombinedNumberWords;
  return this;
}

WordProcessingService ExtractWordsWithNumbers(...) method

The purpose of this method is to discard words that do not contain a numeric digit.

To explain with an example, when filtered, the following list:

"call", "me", "on", "+44", "1234", "+441234", "567", "+441234567", "890", "+441234567890", "or"

... will be filtered to become this list:

"+44", "1234", "+441234", "567", "+441234567", "890", "+441234567890"

public WordProcessingService ExtractWordsWithNumbers()
{
  _listProcessedWords = _listProcessedWords.Where(word => word.Any(char.IsDigit)).ToList();
  return this;
}

WordProcessingService GetMinLengthNumbers(...) method

The purpose of this method is to discard words that do not meet a value that we deem to be the minimum threshold in length.

The idea here, is that while we may not know whether a number is valid or not, we can be fairly certain that are too short to possibly be a E.164 code, can be discarded without further testing.

To explain with an example, when filtered, the following list:

"+44", "1234", "+441234", "567", "+441234567", "890", "+441234567890"

... will be filtered to become this list:

"+441234567", "+441234567890"

public WordProcessingService GetMinLengthNumbers()
{
      _listProcessedWords = _listProcessedWords.Where(w => w.Length >= _minWordLength).ToList();
  return this;
}

WordProcessingService ReformatAsUKInternational(...) method

The purpose of this method is to ensure that any recombined phone number fragments correctly include an international dialling code.

Earlier in the article, we already established that determining which country code to apply would be difficult. For the purpose of this demo code, we will assume that we need to be applying a UK code.

The code inspects the number, performing a few checks:

Non numeric characters are removed, with exception of the "+" symbol.
The leading zero of the national area code is removed.
If not already present, the international prefix is added.

public WordProcessingService ReformatAsUKInternational()
{
  List<string> listReformattedNumberWords = new List<string>();

  foreach (var word in _listProcessedWords)
  {
      string numbersOnlyWord = GetOnlyNumbers(word);

      if (word.Substring(0,1) == "+")
      {
          listReformattedNumberWords.Add($"+{numbersOnlyWord}");
          continue;
      }

      if (numbersOnlyWord.Substring(0, 1) == "0")
      {
          listReformattedNumberWords.Add($"{_countryPrefix}{numbersOnlyWord.Substring(1, numbersOnlyWord.Length-1)}");
          continue;
      }

      listReformattedNumberWords.Add($"{_countryPrefix}{numbersOnlyWord}");
  }

  _listProcessedWords = listReformattedNumberWords;

  return this;
}

Problems With OCR

I've already said that this is a hard problem to solve and that the solution presented in this article is far from robust. Similarly, however clever the OCR process is, it is far from foolproof.

To close this article, we'll have a brief look at some of the problems that have been thrown up with our own test material:

OCR incorrectly detecting lines of text

If you've followed along with the example, you may have already spotted that the phone number "(07700) 1234567" was not detected correctly in the handwritten-text version of the test.

The reason for this is not because the OCR process fails to recognise the words, nor is it because our own code here fails to re-assemble the word.

The problem is that the OCR process incorrectly identifies which line that the text should appear. In this example, the OCR incorrectly identifies the second word to appear sooner in the sequence of words (i.e. "123456" appears before "(07700)"), therefore causing our own process to attempt to assemble the phone number in the incorrect order:

In the following code block, I have extracted out the raw data as returned from the OCR API, as this shows you the fragmented nature of the process along with how the data can be returned out of the expected sequence. What is more reassuring though, is that we can see our loop for reassembling phone numbers seems to work fine, despite being broken up into many smaller words:

...
call
me
on
+
4
4
1234
567
890
or
123
45
6
(
0
7
700)

OCR incorrectly identifying characters

The OCR process seems to work pretty well with printed text, but handwritten text is still a "big ask" to assume that results will be returned reliably. One must remember that a human reading a number can apply "the context" of what they see, not just the literal guess of "what they see", as the computer does.

To demonstrate an example of a problem with the OCR process, we can see that the handwritten example contains a number zero marked with a cross-line (as you see shown in many fonts). When drawing the handwritten-text sample, I had deliberately added the cross-line, as I had hoped that this would have made the character easier for the OCR process to interpret, so as to avoid confusion with the "o" or uppercase "O". As it turned out, this was not the case, as that "0" (zero) character was incorrectly recognised as a "$" (dollar character)

...
my
new
phone
number
is
535
$
199
please
...

Disclosure

No third party (i.e. Microsoft or Twilio) compensate me for my promotion of their services. However, my partner Layla Porter is an employee of Twilio Inc, in the capacity of a developer evangelist (and I very occasionally hang out with other Twilio evangelist) so I have an association and bias to recommend their services.

Scale your application globally with Azure Series - Part 3 - Azure Front Door

Jim Mc̮̑̑̑͒G — Thu, 24 Oct 2019 10:14:44 +0000

This article was originally published at blogs.siliconorchid.com on 30-May-2019

This is part three of a three-part series that shows you how to use Azure to distribute your application globally and ensure that users get the best experience.

In part 1 of this series, we talk about how to scale an application and look at a demonstration application.

In part 2 of this series, we look at using Azure CDN to distribute static content.

In part 3 of this series, we look at using Azure Front Door to globally distribute an application back end hosted in dual Azure Regions.

Use Azure Front Door for, well, everything!

If you have an application that comprises a mix of static and active content (e.g. a JavaScript SPA client consuming a backend that you provide), Azure Front Door is a service that can benefit all aspects, simply by making use of it.

Azure Front Door is a newly-available "Network Entrypoint" service from Azure, which became generally available in April 2019. You should not interpret "newly-available" as meaning that this is a completely new service because it isn't. This is a tried and tested technology that Microsoft has been using with their own services (e.g. Office365 and Xbox Live) for about 5 years.

Front Door is pretty awesome and offers tonnes of features that can improve most applications by offering a layer of caching, acceleration, global distribution, and failover.

An interesting feature to be aware of is that you don't necessarily have to have a backend powered by Azure to use and benefit from the service. By simply overlaying Front Door, over your existing service, wherever they happen to be hosted (they don't have to be in Azure), you could potentially see some performance improvements for users.

In this demo we separated static content to use Azure CDN, so as to demonstrate the use of the CDN in isolation.

If you are choosing to use Azure Front Door, you don't separately need to use the CDN because Front Door provides global distribution for static content also.

The Microsoft network

To begin to explain what Azure Front Door is, we need to have a little background understanding of the infrastructure that underpins Azure.

Microsoft owns and operates its own global network, which is used to connect its various data centre locations together.

This network utilises high capacity dedicated connections, which are not considered to be part of the public internet. This means any traffic that is within the Azure network will benefit from increased performance. As a paying Azure client, network interactions that you make within the service will be using this high-performance dedicated network.

For example, imagine you had a web API application hosted in the East US Region, that connected to a SQL database hosted in the West US Region. The traffic between your two servers (i.e. queries and data results) would traverse the private Microsoft network. However, onward traffic between your users and the web API server (e.g. JSON) would use public networks.

This global network represents not only the large Azure Region data centres (reported by Microsoft to be 54 in number, at time of writing) but also a huge number of satellite locations which form part of their wider network.

Microsoft is a little coy about detailing exactly the makeup of their network (no doubt because of competitive and national secrecy reasons), but according to this document which markets their network to enterprise users, at time of writing, there are:-

"more than 130" Edge Node locations , and
"more than 60" CDN points.

"Edge Nodes", in particular, are of interest to us because an "Edge Node" is a way to create additional well-connected Points-Of-Presence for the Azure network.

In other words, from your own location (at home, in the office, etc), rather than having to make a network connection across the public internet to a major Azure Region, you can instead make the shorter connection across the public network to nearby "Edge Node". From that point, you maintain your contact with that node, which in turn makes requests to your underpinning application, across Microsoft's high-performance dedicated connection.

An analogy that may help you visualise this, is to imagine that you live in a rural village and that you need to travel to a major city to collect a parcel.

Normally, you would use the public road network to drive there by car. This would typically comprise of a journey on local roads and major highways, that are probably congested and across multiple, different junctions.

Imagine instead, that you just needed to drive to a local town where you would meet a courier. This courier would in turn use a private autobahn, with little congestion and potentially higher speed limits, that connects directly from the town to the city. The courier could quickly zip back and forth to the city to get your parcel for you, taking much less time.

The following graphic, duplicated from here, gives fascinating insight not only into the location of Regions and Nodes, but also an approximation of the physical routes that comprise the infrastructure links:

What is Azure Front Door?

Azure Front Door is a premium service which gives your application access to this network of Edge Nodes.

Without making any modifications to your existing application, just by adding Front Door as a service layer, you can potentially improve network access performance for your users.

Instead of having to traverse the public internet to connect directly to your application, hosted in an Azure Region, your users can now take advantage of the Microsoft network, as previously described.

The service offers several features including geographic load-balancing. This is the feature that we'll demonstrate in this article, as we'll dynamically connect our users to a geographically closer service.

For other features, check out the Microsoft Front Door: Product summary page. It's worth noting that the overhead of SSL encryption can be offloaded from your application server and onto the Edge Node. Also worth noting is that Front Door provides firewall and DDOS protection.

Create Azure Function App Service Plans in multiple Azure Regions

To demonstrate a global infrastructure, we're going to need to create App Service Plans in at least two separate Azure Regions.

For the purpose of our demo, we're going to provision one in UK South (London) and the other in West US (California). We'll use the following settings and resourcename(s). When you come to do your own version, you'll need to use your own unique names:

App Name(s) : GlobalScalingDemoFuncAppLondon and GlobalScalingDemoFuncAppCalifornia
Resource Group Name : GlobalScalingDemo
Hosting Plan : "Consumption Plan"
Location : "UK South" and "West US"
Storage : globalscalefuncukstorage and globalscalefuncusstorage

We also need to create a pair of corresponding Application Insight Resources. These will become important to have available later in the demo, as they will show us how the services are being utilised.

Earlier, we discussed that our Azure Function requires a small piece of configuration to be included, which will be used to display the name of the Azure Region in effect.

Go ahead and add the following configuration into both of your Functions. You should provide a value which is appropriate for the Azure Region you are using.
- Configuration Key : CurrentHostingLocation. Value : London

If you are unfamilar with Azure Function configuration, please refer to my earlier article where I demonstrate how to create configuration settings.

Both sets of Azure Functions also need to have a CORS entry, set up independently on each resource, in order for our web client to be able to successfully access these API resources.

In this example, we will need to add a CORS entry for the website https://globalscalingdemocdnendpoint.azureedge.net

If you don't know how to update the CORS entry in Azure Functions, I have detailed the steps in a previous article.

Publish the Function to both Azure Regions

This article is not intended to be a tutorial of how to publish Azure Functions to the cloud. If you don't already know how to do this, please refer to my previous article where we walk through one way to publish, directly from Visual Studio.

From Visual Studio 2019, we'll now publish our Function application directly to Azure. We need to do this twice - to both Azure Regions. This means that you'll end up creating two Deployment Profiles.
With the Functions deployed, the easiest way to test that they are working correctly and returning the expected result, is simply to use our web browser to check for a response. For me, the URL(s) to test are:-
- https://globalscalingdemofuncapplondon.azurewebsites.net/api/CalculatePrimeNumber
- https://globalscalingdemofuncappcalifornia.azurewebsites.net/api/CalculatePrimeNumber

If everything is working correctly, you'll see the following message displayed in your browser:-

Hello, there are 41539 prime numbers in the range 0 - 500000. This result was calculated in London

Note: By the time I publish this article, I will have disabled my Azure Function App Service, as I don't want to run up an unnecessary bill - so please don't expect the above links to be live and working - they are purely to provide a realistic and consistent context to talk about.

Create the Azure Front Door service

Now we're finally getting to the exciting part.

In the Azure Portal, Create a resource and search for "Front Door". Select Microsoft Front Door from the list and click Create
Select your existing Resource Group - for me, this is "GlobalScalingDemo"
Select the option Next : Configuration (don't choose "Review + Create" just yet)
In the panel "Front End Host", click the + symbol in the top-right corner.
- A blade will slide out from the right, prompting you to enter a Host Name.
- I entered GlobalScalingDemoFrontendHost, but you will need to provide your own unique name.
- I left the "Session Affinity" option in its default "off" setting, as this isn't relevant to this demo (session affinity is a way to "glue" users to a particular service on subsequent visits, which could be relevant if your application has user persistence of some description).
  - Click Add to create the front end host

In the second panel, "Backend Pools", click the + symbol in the top-right corner.
- Another blade will slide out from the right, prompting you to enter a "Name".
- I entered GlobalScalingDemoBackendPool, but you will need to provide your own unique name.
- You now need to register backend services. For us, this will be the pair of Function App Services that we created earlier.
- Click the "Add Backend" option.
  - When prompted for "Backend Host Type", choose "App Service"
  - Under the option for "Backend Host Name" choose one of our Function Apps
- Repeat the process of "Adding Backend" a second time for our other App Service.
- Under the option "HEALTH PROBES", leave the setting "interval" at its default "30sec". We'll return to talk about this subject in a moment.
- Leave the "Load Balancing" options at their default setting.

In the third panel, "Routing Rules", click the + symbol in the top-right corner.
- Another blade will slide out from the right, prompting you to enter a "Name".
- I entered GlobalScalingDemoRouting, but you will need to provide your own unique name.
- Leave all other option at their default setting.

Finally, click Create button to validate, review and create the new resource.

Azure Front Door Health Probe

Before we move on to testing the new solution, let's talk about the topic of "Health Probes" (one of the settings we just looked at).

Azure Front Door polls your resources to ensure that they are still in a healthy condition.

Should a backend resource become unresponsive, then the Front Door service can detect this and "fail over", meaning that users will be directed to an alternative, healthy, resource, albeit, with increased latency.

Something to consider about this constant health-checking is that your underlying Azure Function will be triggered each time a check is made.

For a production system, this is not an undesirable thing, as failures can be rapidly detected and responded to swiftly.

If you are just experimenting with the technology, be conscious that this will generate a low-level amount of activity. In the case of Azure Functions, the current pricing model provides you with a surprisingly generous free quota of usage, so it shouldn't cost you anything extra.

[Article Update 12 June 2019] : I was speaking with my friend MVP Shahid Iqbal last night at a community meetup. He raised an interesting point about the traffic generated by AFD's health-check probe.

When I originally wrote this article, I did consider that this may be an issue, but then dismissed it on the basis that calling something like an Azure Function API, even a few thousand times a day, would be an inexpensive operation.

What Shahid has highlighted, to make me reconsider this opinion, is that if you call other types of default resource (specifically, a default webpage), this can actually consume a meaningfully large amount of bandwidth (that you will be charged for).

Researching this topic does not currently bring up much information, but I did find this stack-overflow article.

Therefore, I would recommend creating a simple REST API that does nothing more than return an HTTP-200 OK response. This can be used as a lightweight dedicated-responder to the health-check probe. You will need to explicitly register the URL to this API in the "path" field of the "backend pool, health probe" configuration in Azure.

Normally, if an Azure function is not used for a while, the platform unloads the service from memory and the function goes dormant. This is called "going cold". The impact of this is that the next person to request the resource will experience a "cold start" meaning they could face a slight delay, whilst the function is started back up.

According to this recent article by Mikhail Shilkov, benchmarks indicate that a typical cold-state for a C# Azure Function 2.0, is ~3 seconds.

A useful side-effect of using Front Door is that because your App Service is constantly being polled, it will never go cold, meaning that it will always be in a state ready to immediately serve the next user.

Check that all the Azure resources have been created

Before we move further, let's just take an inventory to make sure that we really have set up all the Azure Resources that this demonstration requires.

In the Azure Portal, navigate to the homepage and select your Resource Group. For me, this is called GlobalScalingDemo. Click on that Resource Group to view a list of resources contained within.
Having followed all the steps in the article, we should have a total of 12 separate resources. Please refer to the following screenshot as a reference. As a reminder, the resource names and regions that I have used are intended for this demo and, in many cases, you will have had to use your own unique names:-

Testing the System

With the Azure Front Door resource created and configured, the easiest way to check that it is working correctly is to use your browser to request a result directly from the "Frontend Host Name", the service API endpoint. For me, I used this URL:

https://globalscalingdemofrontendhost.azurefd.net/api/CalculatePrimeNumber

A successful result should respond with a message that indicates it was generated in the Azure Region nearest to you. For me, using a native internet connection, I would expect London.

At this point, we should now update our original JavaScript client with this endpoint. In the file ....\GlobalScalingDemo\src\GlobalScalingDemo.Web\wwwroot\js\client.js you need to update the variable serviceEndpoint like this:-

const serviceEndpoint = 'https://globalscalingdemofrontendhost.azurefd.net/api/';

Having updated this setting, you should redeploy the JavaScript file, by copying it to the Azure Storage Container, used by the CDN.

How to test that the location-based routing is working correctly?

There are a couple of ways we could check that the service is routing to an appropriate Azure Region (for example, a low-tech way might be to ask a friend in another country to check for you).

A more scientific way is to alter your Internet Point-of-Presence (POP). There are a few ways you might do this:-

Use a VPN (if you work for an international company - or - use a VPN service).
Remotely connect to a distant machine you have access to - e.g. temporarily provision an Azure VM - and operate this using a Remote Desktop Connection.

For the purpose of testing, I used a private VPN service to change my POP. You can watch my test in the following animation, but briefly, the steps I made were:-

Use VPN to connect to a POP in Frankfurt, Germany
Navigate to the CDN-hosted client app in the browser.
Wait for the application to return a result from the backend.
Verify that the result identifies as having originated from London (which is the nearest service to Germany).
Disconnect VPN and reconnect to a different POP, in Denver, USA
Refresh the browser window; the client app will make a fresh request to the backend.
Verify that the result identifies as having originated in California.

Use Application Insights to understand what's happening with your service

Firstly, let's make sure we understand how to see what's actually going on in Azure.

Decide which of the two App Service resources we are going to inspect. Initially, you should choose the Region which you know is geographically closest to you. For me, this is my "London" version.
From the Azure Portal, locate and open the Application Insight resource that corresponds with this App service. For me, this is called "GlobalScalingDemoFuncAppLondonAppInsight"
With the Application Insight blade open, locate the option "Live Metrics Stream" and select it.
In the panel that appears, scroll down towards the bottom so that it displays the section "Servers"

This report is really interesting to watch, as it shows the incoming requests placing a load on the service. It also shows the number of actual Azure Function host instances that have been [automatically] provisioned for you. If a service is worked hard, we can expect to see extra instances appear.

A low-tech way to test your service could be to refresh your browser window really quickly, so as to trigger a number of HTTP calls. However, you'll probably break your mouse button before making much of an impact on Azure.

Instead, we're going to use automation tools to create an artificial workload. There are a couple of ways that we could do this.

One of my favourite tools, Postman, has a feature which allows you to trigger a queue of API requests. You can read about the amusingly named "Postman Collection Runs" in this article : Postman Learning Centre : Intro to collection runs

For this demo, however, we're going to use a load-testing tool called Artillery.

Download and install Artillery. Installation is as simple as running the following command ( but you can follow the official instructions on the website: Getting Started With Artillery):-

npm install -g artillery
Next we want to create a load on our server. The following command will connect to our Front Door global endpoint and create 20 virtual users, each of which call the API 50 times. The process is set to run over a period of 30 seconds.

artillery quick --count 20 -n 50 --duration 30 https://globalscalingdemofrontendhost.azurefd.net/api/CalculatePrimeNumber/

When you have started the test, you should watch Application Insights to see how your service reacts. You should see results similar to the following animation:-

Wrap up

When not to use a CDN - if you have an application with actively-generated server content, e.g. MVC), which has only a very small amount of static content such as a tiny amount of CSS or JavaScript) the overhead of an additional request to another network resource may not add up. Consider in-lining this content into your page.

Disclosure

No third party (i.e. Microsoft) compensate me for my promotion of their services. I have no bias to recommend their services.

Thumbs Up

Thanks to Layla Porter for being my document reviewer. I don't have a team to back me up and sometimes you need another set of eyes!

Thanks to Gerardo Lijs for suggesting an alternative take on the prime-number calculation, which was both more concise and better saturated a CPU. This originated in the book C# 7.0 in a Nutshell.

Thanks to Shahid Iqbal for highlighting a potential issue related to the health-check polling mechanism.

Scale your application globally with Azure Series - Part 2 - Azure CDN

Jim Mc̮̑̑̑͒G — Thu, 24 Oct 2019 10:14:31 +0000

This article was originally published at blogs.siliconorchid.com on 29-May-2019

This is part two of a three-part series that shows you how to use Azure to distribute your application globally and ensure that users get the best experience.

In part 1 of this series, we talk about how to scale an application and look at a demonstration application.

In part 2 of this series, we look at using Azure CDN to distribute static content.

In part 3 of this series, we look at using Azure Front Door to globally distribute an application back end hosted in dual Azure Regions.

Use Azure Content Delivery Network (CDN) for static content

If your application has only static content, such as a blogsite like mine, or a JavaScript application that only consumes APIs from third-parties, then using a CDN is a perfect way to distribute your files.

What is a CDN?

A CDN is a globally distributed network of servers. Data is replicated in a large number of different geographic locations, so as to bring copies physically nearer to users around the planet.

Each location of the network is called a "node" (or "edge server").
CDNs work by seeding from a single source of data and replicating copies out to the various nodes on the network.
Something to be aware of is that when you update a file at the source, you cannot expect the content to update across the network instantly - it can sometimes take a few minutes to propagate globally.
Often, a single country may have multiple nodes, located in different cities, to further increase the chance of geographic proximity to a user.
When requesting a piece of data, the network determines which node will be fastest for the user and serves from that node accordingly.

Even if you've never set up your own CDN, there's a very good chance that you are already familiar with consuming content from one, because it's very common to put a reference to an open-source JavaScript library/resource (e.g. Bootstrap) as a link on a webpage. There are several benefits to doing so:-

Files can be requested and downloaded more quickly (because of physical proximity).
If you are referencing a popular shared resource (e.g. many sites reference the same copy of bootstrap from a Google CDN), there is a good chance that your user may already have a locally cached copy of the resource.
It may save bandwidth charges if another organisation is responsible for hosting shared content.

How does a CDN apply to you?

For many developers, the de facto place to publish their entire website content will be the tried and trusted web server (or perhaps a derivative, such as an Azure WebApp Service).

Such a website will likely be used to serve up both active content, e.g. MVC pages and RESTful APIs, and static content such as stylesheets, images, SPA payloads, etc.

The static content can be a barrage of many smaller files, each of which your server needs to process. This incurs a load on resources such as CPU, memory, network bandwidth, etc.

If this is how you currently work, I would strongly recommend that you review which parts of your application are purely static content and consider publishing these separately to a CDN. Your users could benefit immediately from improved download times and your servers could benefit from a reduced overall traffic load.

Static content doesn't just represent obvious items such as .css and images, it could also represent the compiled payload of your JavaScript SPA application which even when minified could easily be a large download.

You should note that despite having huge capacity and global reach, CDNs are relatively cheap to provision. You can read about Azure CDN charges here.

The Azure Portal provides an element of choice and convenience, directly offering alternative services from both Akamai and Verizon.

Something that you may find interesting, is the list of physical CDN node locations. Check out this link for a list of Azure CDN locations.

Unrelated to Azure, but definitely worth mentioning, if you are an individual with a personal website e.g. a budding blogger like me, Cloudflare offers a free pricing tier which could be perfect for you!

Create an Azure Resource Group

We've been covering a lot of theory so far, it's about time we made a start on our demonstration project.

Firstly, we need a way to keep our Azure resources grouped together logically, so we need to make a Resource Group

If you don't know how to create a Resource Group, refer to this Microsoft Documentation Guide : Manage Azure Resource Manager resource groups by using the Azure portal
In this demo I have created a new group called "GlobalScalingDemo"

Create and configure an Azure Storage Static Website

A CDN requires a source of data to work from. In our demo, we'll be using an Azure Storage Static Website for this purpose.

It's worth clarifying that an Azure CDN does not need a website as it's source - for a couple of years now, it has been possible to connect a CDN directly to files in a storage container.

There is an easy-to-overlook reason as to why we specifically want to use the recently new Azure Storage Static Site option - this relates to the default webpage (and default "not found" page). Without a web server, Azure Storage simply serves up files - it doesn't understand the concept of a default web page, meaning that index.html has no significance. The only way you could load the homepage would be to explicitly ask for it in the URL i.e. something like www.mywebsite.com/index.html. However, with the Static Site feature enabled and configured, we can use a naked URL and correctly serve up the default page as expected i.e. just www.mywebsite.com.

If your application has no requirement to serve a homepage, you can bypass the advice to create a Static Website and simply connect the CDN directly to the exposed URL of the storage container (making sure that the container has public visibility turned on!)

We now need to create an Azure Storage Static Website. If you don't already know how to do this, you should refer to my previous article, which details exactly the steps you need to take.
In this demo, I've given my resource the name globalscalingdemostorage which exposes an endpoint called https://globalscalingdemostorage.z6.web.core.windows.net/ - but you will need to provide your own unique name.
When the new resource has been provisioned, you will need to copy the content for the demo website across to the $web container. There are a couple of ways you could do this, but we discussed using the Azure Storage Explorer in the previous article.

If you are uncertain what content needs to be copied, it should be everything in the folder ....\GlobalScalingDemo\src\GlobalScalingDemo.Web\wwwroot

Please note that at this point in time, we have not set up a backend system, so we don't know what the endpoint will be. As such, we cannot set this value in JavaScript, so the client app will be expected to error.

Create and configure the Azure CDN

Now that we've created a website as a source, we can now go ahead and create the actual Azure CDN.

From your resource group, click the Add new resource button and search for "CDN"
From the "Microsoft CDN" blade, click Create to start the process.
Populate the fields. For some of these fields, you will need to provide your own unique name. For the demo I used these settings:
- Name: "globalscalingdemocdn" - noting that I suffixed this resource name with "cdn" to make it clear what this was.
- Resource Group: select the resource group that you created earlier. For me, I used "GlobalScalingDemo".
- Resource Group Location: This setting is greyed-out and cannot be edited - it inherits from the location associated with the parent resource group.
- Pricing Tier: You have a number of options here, with different providers offering different types of service at different price points. You can review a matrix of features here. For the sake of this demo, we're going to choose the default "Standard Microsoft".
- We want to be able to define a custom URL Endpoint for our CDN, so go ahead and check the tickbox for "Create a new CDN Endpoint now". Doing so will reveal further options:-
- CDN Endpoint Name : "globalscalingdemocdnendpoint" - noting that I suffixed this resource name with "cdnendpoint" to make it clear what this was.
- Origin : Now this is important! You should resist any instinct to select the option called "Storage" and instead choose "Custom Origin". The difference is that the "storage" option is used to connect the CDN to a regular storage container, whereas when we use a static website, we need to connect our CDN to the endpoint of that static website instead.
- Origin Hostname : You need to use the primary endpoint of the Azure Storage Static Website. Be careful cutting+pasting the value though, as you need to remove both the leading "https://" and the trailing "/". For my demo, this means I would enter globalscalingdemostorage.z6.web.core.windows.net into the field - but you will have to provide your own unique version.

Note: There is a bit of an "unpolished user experience" in the Azure Portal UI, that you should keep an eye out for, related to the option "Resource Group Location".

An example of this manifested whilst researching this article. I had originally selected "UK South" to be the location of my resource group. When I came to create the CDN, the option showed "Australia", which was disabled (greyed out) and prevented me from changing it. When I tried to create the CDN resource, the portal threw an error and wouldn't let me proceed.

Not all Azure Regions (datacentres) are equal, with some providing more services than others. Although a CDN is inherently a global service, it still needs to be allocated to an Azure region (the resource metadata needs to be associated with something).

The problem was that only certain Azure Regions support a CDN, but this isn't necessarily apparent up-front.

Evidently, my underlying "UK" selection couldn't be matched to any of those valid regions, in the drop-down list, so "Australia" was being selected as it was alphabetically the first.

As such, the fix was to create a replacement resource group, selecting a major Azure Region (I happened to use Europe West instead).

That's pretty much all you need to do to get a basic working result!

If you navigate to the CDN-Endpoint resource in the portal and view the "overview", it will confirm to you what the Endpoint Hostname is. If you like, you can open this link in a browser window and view your globally-distributed website right now!
As a reminder, in this example, that CDN-serviced endpoint is as follows:

https://globalscalingdemocdnendpoint.azureedge.net

Yours will look similar to the following:

https://<your CDN Endpoint Name >.azureedge.net

There are a few other things worth talking about:

You can, of course, assign your own custom domain to the CDN. This is beyond the intended scope of this article, but you can follow this Microsoft Tutorial : Add a custom domain to your Azure CDN endpoint .
A feature I really, really like about Azure CDN is that there is an option for "complete certificate management".
- This means that HTTPS is handled for you and that Azure automatically provisions an SSL certificate, for your custom domain, for free.
- If, like me, you're more accustomed to having to purchase an SSL certificate, which can be really expensive!)You'll also be used to generating the actual certificate file, uploading it to a provider and remembering to renew it, etc - then you'll be delighted to hear that this expensive chore just goes away.
- You can read more about this in the Tutorial: Configure HTTPS on an Azure CDN custom domain

The only limitation I have discovered with using a CDN, is that you cannot assign the CDN to your Apex domain (i.e. a "naked domain" without any subdomain). For example, you cannot assign "https://mysite.com" - it has to include a subdomain, such as "www" or "blog" etc.

If you're familiar with this subject, behind the scenes, you will be using CNAME records (which are domain-name-based) in your DNS control panel and not A records (which are IP-based). I had briefly hoped that using a DNS ALIAS record (a DNS workaround offered by some registrars) could have been a solution, but no, it simply isn't supported. Because of the dynamic nature of the CDN service, this does actually make sense if you think it through! Just in case I was providing incorrect advice, I checked with Azure Advocate Jim Bennett who confirmed this for me.

Next, in part three, we'll be looking at how you can use Azure Front Door to globally distribute all parts of our application, along with one way how we can scale by using multiple instances hosted in different data centres.

NEXT: Read part 3

Scale your application globally with Azure Series - Part 1 - Introduction

Jim Mc̮̑̑̑͒G — Thu, 24 Oct 2019 10:14:16 +0000

This article was originally published at blogs.siliconorchid.com on 25-May-2019

This is part one of a three-part series that shows you how to use Azure to distribute your application globally and ensure that your users get the best experience.

In part 1 of this series, we talk about how to scale an application and look at a demonstration application.

In part 2 of this series, we look at using Azure CDN to distribute static content.

In part 3 of this series, we look at using Azure Front Door to globally distribute an application back end hosted in dual Azure Regions.

If your application has users located around the globe, you need to take extra architectural steps to maintain great performance, whilst presenting a consistent and seamless presence for all.

In this article, we're going to discuss some of the issues that you need to consider.

We'll also introduce you to two key Azure services that may help you to address those global distribution challenges:-

Azure CDN - for distributing static content
Azure Front Door - for distributing and accelerating all aspects of your application/service.

To demonstrate these services in action, we're going to create a small demo application that comprises:-

a basic web client, created using static files and published to an Azure Storage Static Websites
a simple backend, with a single API method, which uses Azure Functions

We'll then:-

configure services that scale the application globally
show one way to create a test that demonstrates how the system reacts under a simulated load.

Local Scaling

Before we dive into global-scale considerations, let's just review how our computing resources can scale at a single location - a single datacentre or "Azure Region".

One requirement is that we need to be able to minimize our hosting commitments, in order to keep costs down for those times when we only have a small number of users.
We also need to be able to quickly and dynamically increase our computing resources in order to serve significantly more users, should demand change.

Smartphone users, in particular, don't adhere to predictable hours of access. When combined with unpredictable and spiky consumption patterns that often stem from social media trends and other viral behaviours, resource demands could potentially shift dramatically in a very short period of time.

Vertical scaling - Back in the early days of the internet, the provisioning of more powerful servers used to be our first port-of-call to address the issue of increased computing demand. It is still something we can do, but in a majority of cases, this shouldn't be seen as your primary solution. This is because:-
- It cannot be instantly and seamlessly provisioned. It potentially requires a period of downtime as we move from one server to a more powerful one. Solutions such as the Azure WebApp Service have improved matters by making this relatively quick and easy, but there is still a change-over.
- Vertical scaling has diminishing returns - an increasingly more powerful server does not yield proportional returns in performance, relative to its cost.
- The scope of improvement is ultimately finite if you are using a single instance. It doesn't matter how powerful a single machine can be, the internet can and will overwhelm it.
- Vertical scaling should only really be considered if your service is of some specialist type or resource, that can't distribute across multiple systems (e.g. an API that processes an extremely complicated or large set of data, such as a simulation etc, which absolutely requires access to a large pool of CPU and memory resources). Even then, it's likely that you will require a pool of machines to service a large audience.

Horizontal Scaling - For a vast majority of scenarios the best solution is to provision multiple separate servers, so as to distribute processing in a parallel, load-balanced, configuration.
- This solution offers both the greatest outright performance potential, along with the best "bang for buck".
- Typically, by using a greater number of lower-specification, and therefore relatively less expensive servers, costs can usually be kept even further down (when compared to using fewer, but higher-specification servers).
- When combined with elastic/automatic scaling, additional servers can be brought online automatically, as demand dictates. When server load is reduced, we can automatically de-provision the extra servers, allowing money to be saved.
- Options such as Azure WebApp Service, a PaaS (Platform as a Service), easily provide you with these options.

Serverless architectures are an evolution of horizontal scaling.
- Instead of invoicing resources in terms of "instances of a server", when choosing the "consumption" pricing model, computing resources are provisioned completely dynamically, based upon a calculation of the actual time and resources used.
- This architecture can be incredibly appealing as it offers the potential to make significant cost-savings, as we are no longer paying for dormant or underutilised servers.
- Just like elastic-scaling, when demand rises, the cloud provider can keep allocating additional computing resource as needed.

n.b. You have the option to provision Azure Functions on a "traditional" service plan if your circumstances require this.

Global distribution

We've just talked about how, with modern cloud services, we can easily scale a system, in one location, to meet demand. But how does this work with respect to serving to a global audience?

As the physical distance between the data centre and your user(s) increases, there is an unavoidable rise in "latency" (not to be confused with "bandwidth").

It doesn't matter if you have unlimited computing resources in one location, basic physics (the speed of light for signalling over very long distances) and the limitations of our technology (the fact that traffic needs to route across multiple networks to reach its destination) will combine to slow down performance.

To give context to this discussion, I conducted a crude experiment to explore the impact upon latency as distance increased. I ran dozens of pings to a selection of different DNS servers around the world. DNS servers were chosen, as they should be inherently fast with low latency.

I'm based in the UK, so for my first test, I found a list of servers in London. My average ping across the sample was ~10ms.

Pinging a selection of servers in New York City, I averaged ~75ms.

To demonstrate communicating with somewhere on the opposite side of the globe, I then repeated the process down under, in Sydney, averaging a ping of ~260ms.

This shouldn't be considered as an authoritative result. Network performance is a transient thing and this was a brief one-off test. For example, I may have been crossing a part of the internet that had a largely sleeping population at the time!.

Even so, this quick experiment does indicate that a global round-trip could incur an increase in latency in the region of 26x!

By this point, there's a good chance that you've already guessed that part of the solution is to bring your application servers physically closer to your users.

You can address this by hosting multiple instances of your service in different, geographically distributed, data centres. Cloud providers have amazing global coverage and make it easy for you to do this.

So the proposition becomes:-

Q: "how do we set up multiple geographic regions, with users automatically connecting to the fastest host, whilst still presenting a common set of endpoints?"
- A: we require a service that offers "Geographic Load Balancing"

… and this is where Azure Front Door comes in.

What's our demonstration going to be?

For our demonstration application, we're going to:

create a basic web client, using static content.
use Azure Functions to create an HTTP-triggered endpoint.

From my exhaustive research, I have discovered that there is an international shortage of APIs that calculate prime numbers, so we're going to create an Azure Function that fills this shortfall.

Ok, I may have completely made up the requirement in that last sentence.

The real reason we're going to be calculating prime numbers, is because it creates a computational load and can typically take a few moments to complete.

Later in this article, we'll be looking at one way to visually demonstrate how Azure Functions scale with demand, so we want to do something that will make the platform work a little bit harder!

You should clone the demonstration source code from the GitHub repository, here : https://github.com/SiliconOrchid/GlobalScalingDemo.git

Create an Azure Function to calculate prime numbers

This article is not intended to be an introduction or tutorial on how to use Azure Functions. If you are not already familiar with this subject (either how to write the code, or how to create and publish them to Azure), please refer to my previous series Chat using Twilio WhatsApp API, SignalR Service & Azure Functions
. You should also read the Microsoft Documentation: An introduction to Azure Functions.

In the demonstration source code, we have a Visual Studio 2019 project called GlobalScalingDemo.Function and specifically we are interested in the code for the Function itself which is ....\GlobalScalingDemo\src\GlobalScalingDemo.Function\CalculatePrimeNumberFunction.cs:

The complete source code for this file looks like this:-

using System;
using System.Threading.Tasks;

using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;
using System.Linq;

namespace GlobalScalingDemo.Function
{
    public class CalculatePrimeNumberFunction
    {
        [FunctionName("CalculatePrimeNumber")]
        public async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = null)] HttpRequest req)
        {
            int primeNumberRangeSize = 500000;
            long result = CountPrimeNumbers(primeNumberRangeSize);

            string currentHostingLocation = Environment.GetEnvironmentVariable("CurrentHostingLocation");

            return new OkObjectResult($"Hello, there are {result} prime numbers in the range 0 - {primeNumberRangeSize}.   This result was calculated in {currentHostingLocation}");
        }

        public long CountPrimeNumbers(int rangeSize)
        {
            return ParallelEnumerable.Range(1, rangeSize)
                .Count(n => Enumerable
                    .Range(2, (int)Math.Sqrt(n) - 1)
                    .All(i => n % i > 0)
                );
        }
    }
}

In the above code, I would bring your attention to a couple of things:-

The variable primeNumberRangeSize is used to define a range of numbers to check for prime numbers. This effectively controls the amount of processing work that the Function needs to undertake.
- If you want to increase the amount of time the Function needs to run for, put a larger number in here.
The variable currentHostingLocation is used to obtain a label declaring the location that the code is running from (e.g. "Local", "London", or "California").
- This is added to the textual output of the Function.
- Later in the article, when we come to test the system, this will help us to easily recognise from which data centre the function being executed.
- This configuration information will need to be provided either locally in the local.settings.json or defined in Azure for each instance of the Function App.
Don't worry too much about the sample code itself. The point of this exercise is to create an arbitrary and artificial CPU load, so slow code is fine!

Create a basic web client

Our web client is intended to be as simple as possible, so comprises:-

a single html page : ...\GlobalScalingDemo\src\GlobalScalingDemo.Web\wwwroot\index.html
a simple JavaScript file : ...\GlobalScalingDemo\src\GlobalScalingDemo.Web\wwwroot\js\client.js
minor cosmetic components, such as a .css file and use of Bootstrap

The purpose of the client app is simply to trigger an HTTP request to our backend, when the page is first loaded.

When a response is received, a default message that reads Waiting for server... is replaced with the message returned from the back end.

The JavaScript client code looks like this:-

const serviceEndpoint = 'http://localhost:7071/api/';   // include trailing slash
//const serviceEndpoint = 'https://{your function app hostname}.azurewebsites.net/api/';
const serverApiMethod = "CalculatePrimeNumber"; // do not include any slashes

window.onload = function () {

    var messageElement = document.getElementById("messageElement");

    fetch(serviceEndpoint + serverApiMethod)
         .then(response => response.text())
         .then(text => {
            messageElement.innerHTML = text;
         }).catch(err => {
             messageElement.innerHTML = "Failure connecting to server";
         });
};

Next, in part two, we'll be looking at how to use Azure CDN to globally distribute static content.

NEXT: Read part 2

Chat using Twilio WhatsApp API, SignalR Service & Azure Functions Series - Part 3 - Cloud Deployment

Jim Mc̮̑̑̑͒G — Wed, 23 Oct 2019 18:36:25 +0000

This article was originally published at blogs.siliconorchid.com on 19-May-2019

This is part three of a three-part series that shows you a way to combine several serverless technologies, creating an online chat system that sends messages between users of WhatsApp and a real-time web app.

In part 1 of this series, we introduce you to the scenario and walk through the configuration of an entire solution, ready for local testing.

In part 2 of this series, we look at the various pieces of code that make up our solution in detail.

In part 3 of this series, we walk through the additional steps needed to setup and deploy the solution to the cloud.

Deploying to the cloud

In the previous articles of this series, we've tested the system locally and reviewed the code. In this final part of the series, we're now going to deploy the system to the cloud.

In the first article of this series, we created and configured the SignalR Service in Azure. That's already set to go, so there is nothing further we need to do with this.
We need to create and publish our Azure Functions to an App Service
We need to create an Azure Storage account and publish the front-end web app to a Static Website.

Create the Azure Function App

Return to the Azure Portal and navigate to the Resource Group that we created in Part One.
Click the Add button (at the top) to add a new resource.
Type "Function App" into the search bar and select "Function App" from the list (it should be at the top).
Click the Create button.
A "Function App Create" blade will now show. We need to provide some information:-
- Provide an app name - I used "WhatsAppChatFunction.azurewebsites.net" for this demo, but the name must be unique - so you will need to use your own name.
- Select your existing resource group from the dropdown.
- The form will prompt you to create a new Storage Account. This will be used to store the Build Artefacts (compiled code, etc.) that we will publish. These files will be used when provisioning instances of our Function. The automatically generated name is fine.
- Click the Create button - Azure will now provision the Function App.

Configure the Azure Function App

With the Azure Function resource provisioned, select it so we can edit its values.

Select the Platform Features (a tab along the top of the screen) to view an extended view of all the features we have access to.
Under the "General Settings" heading, click the Configuration option.

We need to add some Application Settings. You'll see that the list of settings already contains some values - we can completely ignore these.

Click the New Application Setting button to add a new key. You will need to repeat this process for each of the four keys that we need to add. To make things easier, you can copy both the keys and their values directly from the local.settings.json configuration file in the solution. These are the four we need:-
- AzureSignalRConnectionString
- TwilioAccountSid
- TwilioAuthToken
- TwilioWhatsAppPhoneNumber
Click Save

Note, that it's ok to enter these keys directly into the Azure application setting list. There is a potentially confusing inconsistency, in that the local.settings.json config file has these nested under a key called Values - but there is no need to include this when copying the values into Azure (i.e. you do not need to make the key Values_TwilioAccountSid).

Deploy Azure Functions to Azure

Although it's possible to write functions directly using the Azure Portal, we've already written all of our code in Visual Studio, so we'll be deploying our code from there.

With the Azure Function resource provisioned, configured and ready to go - let's go to Visual Studio so we can publish from there:-

Right-click on the WhatsAppSignalRDemo.Function project file.
Select Publish from the menu (usually near the top).
In the "Pick a publish target" dialogue, choose "Select Existing" [Azure App Service] and then click the Publish button.
A new dialogue will appear, allowing us to choose the Resource Group and then the Function Resource that you created earlier. I named mine WhatsAppChatFunction but you will have to choose your own.
- Ignore the "deployment slot" item and just keep the "Function Resource" highlighted.
- Click OK

Visual Studio will now go about deploying your code.

If you need to make a change to your code and re-publish, your "publish profile" will be retained on subsequent visits here, meaning you simply need to click the Publish button.

Create Azure Storage Static Website

If you have purely static content, such as the website in this demo (or my blogging website), then there is a way to radically slash your hosting costs using Azure.

Your instinct may lead you down the path of creating resources such as "Web Apps", but there is a new feature in Azure which means you don't need to do this!

As of Dec 2018, Azure Storage now offers static website hosting.

From your resource group, click the Add to create a new resource.
Search for "storage" and select "Storage Account".
Click Create to start creating a new *Storage Account *resource.
In the Create Storage account screen:-
- Select your existing resource group.
- Provide a unique name for the storage account. I chose "whatsappwebsitestorage", but you will need to provide your own.
- Choose a nearby location.
- Leave "Performance" as "Standard".
- Leave "Access Tier" as "Hot"
Click Review and Create to proceed.
You will be prompted to review your selections, but assuming there is no problem, carry on and create the new Storage Account and wait a few moments for the resource to be provisioned.

With the Storage Account resource created, find the option "Static Website" under the heading "Settings". The Azure portal presents a slightly overwhelming number of options, so check the screenshot below if you can't spot the option easily:-

In the dialogue that appears:-

Switch the mode "static website" to "enable".
In the text-entry for "Index document name" enter "index.html".
You can also enter "index.html" into the "Error Document Path" option, simply as a default redirect back to the homepage, because we haven't created an actual default error page. If you were to improve the system, you could make a page such as "404.html" to contain an error message.
Click Save

Inside the Blobs section of this Storage Resources, the Azure Portal will have created a specially named Container called "Web$". You can look at this yourself by:-

Clicking "Overview" to take you back to the main dashboard page of the Storage Resource
Click the prominent "Blobs" tile which will be displayed on the main dashboard (alongside other tiles "Files", "Tables" and "Queues".

You can click on this new "$Web" container, which will list any blobs that are stored inside.

If the terminology is not familiar to you, think of a "Storage Account" as a kind of disk drive, a "Container" as a kind of "folder", and "Blobs" as the actual files.

You could at this point, use the Azure Portal to upload files individually, but this will be slow and frustrating. So instead, we'll use a different tool for the job, which we'll talk about in the next section.

Before we leave this Azure Portal page, make a note of the "Primary Endpoint" setting which will be displayed. This is the URL we need to visit in our browser.
- The Url will be different in your own project, but in my case, the Url is https://whatsappwebsitestorage.z6.web.core.windows.net/

Upload the static site files into Azure Storage

When it comes to deploying files to an Azure Storage account, there are a number of ways we could tackle the problem. For example, in a more complicated Continuous Deployment system, we could get our build process to automatically drop files into the Storage Container for us.

For the purpose of this demonstration, we want to keep it simple and convenient to use.

We'll be using a Windows utility created by Microsoft called the "Azure Storage Explorer". Please follow the instruction in the following links:-

You can download "Azure Storage Explorer" from here.
You can find an Azure Storage Explorer : Getting Started guide here.

If you have followed the instructions, have installed "Azure Storage Explorer" and have provided your Azure credentials, you should be able to view your Azure Storage resources.

In the tree structure, locate and click on the $web Blob Container.
- Note, you will also see a Storage Account that we created early in this demo, which is used to store the contents of our Azure Function code … make sure you don't get mixed up as to which Storage Account you should be looking at!

We're just about to copy the files to the cloud, but before we do that, we need to update our JavaScript configuration to link to the endpoints of our published Azure Functions.

Return to the file ...\WhatsAppSignalRDemo\src\WhatsAppSignalRDemo.Web\wwwroot\js\chat.js and open it for editing.
Change the value of the constant serviceEndpoint, from http://localhost:7071/api/ to be the Url of your Azure Function Endpoint. You will have to use your own, but for me, this value would be https://whatsappchatfunction.azurewebsites.net/api/.
Using a regular Windows File Explorer:
- Navigate to the folder. ....\WhatsAppSignalRDemo\src\WhatsAppSignalRDemo.Web\wwwroot
- copy or drag-and-drop all of the files in the wwwroot folder into the main panel of the Container within the "Azure Storage Explorer".
- Note, that the contents of wwwroot is just static content, there is no complication or cleverness required - just a simple file copy.

There are alternative ways to deploy a static website - for example, this tutorial shows you how to deploy directly from Visual Studio Code.

The finish line is in sight

We've already done a lot of work by this point, but there are still a final few configuration changes that we need to make, in order for our published system to be able to work.

Update CORS on the Azure Function

The Azure Function APIs have CORS restrictions that will stop our published Web App from being able to use them. We need to add our new Web App to a whitelist.

In the Azure Portal, navigate through your resource group to you Azure Function App. In this demo, I called mine WhatsAppChatFunction.
Locate and click the "CORS" option which is found under the heading "API"

Add a new entry to the list of allowed hosts, to include the URL to your static website. For my demo, this host would be https://whatsappwebsitestorage.z6.web.core.windows.net

Update Twilio WhatsApp API callback

We're almost there now. The final task we need to perform is to update the API endpoint stored in the Twilio dashboard and replace the callback with the URL of our published Azure Function.

You will need to use your own address, but for me, this was https://whatsappchatfunction.azurewebsites.net/api/ReceiveWhatsAppMessage

Your system will now be good to go!

Wrapping up

Messaging API's. The decision to use one messaging service provider over another is largely a market decision. There are many companies who can provide solutions, so you will ultimately be comparing service costs against support and reputation. Twilio have emerged as a market leader. Their ease of use and great documentation makes them a compelling option.
Serverless Computing. We've presented the use of Azure in this series, but disregarding your actual preference of cloud provider (i.e. putting Google Cloud, AWS, Azure etc on a level playing field), the case to use serverless functions instead of more conventional hosting platforms (such as regular VMs, or an Azure WebApp etc), is not necessarily a clear-cut decision. That dreaded cliche of "it depends" still comes into play.

In scenarios where your service is not fully utilising your host platform, the cost savings of using serverless compute can be hugely significant.

An example of such a solution [that could make significant cost savings] could be an application that serves a domestic audience predominantly during business hours. That system would have a host machine that is effectively only being used for a third of the day and is sat largely dormant at other times. This is a waste of money.

In contrast, with a heavily-used system with a global 24 / 7 usage pattern, you'll need to pay very close attention to the costs. Similarly, if stable and predictable costs are important, serverless computing may not be for you if choosing the consumption model (instead choose the more familiar hosted model)

Where next?

These articles are intended for someone taking their first steps with these technologies. They are not attempting to present an architecture that you should use in a commercial product. There are aspects that we have not covered, such as security and resilience, that you should seek to explore further.

There are some standout issues that I would highlight, which could be the subject of your next steps to improve this project.

The UI and API's have no authentication. As presented they are wide-open to potential abuse (for example, there is nothing to stop you sending messages to the SendWhatsAppMessageFunction).
The individual functions communicate by calling HTTP endpoints. If there is a transient problem - e.g. the Function has not been used for a while and has "gone cold" (non-responsive) - that communication attempt could be lost.

A far better way to process tasks could be to use services such as Azure Event Hubs, Queues, Service Bus, or Event Grid. Also consider investigating the recently introduced Azure Durable Functions which accommodate the concept of chaining-together workflows of separate functions.
- For example, in this demo the BroadcastSignalRMessageFunction messages SendWhatsAppMessageFunction by HTTP. A more resilient improvement would be to recode the BroadcastSignalRMessageFunction so that it adds a message to a queue. Subsequently, we could change SendWhatsAppMessageFunction so that it is a queue-triggered function.

For now, I'll leave you with some other ideas of where you could take this project next:-

SignalR Authentication, to prevent completely open and insecure access.
JavaScript automatic reconnect to SignalR if dropped (using connection.onclose()).
Authenticated pages, where "username" can be automatically picked up from logged-in user instead of manually typing it.
Define the service endpoints used by Client into WebApp configuration (i.e. don't just hardcode them into JavaScript file, pass the endpoint through from server).
Explore using Azure CDN or Azure FrontDoor for ways to improve your static website (e.g. with your own custom domain, using free SSL).

Disclosure

No third party (i.e. Microsoft or Twilio) compensate me for my promotion of their services. However, my partner Layla Porter is an employee of Twilio Inc, in the capacity of a developer evangelist (and I very occasionally hang out with other Twilio evangelists) so I have a strong bias to recommend their services.

Thumbs Up

Thanks to Corey Weathers for hopping onto a video call with me to discuss parts of this project.

Thanks to Layla Porter for being my document reviewer. I don't have a team to back me up and sometimes you need another set of eyes!

Chat using Twilio WhatsApp API, SignalR Service & Azure Functions Series - Part 2 - The Code

Jim Mc̮̑̑̑͒G — Wed, 23 Oct 2019 18:36:01 +0000

This article was originally published at blogs.siliconorchid.com on 19-May-2019

This is part two of a three-part series that shows you a way to combine several Serverless technologies, creating an online chat system that sends messages between users of WhatsApp and a real-time web app.

In part 1 of this series, we introduce you to the scenario and walk through the configuration of an entire solution, ready for local testing.

In part 2 of this series, we look at the various pieces of code that make up our solution in detail.

In part 3 of this series, we walk through the additional steps needed to set up and deploy the solution to the cloud.

Let's look at the code

In the previous article, we spent a while looking at how to set up and run the project. Let's look at some code next!

If you haven't done so already, you should clone this repository.

Our Visual Studio project is comprised of two projects - an Azure Function project (WhatsAppSignalRDemo.Function) and an ASP.NET Core Web Application (WhatsAppSignalRDemo.Web).

Parts of the code in this demo originated from the example provided in the Microsoft SignalR Quickstart guide, so this would be a recommended read.

Another recommended resource from Microsoft is the tutorial Get started with ASP.NET Core SignalR
- whilst it doesn't cover SignalR Service specifically, it does show you how to write a chat client using "Hosted SignalR" and introduces most of the concepts you need to know.

The web client project

In this demo, we've gone out of our way to make the Web Client as simple as possible.

The Web App consists purely of static web content. There is no MVC, Razor, Controllers nor any other server-side logic. Instead, we have a single index.html and a small amount of accompanying static content (such as JavaScript and CSS).

The purpose of doing this is twofold:-

We don't want to distract you with any implementation details that are specific to a UI framework (whether that be ASP.NET MVC or one of the many JavaScript frameworks/libraries such as Angular or React). We want to focus upon the essentials, meaning that we have a very basic UI and minimal code (which includes any code needed to interact with SignalR).
We specifically wanted to have purely static web content (i.e. just .html, .css and .js files) so that, later in the article when we come to publish the Web App to the cloud, we can show you how to use Azure Storage Static Websites. One considerable benefit to this approach is that the hosting cost is a fraction of what it could otherwise be.

For development and testing purposes, we will still need a development web server, so we have opted to use an "ASP.NET Core Web Application" project as a starting point. This is still essentially the same as you would find for a conventional MVC or RazorPages project, except it has been pared back to the absolute minimum.

For example, there is no longer a Pages folder (for .cshtml views, in general) and none of the usual MVC constructs (such as _Layout.cshtml).
Static content has no need for configuration, so appsettings.json has been discarded.
The template includes the JQuery library, but that is not being used so has been removed from the wwwroot/lib folder.
We have retained the site.css stylesheet and the Bootstrap library.
We needed to include the SignalR Javascript Client library. You can find that in wwwroot/lib/signalr

Moving on to the small amount of C# code in this project:-

Program.cs remains untouched
Startup.cs has significant changes:-
- Pretty much the entire content that was provided by the new-project Template has been discarded.
- We need to explicitly tell ASP.NET core to use the index.html and we need to explicitly tell it to serve up static content. The revised code looks like this:-

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;

namespace WhatsAppSignalRDemo.Web
{
    public class Startup
    {
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            DefaultFilesOptions options = new DefaultFilesOptions();
                options.DefaultFileNames.Add("index.html");
            app.UseDefaultFiles(options);

            app.UseStaticFiles();
        }
    }
}

Javascript code on the client

The script that runs in the browser can be located here:

….\WhatsAppSignalRDemo\src\WhatsAppSignalRDemo.Web\wwwroot\js\chat.js

We briefly looked at this piece of code earlier in the article, when we checked that the API endpoint serviceEndpoint was correctly defined.

This particular piece of code started off life as being a copy of the sample code presented in the aforementioned Microsoft chat-application Tutorial Get started with ASP.NET Core SignalR
, so any similarities are due to this. That original sample was intended to work with Hosted SignalR, so along with other customisations, we've adapted the code to work with our SignalR Service.

As an overview, the code uses the Microsoft SignalR JavaScript library to create a “connection” object (named signalRconnection in this demo). The MS library does all the heavy-lifting work for us.

The code found in ....\WhatsAppSignalRDemo\src\WhatsAppSignalRDemo.Web\wwwroot\js\chat.js does the following:-

Defines a handful of configuration values, identifying the API endpoint of the service and a specific API name to be used for broadcasting messages.
Calls the signalR.HubConnectionBuilder() function to establish a connection to either a SignalR Hub or SignalR Service (we use the same JavaScript client, regardless of how the backend is implemented).
- The "HubConnectionBuilder" code is hardcoded to look for an API which is called negotiate by convention. We need to provide this in our Azure Function backend. This part is quite an important point to be aware of. You can read about it on Microsoft: Azure Functions development and configuration with Azure SignalR Service .

var signalRconnection = new signalR.HubConnectionBuilder()
    .withUrl(serviceEndpoint)
    .build();

We have an event listener, which reacts to messages being broadcast from the SignalR Service. When they arrive, the message object is separated into component parts (a username and user message) and simply appended to a UI list:-

signalRconnection.on(signalRTargetGroupName, function (broadcastMessage) {
    console.log(broadcastMessage);

    var encodedMsg = "<b>" + broadcastMessage.User + "</b> : &quot;" + broadcastMessage.Message + "&quot;";

    var li = document.createElement("li");
    li.innerHTML   = encodedMsg;
    document.getElementById("messagesList").appendChild(li);
});

We have a startup handler, that is responsible for updating the UI when the client established a connection to the SignalR Service (it enables the "send" button and removes the "please wait" message):-

signalRconnection.start().then(function () {
    document.getElementById("sendButton").disabled = false;
    document.getElementById("connectingMessage").style.display = "none";
}).catch(function (err) {
    return console.error(err.toString());
});

With SignalR Service, instead of "invoking" Hub methods, we send HTTP messages to a restful API endpoint.

The way we interact with SignalR Service is different from traditional Hosted SignalR.

Previously, with Hosted SignalR we would have a server-side "Hub" that contained [C# proxy] methods. In our client-side [JavaScript] code, we would "invoke" these methods using the SignalR connection object itself.

Such a piece of code would have looked like this (where "SendMessage" would be a corresponding C# method of the Hub class):-

signalRconnection.invoke("SendMessage", user, message).catch(function (err) {
    return console.error(err.toString());
});

In contrast, when using the "serverless mode" of SignalR Service, we still have the concept of Hubs (e.g. will still need to identify a "HubName" to group connections together) - but those Hubs are generic and no longer contain our [C# proxy] code. This means that there is no longer anything to "invoke".

Instead, we need our [web] client to POST separate HTTP messages to an API that we provide ourselves. In our serverless architecture, this would be another HTTP-triggered Azure Function.

Any APIs we create that provide SignalR functionality will have a connection string tying that Azure Function to our SignalR Service. We'll talk about the C# API code itself, later in the series.

This change is worth underlining because, at the time of writing, I felt that this was slightly ambiguous in the MS documentation. When researching this article, I wasn't confident that I should have been abandoning the use of the invoke function of the signalRConnection object - having to make separate REST calls felt like I awkwardly working around their solution.

To be sure that I have presented the correct solution in this article, I asked Microsoft Cloud Advocates directly. Thank you Brady Gaster and Anthony Chu for clarifying that I was indeed, doing it right!!

Something interesting that they pointed out, was that they are currently looking for a way to harmonise the experience, so there is a good chance that this current approach may change again in the near future.

Returning to the code in this demo, the need to make separate HTTP call(s) represents the most significant shift away from the Microsoft sample code that this file was originally based upon.

The following encapsulates a vanilla JavaScript fetch request into the function postMessage. In the future, if our code expands to require other HTTP calls, we could then easily reuse this function.

document.getElementById("sendButton").addEventListener("click", function (event) {

    var userMessage = new Object();
        userMessage.User = document.getElementById("userInput").value;
        userMessage.Message = document.getElementById("messageInput").value;

    postMessage(serviceEndpoint + signalRBroadcastApiMethod, userMessage);

    event.preventDefault();
});


function postMessage(url = ``, data = {}) {
    // Default options are marked with *
    return fetch(url, {
        method: "POST", // *GET, POST, PUT, DELETE, etc.
        mode: "cors", // no-cors, cors, *same-origin
        cache: "no-cache", // *default, no-cache, reload, force-cache, only-if-cached
        credentials: "same-origin", // include, *same-origin, omit
        headers: {
            "Content-Type": "application/json",
            // "Content-Type": "application/x-www-form-urlencoded",
        },
        redirect: "follow", // manual, *follow, error
        referrer: "no-referrer", // no-referrer, *client
        body: JSON.stringify(data), // body data type must match "Content-Type" header
    })
        .then(response => response.json()); // parses JSON response into native Javascript objects 
}

The Azure Function project

Broadly speaking this project is comprised of just three main elements:-

Models - there are only two models in the project, a container for some configuration items GenericConfig.cs and a very simple container for user messages UserMessage.cs
Common Code - this represents a handful of classes that are shared across all functions.
Functions - there are four HTTP-triggered Azure Functions .

If you have worked with Azure Functions in the past, you may be expecting to declare each function as a static. A very recent change to the SDK means that this is no longer a requirement and you can create function as an instance class. This is all due to scoping changes being made in order to accommodate the upcoming introduction of Dependency Injection.

Project Dependencies

There are only a handful of dependencies to other libraries. It would be simplest to add these dependencies using the NuGet Package Manager, but here is the library listing as seen in the ....\src\WhatsAppSignalRDemo.Function\WhatsAppSignalRDemo.Function.csproj file:-

  <ItemGroup>
    <PackageReference Include="Microsoft.Azure.WebJobs.Extensions.SignalRService" Version="1.0.0" />
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="1.0.24" />
    <PackageReference Include="twilio" Version="5.28.2" />
  </ItemGroup>

GlobalConstants.cs

One of the things that struck me when looking at much of the sample code available for both Azure Functions and SignalR, is that there seems to be a heavy reliance on string literals for identifying things in the code.

For example, functions typically have a [FunctionName="xyz"] attribute to define their exposed API name.

Similarly, if we wanted to pass messages between functions (over HTTP), we find ourselves identifying the function we want by the URL - again, another form of string.

I feel that these various examples make for brittle code - it would only take a typo for things to break.

Additionally, by using string-literals, we lose things such as compile-time checks and intellisense [to hint at mistakes]. If there is a problem, it will only manifest at runtime.

Therefore I have implemented a simple solution to address this issue. We create the static class GlobalConstants and within this, define a small selection of string constants. The globalConstants.cs class looks like this:-

namespace WhatsAppSignalRDemo.Function.Common
{
    public static class GlobalConstants
    {
        public const string SignalR_HubName = "Chat";
        public const string SignalR_TargetGroup = "AllUsers";

        public const string FunctionName_Negotiate = "negotiate";
        public const string FunctionName_BroadcastSignalRMessage = "BroadcastSignalRMessage";
        public const string FunctionName_SendWhatsAppMessage = "SendWhatsAppMessage";
        public const string FunctionName_ReceiveWhatsAppMessage = "ReceiveWhatsAppMessage";

        public const string Config_TwilioAccountSid = "TwilioAccountSid";
        public const string Config_TwilioAuthToken = "TwilioAuthToken";
        public const string Config_TwilioWhatsAppPhoneNumber = "TwilioWhatsAppPhoneNumber";
    }
}

Creating and using this class means that we can define string values in just one single place and then we can use those strongly-typed values across the rest of the project.

Aside from greatly reducing the possibility of making a silly mistake caused by a typo, it means that if you want to do something such as rename a keyname in your configuration, you don't have to then make this change all over your codebase.

To use these values, we can substitute them anywhere where a string literal would otherwise be used. So where previously we would have code that looks like this:-

public class SendWhatsAppMessageFunction
{
    [FunctionName("SendWhatsAppMessage")]
    public async Task<IActionResult> Run(
    ...

We can instead replace it with the following:-

public class SendWhatsAppMessageFunction
{
    [FunctionName(GlobalConstants.FunctionName_SendWhatsAppMessage)]
    public async Task<IActionResult> Run(
    ...

HttpHelper.cs

This class is a component that helps our functions make HTTP requests. It is a common, reusable component that can be shared by several separate Azure Functions.

Making RESTful calls is one mechanism for communicating between different functions (there are other, more reliable, ways such as using a queuing mechanism, but that is beyond the scope of this article). For example, in this demo, when a message is received from WhatsApp to the ReceiveWhatsAppMessageFunction, the message is relayed onward to the BroadcastSignalRMessageFunction by way of an HTTP call.

using System.IO;
using System.Net;

using Newtonsoft.Json;

namespace WhatsAppSignalRDemo.Function.Common
{
    public static class HttpHelper
    {
        public static void PostMessage (string apiUrl, object message)
        {
            //send request
            var httpWebRequest = (HttpWebRequest)WebRequest.Create(apiUrl);
            httpWebRequest.ContentType = "application/json";
            httpWebRequest.Method = "POST";
            using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
            {
                streamWriter.Write(JsonConvert.SerializeObject(message));
                streamWriter.Flush();
                streamWriter.Close();
            }

            //get response
            var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
            using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
            {
                var result = streamReader.ReadToEnd();
            }
        }
    }
}

StartupHelper.cs

Azure Functions are self-contained units that are instanced as demand requires. This is why they can scale without issue.

In contrast, ASP.NET APIs exist on a common platform - a constantly provisioned App Server.

One benefit of using an ASP.NET Web Application is that you only need a single application startup (with that code literally being in the Startup.cs file). This means that any setup and configuration needs happen only once and the results can then be made available until the application is recycled.

In contrast, an Azure Function requires you to run configuration on each and every use. If you look at many of the code examples for Azure Functions, you tend to see often those examples repeating boilerplate code for things like configuration.

Looking at an Azure Function in isolation, this probably doesn't appear to be much of an issue. However, as soon as you have a suite of different functions, you'll start to see a pattern of repetition, which isn't ideal.

As developers we aspire to produce, what we hope to be well-considered code, therefore, we should try and follow software design principles where possible. Amongst these recommendations is the DRY Principle - which basically says "don't repeat the same code everywhere - try and reuse it".

So, the code in ....\src\WhatsAppSignalRDemo.Function\Common\StartupHelper.cs is an effort to try and encapsulate some of that code which is common between each of the four Functions.

using System;

using Microsoft.Azure.WebJobs;

using WhatsAppSignalRDemo.Function.Models;

namespace WhatsAppSignalRDemo.Function.Common
{
    public static class StartupHelper
    {
        public static GenericConfig GetConfig(ExecutionContext executionContext)
        {
            string functionHostName = Environment.GetEnvironmentVariable("WEBSITE_HOSTNAME");

            return new GenericConfig
            {
                TwilioAccountSid = Environment.GetEnvironmentVariable(GlobalConstants.Config_TwilioAccountSid), 
                TwilioAuthToken = Environment.GetEnvironmentVariable(GlobalConstants.Config_TwilioAuthToken), 
                TwilioWhatsAppPhoneNumber = Environment.GetEnvironmentVariable(GlobalConstants.Config_TwilioWhatsAppPhoneNumber),
                ApiEndpoint = $"http://{functionHostName}/api/"
            };
        }
    }
}

Within the Function class (such as ReceiveWhatsAppMessageFunction), the StartupHelper is made available a little bit like an ASP.NET Core Configuration Item. It would look like this (partial code, for brevity):-

... 

private GenericConfig _genericConfig;

... 

_genericConfig = StartupHelper.GetConfig(executionContext);

... 

HttpHelper.PostMessage(
        _genericConfig.ApiEndpoint + GlobalConstants.FunctionName_BroadcastSignalRMessage, 
        userMessage);

...

The intent of the StartupHelper class is to demonstrate a way to encapsulate all of the requests for configuration information, into one place (which can then be re-used by multiple different functions). The mindset behind this idea is to emulate the effect of having all of your configuration code in a startup class.

The practical use of the above class is to define and populate the field ApiEndpoint, which is genuinely re-used in three of the four functions.

The inclusion of the three Twilio configuration items into StartupHelper, is a little bit more tenuous to justify. Those particular fields are only actually used in SendWhatsAppMessageFunction, so you could argue that those configuration items may have been better placed directly into just SendWhatsAppMessageFunction, using Environment.GetEnvironmentVariables as appropriate.

The point of this article is to talk about and demonstrate some ideas, so take all of this into consideration and choose a solution that suits your purposes best.

NegotiateFunction.cs

This function is fundamental to the operation of the SignalR Service, so you need to know that it's both required and how works.

Previously, with Hosted SignalR, the [web] client would negotiate directly with the Hub. This would all be managed transparently by the SignalR JavaScript client code - we only needed to provide the hostname of the service.

With SignalR Service, the concept of a Hub still exists, but it is all dynamically provisioned and managed by Azure. The upshot is that our [web] client can't make the first connection directly. To make this work, we need to provide a static HTTP API, which will negotiate with the SignalR Service, and return connection details and a user-access token.

The good news is that the SignalR JavaScript client software, provided by Microsoft, understands the differences between working with Hosted and Service modes, so will explicitly be expecting you to provide an API called "negotiate". You can read about that in their own documentation here.

When it comes to writing the C# for the "negotiate" API, fortunately, the code itself is really straightforward and we didn't even need to write it ourselves, as it comes directly cut+paste from Microsoft's documentation.

In our demo, we've tweaked it slightly, so as to provide consistency and make use of our GlobalConstants:-

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Extensions.SignalRService;
using Microsoft.AspNetCore.Http;

using WhatsAppSignalRDemo.Function.Common;

namespace WhatsAppSignalRDemo.Function
{
    public class NegotiateFunction
    {
        [FunctionName(GlobalConstants.FunctionName_Negotiate)]
        public SignalRConnectionInfo Negotiate(
            [HttpTrigger(AuthorizationLevel.Anonymous)]HttpRequest req,
            [SignalRConnectionInfo(HubName = GlobalConstants.SignalR_HubName)]SignalRConnectionInfo connectionInfo)
        {
            return connectionInfo;
        }
    }
}

One part of the code to draw your attention to is the need to be consistent with your use of the SignalR HubName. This needs to be shared across any of the references that you make - so in the case of this demo, be conscious that this HubName is also used in the BroadcastSignalRMessageFunction (which is another good reason to use string constants, rather than literals)

BroadcastSignalRMessageFunction.cs

The BroadcastSignalRMessageFunction class is an HTTP-triggered Azure Function, which receives a message from the web client and relays it onto both:-

The SignalR Service, which In turn, broadcasts the message to every connected client.
The SendWhatsAppMessageFunction API, which in turn, broadcasts the message to every subscribed WhatsApp user.

Earlier in this article, we've explained that although SignalR Service has Hubs, they no longer accommodate having methods written against them.

The BroadcastSignalRMessageFunction is the stand-alone HTTP API, that effectively replaces code that would previously have been a method within the Hub class.

The SignalR Service extension is added as an argument to our Function and the object is named signalRMessages. This handles all the operational details, such as locating a connection string, automatically for us.

We send messages into the Service by calling signalRMessages.AddAsync(...) like this:-

using System.Threading.Tasks;

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Extensions.SignalRService;

using WhatsAppSignalRDemo.Function.Common;
using WhatsAppSignalRDemo.Function.Models;

namespace WhatsAppSignalRDemo.Function
{
    public class BroadcastSignalRMessageFunction
    {
        private GenericConfig _genericConfig;

        [FunctionName(GlobalConstants.FunctionName_BroadcastSignalRMessage)]
        public Task SendMessage(
            [HttpTrigger(AuthorizationLevel.Anonymous, "post")]object message,
            [SignalR(HubName = GlobalConstants.SignalR_HubName)]IAsyncCollector<SignalRMessage> signalRMessages,
            ExecutionContext executionContext)
        {
            _genericConfig = StartupHelper.GetConfig(executionContext);

            // relay the message to the WhatsApp API
            HttpHelper.PostMessage(_genericConfig.ApiEndpoint + GlobalConstants.FunctionName_SendWhatsAppMessage, message);

            //relay the message to the SignalR Service
            return signalRMessages.AddAsync(
                new SignalRMessage
                {
                    Target = GlobalConstants.SignalR_TargetGroup,
                    Arguments = new[] { message }
                });
        }
    }
}

SendWhatsAppMessageFunction.cs

This Function is not intended to be called directly from the [web] client, but instead triggered by the BroadcastSignalRMessageFunction Function.

This particular Function is probably the most complex in terms of different tasks that it performs:-

The incoming JSON message is deserialised and ultimately end ups in the C# dynamic type (for simplicity) named requestObject.
The Twilio client is created and initialised using credentials originating in our configuration.
Using the Twilio library method MessageResource.ReadAsync(...) we obtain a list of all WhatsApp messages that have been added to our sandbox in this session. This will contain a list of every single message, including each phone number of the user involved. This collection is named messageCollection.
We use a LINQ query to filter the list of every phone number in messageCollection, down to a list of unique phone numbers. This resultant collection is named distinctPhoneNumbers.
We iterate over the list of unique phone numbers, using the Twilio library method MessageResource.Create(...) to send a message to each.
- We test that the phone number of the recipient is not the same as the phone number in the message (i.e. the sender) - we don't want to send a WhatsApp message straight back to the user who sent it!

using System.IO;
using System.Threading.Tasks;
using System.Linq;
using System.Collections.Generic;

using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;

using Newtonsoft.Json;
using Twilio;
using Twilio.Base;
using Twilio.Types;
using Twilio.Rest.Api.V2010.Account;

using WhatsAppSignalRDemo.Function.Models;
using WhatsAppSignalRDemo.Function.Common;


namespace WhatsAppSignalRDemo.Function
{
    public class SendWhatsAppMessageFunction
    {
        private GenericConfig _genericConfig;

        [FunctionName(GlobalConstants.FunctionName_SendWhatsAppMessage)]
        public async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = null)]HttpRequest httpRequest,
            ExecutionContext executionContext
            )
        {

            _genericConfig = StartupHelper.GetConfig(executionContext);

            string requestBody = await new StreamReader(httpRequest.Body).ReadToEndAsync();
            dynamic requestObject = JsonConvert.DeserializeObject(requestBody);

            // connect to Twilio
            TwilioClient.Init(_genericConfig.TwilioAccountSid, _genericConfig.TwilioAuthToken);

            // query twilio api ... and get distinct phone numbers of whatsapp users subscribed to chat
            ResourceSet<MessageResource> messageCollection = await MessageResource.ReadAsync(to: _genericConfig.TwilioWhatsAppPhoneNumber);
            IEnumerable<PhoneNumber> distinctPhoneNumbers = messageCollection.GroupBy(a => a.From.ToString()).Select(b => b.FirstOrDefault().From);

            foreach(var phoneNumber in distinctPhoneNumbers)
            {
                if (phoneNumber.ToString() == requestObject.User.ToString())
                {
                    // if the message originated from whatsapp, don't send a copy straight back to sender
                    continue;
                }

                // send message to whatsapp user
                var message = MessageResource.Create(
                    from: new Twilio.Types.PhoneNumber(_genericConfig.TwilioWhatsAppPhoneNumber),
                    body: $"{requestObject.User} : {requestObject.Message}",
                    to: phoneNumber
                );
            }

            return (ActionResult)new OkResult();
        }
    }
}

ReceiveWhatsAppMessageFunction.cs

This Function is the endpoint we identified in the Twilio Dashboard. Its purpose is to simply receive a message sent from Twilio and extract some of the fields that we receive.

That extracted information is then used to populate our Model Class UserMessage. The fields are simply a username (the WhatsApp phone number) and message.

The processed message is then sent onward, via an HTTP POST, to BroadcastSignalRMessage.

using System.IO;
using System.Web;
using System.Threading.Tasks;

using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;

using WhatsAppSignalRDemo.Function.Models;
using WhatsAppSignalRDemo.Function.Common;

namespace WhatsAppSignalRDemo.Function
{
    public class ReceiveWhatsAppMessageFunction
    {
        private GenericConfig _genericConfig;

        [FunctionName(GlobalConstants.FunctionName_ReceiveWhatsAppMessage)]
        public async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = null)]           
            HttpRequest httpRequest,
            ExecutionContext executionContext) 
        {
            _genericConfig = StartupHelper.GetConfig(executionContext);

            string requestBody = await new StreamReader(httpRequest.Body).ReadToEndAsync();

            UserMessage userMessage = new UserMessage
            {
                User = HttpUtility.ParseQueryString(requestBody).Get("From"),
                Message = HttpUtility.ParseQueryString(requestBody).Get("Body")
            };

            HttpHelper.PostMessage(
                _genericConfig.ApiEndpoint + GlobalConstants.FunctionName_BroadcastSignalRMessage, 
                userMessage);

            return new OkResult();
        }
    }
}

Summary

We've now had an in-depth look at the code and you should be in a good place with your understanding of what's needed in the system.

In the final article of this series, we'll look into the additional steps needed to get our development system published to the cloud.

See you there!

NEXT: Read part 3

Forem: Jim Mc̮̑̑̑͒G

How to save an audio file from Twilio Media streams to Azure storage.

Introduction

Requirements

What will we be doing?

Create a webhook (an HTTP "handshaking" endpoint)

Create a websocket service

Create a buffering system

Create an audio file

Create a storage handler

Primary resources/references

Heads-up : Working with websockets in .NET isn't quite as straightforward as you might expect.

Use NGrok whilst developing external-facing web services.

Create Azure Resources

Get a Twilio Phone number and configure the webhook

Create the project

Template a new solution

Set up configuration

Create webhook for Twilio to use

Recreate the WebsocketManager project

Scaffold the code of our project

Layer in the implementation code of our project

The buffer

Starting websocket connections

Receiving websocket messages

Adding the payload to a buffer

Perform tasks when the stream closes

Orchestrate the creation of an audio file and uploading to storage

Flatten the list of audio data chunks into a single bytearray

Implement audio file writer

Implement Azure Storage handler

Register the middleware and finish application configuration

Test the code

Wrapping up

Further reading

Disclosure

[Configuration in Azure Functions Series - Part 4] Azure App Configuration and Azure Key Vault

Overview

Azure App Configuration

Azure Key Vault

Let's setup an Azure Key Vault!

1) Create a new HTTP-Triggered Azure Function from the templates.

2) Add extension packages

3) Create a new Resource Group in Azure

4) Create a new Azure Functions AppService in Azure.

5) Set AppService to have a System-Assigned Identity

6) Create a new Azure Key Vault resource in Azure.

7) Grant permission to the new AppService identity.

8) Make a note of service address

9) Create a new secret setting

10) Add startup code

11) Update the http-triggered function code

12) Login locally to "Az Functions" CLI

13) Test our local development version.

14) Deploy code to AppService and test cloud version.

Azure Key Vault References

That's all

Disclosure

Thumbs Up

Further reading

[Configuration in Azure Functions Series - Part 3] Add ASP.NET Core configuration into an Azure Function project

Should you even attempt to use ASP.NET Core configuration, using IOptions<>, in an Azure Function?

Does this even work?

How could this approach using supplemental configuration sources be useful to me?

Do I have to use a separate AppSettings.json file?

Dependency Injection in Azure Functions

Let's do it!

1) Explicitly tell the compiler which version of .NET Core SDK to use

2) Set Framework Version and Add Nuget Packages in the project

3) Update local.settings.json with a setting

4) Create appSettings.json and populate

5) Create user secrets

6) Create a Model which will bind to configuration

7) Create a startup class

8) In your Azure Function class

9) Run the program

[Configuration in Azure Functions Series - Part 2] A deeper dive into Azure Functions configuration

Configuration, the Azure Functions v2 way

What does serverless really mean?

Why do I need to know this?

3) Update `local.settings.json` with a setting

4) Create `appSettings.json` and populate