DEV Community: Niels Swimburger.NET 🍔

How to generate TwiML using Strings in C#

Niels Swimburger.NET 🍔 — Tue, 21 Feb 2023 00:00:00 +0000

This blog post was written for Twilio and originally published at the Twilio blog.

Over the decades, C# has added different ways to create a string, each with their own benefit. In this tutorial, you'll learn how to generate TwiML using the different C# string features with an ASP.NET Core Minimal API and compare it to the object oriented way of generating TwiML.

But first, let's get you up to speed on how Twilio uses webhooks and TwiML to respond to text messages and voice calls.

Prerequisites

Here's what you will need to follow along:

.NET 6 SDK, or .NET 7 SDK to use Raw String Literals (later versions will work too)
A code editor or IDE. I recommend JetBrains Rider, Visual Studio 2022 Preview (will also work in the non-preview Visual Studio in the future), or VS Code with the C# plugin
A free Twilio account (sign up with Twilio for free and get trial credit)
A Twilio Phone Number
The ngrok CLI, and optionally, a free ngrok account

Experience with ASP.NET Core and Minimal APIs is not required but recommended. Here's an article that brings you up to speed on how to integrate ASP.NET Core Minimal APIs with Twilio.

You can find the source code for this tutorial on GitHub. Use it if you run into any issues, or submit an issue, if you run into problems.

Before creating your application, let's get you up to speed on how Twilio uses webhooks and TwiML to respond to text messages and voice calls.

Webhooks and TwiML

Using Twilio, you can build programmatic text message and voice call applications. Twilio can do a lot of things like playing audio, gathering input, and recording a call. But Twilio doesn't know how you want to respond to voice calls and text messages. That's why when Twilio receives a call or text message, Twilio will send an HTTP request to your application asking for instructions.

A webhook is a user-defined HTTP callback. When an event happens in a service, your application is notified of that event using an HTTP request.

Twilio uses webhooks heavily throughout all its products. Here's a diagram of what it looks like when there's an incoming text message to your Twilio Phone Number and your application is handling the messaging webhook:

When your Twilio Phone Number receives a text message, Twilio will send an HTTP request with the message details to your application. Your application then has to respond with TwiML ( Twi lio M arkup L anguage) to instruct Twilio how to respond. TwiML is XML with special tags defined by Twilio to provide instructions on how to respond to messages and voice calls. In the diagram depicted above, Twilio will respond with "Hi!" because the app responded with the following TwiML:

<?xml version="1.0" encoding="utf-8"?>
<Response>
<Message>Hi!</Message>
</Response>

You can learn more about TwiML for Programmable Messaging here and TwiML for Programmable Voice here.

Create an ASP.NET Core Minimal API to handle voice calls

First, let's create an ASP.NET Core Minimal API to handle voice calls without using Raw String Literals.

Open a terminal and create a new ASP.NET Core Minimal API project using the .NET CLI:

dotnet new web -o TwimlStrings 
cd TwimlStrings

These commands will create the project in a folder named TwimlStrings and navigate into the folder.

Open the project in your editor, and update the Program.cs file with the following C# code:

using System.Security;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/what-does-the-fox-say", () => Results.Text("" +
"<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
"<Response>" +
" <Gather action=\"/answer\" method=\"GET\" input=\"speech\"> " +
" <Say>What does the fox say?</Say>" +
" </Gather>" +
" <Say>Ring-ding-ding-ding-dingeringeding!</Say>" +
"</Response>",
 contentType: "application/xml"
));

app.MapGet("/answer", (string speechResult) => Results.Text("" +
"<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
"<Response>" +
" <Say>You said: " + SecurityElement.Escape(speechResult) + "</Say>" +
"</Response>",
 contentType: "application/xml"
));

app.Run();

When your Twilio Phone Number receives a call, Twilio will send an HTTP GET request to the /what-does-the-fox-say endpoint, which will set the content-type response header to application/xml, and return the following TwiML in the response:

<?xml version="1.0" encoding="utf-8"?><Response><Gather action="/answer" method="GET" input="speech"><Say>What does the fox say?</Say></Gather><Say>Ring-ding-ding-ding-dingeringeding!</Say></Response>

That's not very readable, so here's the formatted version:

<?xml version="1.0" encoding="utf-8"?>
<Response>
<Gather action="/answer" method="GET" input="speech">
<Say>What does the fox say?</Say>
</Gather>
<Say>Ring-ding-ding-ding-dingeringeding!</Say>
</Response>

When Twilio receives the TwiML, it'll ask the caller "What does the fox say?" and listen for a speech response. When the caller responds, Twilio will send an HTTP request, this time to the /answer endpoint, with the transcription of what the caller said. If the caller doesn't respond, Twilio will say "Ring-ding-ding-ding-dingeringeding!" to the caller.

The /answer endpoint will retrieve the transcription from the query string parameter SpeechResult by binding it to the speechResult parameter. The speechResult is used to construct some more TwiML, but it is first escaped using SecurityElement.Escape to ensure no XML is in the variable. The /answer endpoint will generate the following TwiML when the caller says "ring ding ding":

<?xml version="1.0" encoding="utf-8"?>
<Response>
<Say>You said: ring ding ding</Say>
</Response>

When Twilio receives this TwiML, Twilio will convert "You said: ring ding ding" to speech and stream the audio to the caller.

In case you're not familiar with the song I am referencing in this app, "What does the fox say?" originates from this famous song.

Start your .NET application using your editor or using the terminal using the .NET CLI:

dotnet run

Before integrating Twilio, open a browser and navigate to your web application URL with the suffix /what-does-the-fox-say, to verify the TwiML that is generated.

Make the application publicly accessible

For Twilio to be able to send HTTP requests to your local web server, the server needs to be publicly accessible. ngrok is a free and secure tunneling service that can make your local web server public.

To start ngrok, run the following ngrok command in a separate terminal:

ngrok http [YOUR_ASPNET_URL]

Replace [YOUR_ASPNET_URL] with the localhost URL from your .NET application. If you're using an HTTPS localhost URL, you'll need to authenticate ngrok. The ngrok command will display an HTTPS Forwarding URL that makes your local web server public.

Configure your Twilio Phone Number

Now it's time to update your Twilio Phone Number to send HTTP requests to your /what-does-the-fox-say endpoint via the ngrok Forwarding URL. The URL should look something like https://cd2f8809cbd0.ngrok.io/what-does-the-fox-say.

Go to the Active Phone Numbers section in the Twilio Console and click on your Twilio Phone Number.

This will take you to the configuration for the phone number. Find the Voice & Fax section and under the " A CALL COMES IN" label, set the dropdown to " Webhook". In the text field next to it, enter your ngrok forwarding URL with /what-does-the-fox-say appended to it. Select “ HTTP GET ” in the last dropdown. Finally, click the Save button at the bottom of the page.

Test that the application works

To test out your application, call your Twilio Phone Number. You should hear the question "What does the fox say?" which you can respond to, wait 5 seconds, and then your response will be read back to you.

After you've done that, stop your .NET application using your editor, or if you're using the terminal, press ctrl + c.

Use Verbatim Strings

The first way you can improve your code is by using Verbatim Strings. To turn your string into a Verbatim String, prefix your string with the "at" @ symbol.

@"The fox said: ""I like using verbatim strings,
because it supports multi-line text,
you don't need to escape forward slashes (/), and backslashes (\),
and you can easily escape double quotes by doubling the double quotes""."

As the Verbatim String above says, you don't need to escape forward slashes or backslashes, however you still need to escape double quotes. However, instead of using a backslash to escape the double quotes, you place two double quotes and the resulting character will be a single double quote.

Applying this knowledge to your TwiML Program.cs file, you will have the following endpoint code:

app.MapGet("/what-does-the-fox-say", () => Results.Text(
@"<?xml version=""1.0"" encoding=""utf-8""?>
 <Response>
 <Gather action=""/answer"" method=""GET"" input=""speech""> 
 <Say>What does the fox say?</Say>
 </Gather>
 <Say>Ring-ding-ding-ding-dingeringeding!</Say>
 </Response>",
 contentType: "application/xml"
));

app.MapGet("/answer", (string speechResult) => Results.Text(
@"<?xml version=""1.0"" encoding=""utf-8""?>
 <Response>
 <Say>You said: " + SecurityElement.Escape(speechResult) + @"</Say>
 </Response>",
 contentType: "application/xml"
));

The resulting TwiML will be formatted better, but still be indented oddly because the tabs used to nicely indent the code are also included in the string:

<?xml version="1.0" encoding="utf-8"?>
<Response>
<Gather action="/answer" method="GET" input="speech"> 
<Say>What does the fox say?</Say>
</Gather>
<Say>Ring-ding-ding-ding-dingeringeding!</Say>
</Response>

By using Verbatim Strings, you are able to use multi-line text so you don't have to concatenate the string for every line of TwiML. You may think that this will also improve performance as you aren't creating as many strings and then concatenating them. But the compiler will optimize your code so that there's no difference in the end result.

Use String Interpolation

By using Verbatim Strings, you were able to decrease the amount of opening and closing double quotes to construct your TwiML string which makes the code a lot easier to read. However, you still had to use string concatenation to embed the speechResult into your TwiML string for the /answer endpoint.

To embed variables in your string, you can use String.Format or, much better, String Interpolation. First, start your string with the dollar $ sign then use the curly brackets {} to embed C# expressions.

For example, the following code will write "What does the fox say?" to the console.

var animal = "fox";
Console.WriteLine($"What does the {animal} say?");

Applying this knowledge to the /answer endpoint, you can further improve the code like this:

app.MapGet("/answer", (string speechResult) => Results.Text(
$@"<?xml version=""1.0"" encoding=""utf-8""?>
 <Response>
 <Say>You said: {SecurityElement.Escape(speechResult)}</Say>
 </Response>",
 contentType: "application/xml"
));

C# 11 and .NET 7 only: Use Raw String Literals

C# 11 is still in preview, but you can try it out today using the .NET 7 previews. Make sure you have .NET 7 installed and are using .NET 7 in your project. Then, open your project file at TwimlStrings.csproj and add the <LangVersion>preview</LangVersion> to the first <PropertyGroup> node. This will enable the C# 11 preview features.

Your TwimlStrings.csproj in the project folder, should look something like this:

<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net7.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<LangVersion>preview</LangVersion>
</PropertyGroup>
</Project>

Now that you have enabled C# 11, let's talk about the new Raw String Literals. To use Raw String Literals, you start and end your string with at least 3 double quotes. For example:

"""
 I like using Raw String Literals,
 because it supports multi-line text,
 you don't need to escape forward slashes (/), backslashes (\), and double quotes\* ("),
 and you can indent your code better without having the indentation included in your string. 
"""

The syntax highlighting may be off in the next snippets and snippet above because the blog doesn't have C# 11 highlighting yet.

As with Verbatim Strings, you don't have to escape forward slashes and backslashes, but, as opposed to Verbatim Strings, in Raw String Literals you also don't have to escape your double quotes, more or less.

You can use double quotes as long as the number of subsequent double quotes is less than the amount of double quotes you started and ended your string with. This is clearer with an example:

// 3 start and end double quotes, so 1 and 2 subsequent double quotes is allowed
"""This " and this "" is allowed.""" 

// 3 start and end double quotes, so 3 subsequent double quotes is NOT allowed
"""This """ is not allowed."""

// 4 start and end double quotes, so 3 subsequent double quotes is NOT allowed
""""This """ is allowed.""""

Lines one and two are valid Raw String Literals because the number of subsequent double quotes is lower than the number of double quotes used to start and end the Raw String Literal.

Raw String Literals also makes it easier to format your strings. Take the following method that generates a Verbatim String as an example:

public string GenerateHtml()
{
return @"
 <p>
 This is a <b>multi-line Verbatim String</b> to generate some HTML
 </p>
";
}

The resulting string will be:


<p>
 This is a <b>multi-line Verbatim String</b> to generate some HTML
<p>

Notice the newlines and the tab indentation? I formatted the Verbatim String for the sake of readability, but as a result I also got the newlines and tabs in it which I do not want.

Let's take a look at the Raw String Literal version:

string GenerateString()
{
return """
 <p>
 This is a <b>multi-line Raw String Literal</b>
 </p>
""";
}

The resulting string now looks like this:

<p>
This is a <b>multi-line Raw String Literal</b>
</p>

The unnecessary newlines and tabs are gone. The way Raw String Literals indent your strings depends on where you place the starting and ending double quotes, and also how you indent the content of your string. It's a little funky and hard to explain all the variations, so I recommend experimenting with it and reading the Microsoft documentation on Raw String Literals to learn more.

Using this knowledge, you can apply Raw String Literals to your endpoints like this:

app.MapGet("/what-does-the-fox-say", () => Results.Text("""
 <?xml version="1.0" encoding="utf-8"?>
 <Response>
 <Gather action="/answer" method="GET" input="speech">
 <Say>
 What does the fox say?
 </Say>
 </Gather>
 <Say>Ring-ding-ding-ding-dingeringeding!</Say>
 </Response>
""",
 contentType: "application/xml"
));

app.MapGet("/answer", (string speechResult) => Results.Text($"""
 <?xml version="1.0" encoding="utf-8"?>
 <Response>
 <Say>You said: {SecurityElement.Escape(speechResult)}</Say>
 </Response>
""" ,
 contentType: "application/xml"
));

Now the resulting TwiML will be readable and not contain unnecessary newlines and tabs.

Other ways to generate TwiML

There are many other ways you could generate TwiML. Since TwiML is XML, you can use the APIs from the System.Xml and System.Xml.Linq namespace. Twilio also has a helper library for .NET that lets you generate TwiML in an object-oriented way, and the helper library for ASP.NET helps you return the TwiML in the HTTP response.

In the terminal where you ran your project, run the following commands to add the Twilio package and Twilio.AspNet.Core package:

dotnet add package Twilio
dotnet add package Twilio.AspNet.Core

Then, update the Program.cs file with the following code:

using Twilio.AspNet.Core.MinimalApi;
using Twilio.TwiML;
using Twilio.TwiML.Voice;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/what-does-the-fox-say", () =>
{
var response = new VoiceResponse();
var gather = new Gather(
 input: new List<Gather.InputEnum> {Gather.InputEnum.Speech},
 action: new Uri("/answer", UriKind.Relative),
 method: Twilio.Http.HttpMethod.Get
 );
 gather.Append(new Say("What does the fox say?"));
 response.Append(gather);
 response.Say("Ring-ding-ding-ding-dingeringeding!");
return Results.Extensions.TwiML(response);
});

app.MapGet("/answer", (string speechResult) =>
{
var response = new VoiceResponse()
 .Say($"You said: {speechResult}");
return Results.Extensions.TwiML(response);
});

app.Run();

The resulting TwiML will be the same as before. Notice, however, that you don't need to use the SecurityElement.Escape anymore to escape the user input, because the Twilio helper library will XML encode it for you. Under the hood, the helper library uses the APIs from System.Linq.Xml to generate the XML string which will also do the formatting for you.

Now, you may be wondering, why would you use strings when you can use the Twilio helper library, or maybe you're wondering why you would use the helper library when you can use strings.

The advantages of creating TwiML using strings, is that you don't need any dependencies and it's more memory efficient & performant. However, it is easier to make a mistake in your TwiML and there will be no compilation errors to prevent you from doing that. You also have to XML escape user input yourself to protect yourself from XML injection.

The advantages of using the Twilio helper library are that you are using fully typed objects and methods that provide IntelliSense in IDEs. If you make a typo, your project will not build and you will receive a compiler error telling you where your typo is. However, you do depend on the Twilio helper library and its dependencies, and you have to create a bunch of objects that are ultimately serialized to an XML string which is less memory efficient and slower.

They both have their own advantages and disadvantages, but you can mix and match based on your use case.

Next steps

You learned how Twilio uses webhooks and TwiML to give you control over how to respond to a call or text message. You then learned how to generate TwiML using different string features in C#, such as Verbatim Strings, String Interpolation, and C# 11's new Raw String Literal feature. You then looked at the difference between generating TwiML using strings and generating TwiML using the Twilio helper library.

Here are a couple more resources to further your learning on Minimal APIs and Twilio:

We can't wait to see what you build. Let us know!

Use Raw String Literals to generate TwiML in C# 11

Niels Swimburger.NET 🍔 — Wed, 15 Feb 2023 00:00:00 +0000

This blog post was written for Twilio and originally published at the Twilio blog.

Over the decades, C# added different ways to create a string, each with their own benefit, and C# 11 is adding another way: Raw String Literals. There are many use cases for Raw String Literals, and one of those use cases is to generate TwiML, but more on that later. In this tutorial, you'll learn how to generate TwiML with Raw String Literals with an ASP.NET Core Minimal API.

Prerequisites

Here's what you will need to follow along:

.NET 7 SDK (later versions will work too)
A code editor or IDE (I recommend JetBrains Rider, Visual Studio 2022 Preview (C# 11 is only supported in preview now, but will work in non-preview in the future.), or VS Code with the C# plugin)
A free Twilio account (sign up with Twilio for free and get trial credit)
A Twilio Phone Number
The ngrok CLI, and optionally, a free ngrok account

Experience with ASP.NET Core and Minimal APIs is not required but recommended. Here's an article that brings you up to speed on how to integrate ASP.NET Core Minimal APIs with Twilio.

You can find the source code for this tutorial on GitHub. Use it if you run into any issues, or submit an issue, if you run into problems.

Before creating your application, let's get you up to speed on how Twilio uses webhooks and TwiML to respond to text messages and voice calls.

Webhooks and TwiML

Using Twilio, you can build programmatic text message and voice call applications. Twilio can do a lot of things like playing audio, gathering input, and recording a call, but Twilio doesn't know what you want to do in response to voice calls and text messages. That's why when Twilio receives a call or text message, Twilio will send an HTTP request to your application asking for instructions.

A webhook is a user-defined HTTP callback. When an event happens in a service, your application is notified of that event using an HTTP request.

<?xml version="1.0" encoding="utf-8"?>
<Response>
<Message>Hi!</Message>
</Response>

You can learn more about TwiML for Programmable Messaging here and TwiML for Programmable Voice here.

Now that you know what webhooks and TwiML are, let's create a voice call application with ASP.NET Core.

Create an ASP.NET Core Minimal API to handle voice calls

First, let's create an ASP.NET Core Minimal API to handle voice calls without using Raw String Literals.

Open a terminal and create a new ASP.NET Core Minimal API project using the .NET CLI:

dotnet new web -o TwimlRawStringLiterals 
cd TwimlRawStringLiterals

These commands will create the project in a folder named TwimlRawStringLiterals and navigate into the folder.

Open the project in your editor, and update the Program.cs file with the following C# code:

using System.Security;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/what-does-the-fox-say", () => Results.Text(
@"<?xml version=""1.0"" encoding=""utf-8""?>
 <Response>
 <Gather action=""/answer"" method=""GET"" input=""speech""> 
 <Say>What does the fox say?</Say>
 </Gather>
 <Say>Ring-ding-ding-ding-dingeringeding!</Say>
 </Response>",
 contentType: "application/xml"
));

app.MapGet("/answer", (string speechResult) => Results.Text(
$@"<?xml version=""1.0"" encoding=""utf-8""?>
 <Response>
 <Say>You said: {SecurityElement.Escape(speechResult)}</Say>
 </Response>",
 contentType: "application/xml"
));

app.Run();

<?xml version="1.0" encoding="utf-8"?>
<Response>
<Gather action="/answer" method="GET" input="speech"> 
<Say>What does the fox say?</Say>
</Gather>
<Say>Ring-ding-ding-ding-dingeringeding!</Say>
</Response>

Take note of how the <Response> node and everything in it is indented with a tab too much.

<?xml version="1.0" encoding="utf-8"?>
<Response>
<Say>You said: ring ding ding</Say>
</Response>

When Twilio receives this TwiML, Twilio will convert "You said: ring ding ding" to speech and stream the audio to the caller.

In case you're not familiar with the song I am referencing in this app, "What does the fox say?" originates from this famous song.

Start your .NET application using your editor or using the terminal using the .NET CLI:

dotnet run

Before integrating Twilio, open a browser and navigate to your web application URL with the suffix /what-does-the-fox-say to verify the TwiML that is generated.

Make the application publicly accessible

For Twilio to be able to send HTTP requests to your local web server, the server needs to become publicly accessible. ngrok is a free secure tunneling service that can make your local web servers public.

To start ngrok, run the following ngrok command in a separate terminal:

ngrok http [YOUR_ASPNET_URL]

Configure your Twilio Phone Number

Now it's time to update your Twilio Phone Number to send HTTP requests to your /what-does-the-fox-say endpoint via the ngrok Forwarding URL. The URL should look something like _ https://cd2f8809cbd0.ngrok.io/what-does-the-fox-say _.

Test that the application works

After you've done that, stop your application using your editor, or if you're using the terminal, press ctrl + c.

C# 11 and .NET 7 only: Use Raw String Literals

C# 11 is still in preview, but you can try it out today using the .NET 7 previews. Make sure you have .NET 7 installed and are using .NET 7 in your project. Then, open your project file at TwimlRawStringLiterals.csproj and add the <LangVersion>preview</LangVersion> to the first <PropertyGroup> node. This will enable the C# 11 preview features.

The TwimlRawStringLiterals.csproj file should look something like this:

<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net7.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<LangVersion>preview</LangVersion>
</PropertyGroup>
</Project>

Now that you have enabled C# 11, let's talk about the new Raw String Literals. To use Raw String Literals, you start and end your string with at least 3 double quotes. For example:

"""
 I like using Raw String Literals,
 because it supports multi-line text,
 you don't need to escape forward slashes (/), backslashes (\), and double quotes\* ("),
 and you can indent your code better without having the indentation included in your string. 
"""

The syntax highlighting may be off in the next snippets and snippet above because the blog doesn't have C# 11 highlighting yet.

You don't have to escape forward slashes, backslashes, and you also don't have to escape your double quotes, more or less. You can use double quotes as long as the number of subsequent double quotes is less than the amount of double quotes you started and ended your string with. This is clearer with an example:

// 3 start and end double quotes, so 1 and 2 subsequent double quotes is allowed
"""This " and this "" is allowed.""" 

// 3 start and end double quotes, so 3 subsequent double quotes is NOT allowed
"""This """ is not allowed."""

// 4 start and end double quotes, so 3 subsequent double quotes is NOT allowed
""""This """ is allowed.""""

Line one and two are valid Raw String Literals because the number of subsequent double quotes is lower than the number of double quotes used to start and end the Raw String Literal.

Raw String Literals also makes it easier to format your strings. Take the following method that generates a Verbatim String (@) as an example:

public string GenerateHtml()
{
return @"
 <p>
 This is a <b>multi-line Verbatim String</b> to generate some HTML
 </p>
";
}

The resulting string will be:


<p>
 This is a <b>multi-line Verbatim String</b> to generate some HTML
<p>

Notice the newlines and the tab indentation? I formatted the Verbatim String for the sake of readability, but as a result I also got the newlines and tabs in it which I do not want.

Let's take a look at the Raw String Literal version:

string GenerateString()
{
return """
 <p>
 This is a <b>multi-line Raw String Literal</b>
 </p>
""";
}

The resulting string now looks like this:

<p>
This is a <b>multi-line Raw String Literal</b>
</p>

Using this knowledge, you can apply Raw String Literals to your endpoints like this:

app.MapGet("/what-does-the-fox-say", () => Results.Text("""
 <?xml version="1.0" encoding="utf-8"?>
 <Response>
 <Gather action="/answer" method="GET" input="speech">
 <Say>
 What does the fox say?
 </Say>
 </Gather>
 <Say>Ring-ding-ding-ding-dingeringeding!</Say>
 </Response>
""",
 contentType: "application/xml"
));

app.MapGet("/answer", (string speechResult) => Results.Text($"""
 <?xml version="1.0" encoding="utf-8"?>
 <Response>
 <Say>You said: {SecurityElement.Escape(speechResult)}</Say>
 </Response>
""" ,
 contentType: "application/xml"
));

Now the resulting TwiML will be readable and not contain unnecessary newlines and tabs.

Other ways to generate TwiML

In the terminal where you ran your project, run the following commands to add the Twilio package and Twilio.AspNet.Core package:

dotnet add package Twilio
dotnet add package Twilio.AspNet.Core

Then, update the Program.cs file with the following code:

using Twilio.AspNet.Core.MinimalApi;
using Twilio.TwiML;
using Twilio.TwiML.Voice;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/what-does-the-fox-say", () =>
{
var response = new VoiceResponse();
var gather = new Gather(
 input: new List<Gather.InputEnum> {Gather.InputEnum.Speech},
 action: new Uri("/answer", UriKind.Relative),
 method: Twilio.Http.HttpMethod.Get
 );
 gather.Append(new Say("What does the fox say?"));
 response.Append(gather);
 response.Say("Ring-ding-ding-ding-dingeringeding!");
return Results.Extensions.TwiML(response);
});

app.MapGet("/answer", (string speechResult) =>
{
var response = new VoiceResponse()
 .Say($"You said: {speechResult}");
return Results.Extensions.TwiML(response);
});

app.Run();

The resulting TwiML will be the same as before. Notice, however, that you don't need to use the SecurityElement.Escape anymore to escape the user input, because the Twilio helper library will XML encode it for you.

Under the hood, the helper library uses the APIs from System.Linq.Xml to generate the XML string which will also do the formatting for you.

Now, you may be wondering, why would you use strings when you can use the Twilio helper library, or maybe you're wondering why you would use the helper library when you can use strings.

They both have their own advantages and disadvantages, but you can mix and match based on your use case.

Next steps

You learned how Twilio uses webhooks and TwiML to give you control over how to respond to a call or text message. You then learned how to generate TwiML instructions using C# 11's new Raw String Literal feature, and compared it to generating TwiML with the Twilio helper library.

Here are a couple more resources to further your learning on Minimal APIs and Twilio:

We can't wait to see what you build. Let us know!

Use Visual Studio dev tunnels to handle Twilio Webhooks

Niels Swimburger.NET 🍔 — Wed, 08 Feb 2023 00:00:00 +0000

This blog post was written for Twilio and originally published at the Twilio blog.

Visual Studio recently introduced a new feature called dev tunnels. By using dev tunnels, Visual Studio will create a new public URL (tunnel URL) for you, and HTTP requests sent to the tunnel URL will be forwarded to your ASP.NET Core project running on localhost.

Dev tunnels has a lot of use cases. You could use this to easily test your web application on other devices like mobiles phone and tablets. You could also use this to make your application temporarily, publicly available for doing interactive demos and inviting your audience to participate.

How to use dev tunnels with Twilio

The most exciting use case for Twilio is that you can use dev tunnels to test webhooks. What are webhooks again?

" Webhooks are user-defined HTTP callbacks. They are triggered by some event in a web application and can facilitate integrating different applications or third-party APIs, like Twilio."

At Twilio, we heavily use webhooks throughout all of our products. You can use webhooks to respond to text messages or to manage voice calls. Here's a diagram of what it looks like when there's an incoming text message to your Twilio Phone Number and your application is handling the messaging webhook:

When your Twilio Phone Number receives a text message, Twilio will send an HTTP request with the message details to your application. Your application then has to respond with TwiML (Twilio Markup Language) to instruct Twilio how to respond. TwiML is XML with special tags defined by Twilio to provide instructions on how to respond to messages and voice calls. In the diagram depicted above, Twilio will respond with "Hi!" because the app responded with TwiML that looks like this:

<?xml version="1.0" encoding="utf-8"?>
<Response>
<Message>Hi!</Message>
</Response>

You can learn more about TwiML for Programmable Messaging here.

Some other types of webhooks will inform you of an event and not expect instructions as a response. However, webhook requests can only be made to publicly available URLs , and when you're developing and testing applications, you are usually doing so locally. But with Visual Studio dev tunnels, you can quickly make your web application public, so you can develop your webhooks!

So when a text message comes in, instead of Twilio sending an HTTP request directly to your application, Twilio can send it to your Visual Studio tunnel which will forward it to your application running on localhost.

In this tutorial, you'll learn how to use Visual Studio to create an ASP.NET Core project that will handle the Twilio SMS webhook, use dev tunnels to make the locally running application public, and then configure a Twilio Phone Number to send webhook requests to the public tunnel URL whenever a text message comes in so you can respond to it.

Prerequisites

You'll need the following things in this tutorial:

A Windows machine (there is no information about support for Visual Studio for Mac yet.)
Visual Studio 2022 Preview, with the ASP.NET and web development workload installed
In Visual Studio, you need to enable the dev tunnels preview feature

You can find details on how to do these steps in the dev tunnels announcement post by Microsoft.

Lastly, you'll also need a Twilio account (trial or upgraded). Try Twilio for free with promotional trial credit.

You can find the source code for this tutorial on GitHub. Use it as a reference if you run into any issues, or submit an issue if you need assistance

Create an empty ASP.NET Core web application with dev tunnels

Open Visual Studio 2022 preview and click " Create a new project", then search for the " ASP.NET Core Empty" project template and click Next.

On the next screen, give your project a meaningful name and click Next. Then on the last screen, leave everything as is and click Create.

Visual Studio will now generate an empty ASP.NET Core application that returns "Hello World!" using Minimal APIs. Go ahead and run your project to see it in action by pressing the green play arrow with your project name.

Visual Studio will run your application, open your browser, and then browse to the web application URL, which will look similar to https://localhost:5000. However, port number 5000 will be a random port number instead. The "Hello World!" application works as expected, but is only reachable on your machine. No other devices can reach it.

Back in Visual Studio, click on the debug dropdown menu, and then select the Dev Tunnels menu item. Now, the Dev Tunnels fly out menu shows you different options, to either select a dev tunnel (but there are none yet), to create a new tunnel, or to open the dev tunnels window.

Click on Create A Tunnel... which opens a dialog to create your tunnel.

Just like the form above, select an Account , enter a Name for the tunnel, set the Tunnel Type to Persistent , and the Access to Public. Then click OK.

When you set the Tunnel Type to Persistent, the URL of your dev tunnel is preserved until you delete the tunnel. When set to Temporary, the URL of the tunnel changes whenever you restart Visual Studio. The Tunnel Access has three options:

Private : Only you can access the web application by logging in with your Visual Studio account. This is great for personally testing your application on other devices.
Organizational : Anyone within your organization can access the web application. You can use this to demo the application to your teammates.
Public : Anyone can access the web application, and you don't need to log in. Make sure it is safe for you to share your application publicly! This is what you need to receive HTTP requests from Twilio webhooks.

Just like before, Visual Studio will open your web browser and browse to your web application. However, this time it will browse to the public tunnel URL, which looks something like https://0pbvlk3m-7032.use.devtunnels.ms/.

Now you can open the same URL on any other device and send it to your friends and colleagues. As long as your project is running, they will be able to use the web application that is running locally on your machine.

Now that your application is publicly available, let's add some Twilio magic to it ☎️

Respond to SMS with ASP.NET Core

Buy a Twilio Phone Number

If you haven't done so already, you'll need to buy a Twilio phone number. To do that, log in to the Twilio Console, select Phone Numbers, and then click on the “ Buy a number ” button. Note that if you have a free account, you will be using your trial credit for this purchase.

On the “ Buy a Number ” page, select your country and check SMS in the “ Capabilities ” field. If you’d like to request a number that is local to your region, you can enter your area code in the “ Number ” field.

Click the “ Search ” button to see what numbers are available, and then click “ Buy ” for the number you like from the results. After you confirm your purchase, click the “ Close ” button.

Handle Twilio SMS webhook in ASP.NET Core

Since TwiML is XML, you can use any technique to produce the XML as a response to the Twilio webhook request. However, you can use the Twilio .NET SDK and the Twilio helper library for ASP.NET Core to make it easier.

First, make sure your application isn't running anymore. You can stop your app by pressing the red square icon in the Visual Studio top toolbar, or close the browser window.

In Visual Studio, right-click on the Dependencies node of your project, and click " Manage NuGet Packages". This will open the NuGet Package Manager window in Visual Studio. Click on the Browse tab and search for " Twilio.AspNet.Core". Click on the Twilio.AspNet.Core package by Twilio Labs, and click the Install button to install the latest version.

By installing the Twilio.AspNet.Core package, you also implicitly install the Twilio NuGet package which has the Twilio SDK. You can also explicitly install the Twilio NuGet package to choose the package version yourself.

Now, replace the code from Program.cs with the following code:

using Twilio.AspNet.Core.MinimalApi;
using Twilio.TwiML;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapPost("/message", () =>
{
var messagingResponse = new MessagingResponse();
 messagingResponse.Message("Ahoy!");
return Results.Extensions.TwiML(messagingResponse);
});

app.Run();

The "Hello World!" GET / endpoint has been replaced with the /message endpoint. The /message endpoint creates a MessagingResponse. messagingResponse.Message("Ahoy!") will create a Message TwiML verb to respond with "Ahoy!".

Lastly, the Results.Extensions.TwiML method will create a TwiMLResult object which takes care of serializing the object to XML and setting the correct content-type headers.

Start your project again. Visual Studio will open the browser again, but you'll see a HTTP 404 error which is fine, this is expected. Copy the URL somewhere as you'll need it in the next section.

Configure your SMS webhook

Now that your web application is running and publicly available through the tunnel, you can now configure the messaging webhook on your Twilio Phone Number.

Back in the Twilio Console, navigate to Phone Numbers > Manage > Active Numbers , or click this link to the Active Numbers page, then click on your Twilio Phone Number to navigate to the configuration page. Scroll down to the Messaging section and where it says " A MESSAGE COMES IN", pick the " Webhook" option in the first dropdown, paste your Visual Studio tunnel URL and add the /message path, and then pick the " HTTP POST" option from the next dropdown.

Click the Save button.

Test your SMS application

Now that everything has been set up, it's time to test out your SMS application. Pull out your personal phone, and send an SMS to your Twilio Phone Number. You should receive a response saying "Ahoy!".

One thing I always do to gain a better understanding is to put a breakpoint in the application and see when the breakpoint is hit. Feel free to put a breakpoint inside the /message endpoint, and play around with the application to see what you can do with Twilio Messaging.

Alternatively, you can test your messaging and voice applications using the Twilio Dev Phone.

Next steps

Congratulations on building this SMS application! Since your application is now public, that also means anyone on the internet can reach it which comes with its own risks. To mitigate these risks, you can validate that the incoming requests originated from Twilio and not some bad actor. In this tutorial, you manually updated the webhook URL in the Twilio console, but you can also do this programmatically. Check out this follow-up tutorial on how to automatically configure your Twilio webhooks using Visual Studio dev tunnels.

Want to learn what else you can do with Twilio? Here are some more tutorials for inspiration:

Shout-out to Sayed I. Hashimi for answering my questions and taking my feedback.

How to create an ASP.NET Core Minimal API with Visual Basic .NET (there's no template)

Niels Swimburger.NET 🍔 — Thu, 25 Aug 2022 00:00:00 +0000

Visual Basic .NET (VB) is not dead, but it's not getting the same amount of love as C# or even F#. That is instantly clear when you list the available templates that come with the .NET SDK:

Only 6 out 23 project templates have support for VB, while F# has support for 10, and C# has support for all of them.

However, this does not mean you cannot recreate the C# template in VB. In this tutorial, you'll see how you can start from the VB console template, and update it to a ASP.NET Core Minimal API project.

Prerequisites

To follow along you'll need to have the .NET 6 SDK or newer on your machine, and I recommend using a .NET editor with VB support such as Visual Studio or JetBrains Rider.

Create a C# Minimal API and VB Console project

The easiest way to convert a C# project template to VB, is to generate that C# project, generate a VB console project, and then compare the two. So let's first create a C# Minimal API project and VB Console project. Open a terminal and run the following .NET CLI commands:

dotnet new web -lang C# -o MinimalApiSharp
dotnet new console -lang VB -o MinimalApiVb

Compare C# Minimal API and update VB Console app

The first files you need to compare are the project file: MinimalApiSharp/MinimalApiSharp.csproj and MinimalApiVb/MinimalApiVb.vbproj.

MinimalApiSharp/MinimalApiSharp.csproj:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

</Project>

Note: I'm using .NET 7, but you can apply the same technique to older and newer versions of .NET.

MinimalApiVb/MinimalApiVb.vbproj:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <RootNamespace>MinimalApiVb</RootNamespace>
    <TargetFramework>net7.0</TargetFramework>
  </PropertyGroup>

</Project>

You'll notice a couple differences between the two project files, but the difference that matters is the SDK that is being used. The Minimal API project uses the Microsoft.NET.Sdk.Web SDK which will load the necessary dependencies and build steps for running ASP.NET Core projects. In MinimalApiVb.vbproj, replace Microsoft.NET.Sdk with Microsoft.NET.Sdk.Web:

MinimalApiVb/MinimalApiVb.vbproj:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <RootNamespace>MinimalApiVb</RootNamespace>
    <TargetFramework>net7.0</TargetFramework>
  </PropertyGroup>

</Project>

Next, compare the MinimalApiSharp/Program.cs and MinimalApiVb/Program.vb files.

MinimalApiSharp/Program.cs:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

MinimalApiVb/Program.vb:

Imports System

Module Program
    Sub Main(args As String())
        Console.WriteLine("Hello World!")
    End Sub
End Module

Now you need to convert the C# code into VB code and place it into the Main method, like this:

Imports System

Module Program
    Sub Main(args As String())
        Dim builder = WebApplication.CreateBuilder(args)
        Dim app = builder.Build()
        app.MapGet("/", Function() "Hello World!")

        app.Run()
    End Sub
End Module

The C# project uses ImplicitUsings which means that commonly needed namespaces are already imported without explicitly having to import them with the using statement. This is great for C#, but makes it a little harder for you to discover which namespaces to import in your VB application. However, with a good IDE like Visual Studio and JetBrains Rider, importing namespaces is relatively straightforward.

Update the Imports statement like this:

Imports System
Imports Microsoft.AspNetCore.Builder
Imports Microsoft.AspNetCore.Http

Now you've got a working Minimal API using the VB language!

You can also copy and paste the appsettings.json and appsettings.Development.json file from the C# project into your VB project so you can configure your application using the JSON files.

Now, go ahead and test your application by running dotnet run. The command will print the localhost URLs where your app is hosted. Grab the URL and open it in your browser to see "Hello World!".

Conclusion

While VB is still supported by Microsoft, it isn't getting the same level of support which you can see in the missing project templates. Luckily, all that is .NET can be used by all .NET languages including VB, so you can still use ASP.NET Core and Minimal APIs with the VB language.

Find your US Representatives and Congressional Districts with SMS and ASP.NET Core

Niels Swimburger.NET 🍔 — Tue, 02 Aug 2022 00:00:00 +0000

This blog post was written for Twilio and originally published at the Twilio blog.

When someone runs for office in the United States of America (U.S.), they have to fulfill certain "Ballot Access Requirements" to become listed on the ballot. One of those requirements could be that you need a certain number of signatures per district. So when volunteers and campaign workers go out to gather signatures, it is instrumental to know which congressional district (CD) the signee belongs to. However, knowing which congressional district you are from is not common knowledge, especially in areas where the district cuts right through counties, cities, and neighborhoods.

States redraw their congressional districts every decade after getting an updated population count from the Census Bureau. Each district is represented by a single U.S. representative in the U.S. House of Representatives. However, the manner in which these districts are drawn often result in unique and odd shapes which can be confusing. This is why constituents living just a street apart sometimes live in different districts, and as a result, vote in different house races.

This blog post won't discuss why U.S. congressional district maps are drawn the way they are, however, I highly recommend you look into this topic and learn how it affects political voting power.

When I gathered signatures, the first question I had to ask over and over again was "what congressional district are you from?", and 95% of the time, the answer was "I don't know". That's because in Northern Virginia, the border between the 10th and 11th congressional district cuts directly through some counties, cities, neighborhoods, and streets.

Map of Virginia's 11th Congressional District

The house.gov website has a tool to look up your congressional district and representative, but unfortunately, the tool is slow and painful to use, especially when you're on the go on mobile internet.

That's why instead of using web technology, I built a solution using connectivity technology that's more accessible, more reliable, and simpler. Using Twilio SMS, I built a phone number that you can text your address to and you will receive a response with your congressional district and representative. Let me walk you through how you can build this SMS bot using Twilio, C# .NET, and Google's Civic Information API.

Prerequisites

You'll need a couple of things to follow along:

.NET 6 SDK (older or newer should work too)
A code editor or IDE (I recommend VS Code with the C# plugin, Visual Studio, or JetBrains Rider)
The ngrok CLI, and optionally, a free ngrok account
A Twilio account (If you register for a Twilio account here, you'll receive $10 in Twilio credit when you upgrade to a paid account!)
A Twilio Phone Number
A personal phone or the Twilio Dev Phone to test your bot
A free Google Cloud account

You can find the source code for this tutorial on GitHub. Use it as a reference if you run into any issues, or submit an issue if you need assistance.

Get Started with the Google Civic Information API

This SMS bot will use the Google Civic Information API to look up the U.S. congressional districts and representatives. This API has a free tier as part of the Google Cloud Platform.

Go to the Google Cloud Console and create a new project. Once the project is created, select the project using the project dropdown in the top-left navigation bar.

You'll first need to enable the Civic Information API. Click on "ENABLE APIS AND SERVICES", then search for the " Civic Information API".

Click on the search result and then click ENABLE.

Now that the API is enabled for your project, you'll need to create an API token to be able to authenticate when consuming the API from your .NET project. Navigate to the Credentials page, click on " CREATE CREDENTIALS" and then on " API key".

A modal will appear showing your API key. You will need this API key later, so copy and paste the API key somewhere safe. Next, click on the " Edit API key" link.

On the " Edit API key" page, you can configure the name and restrictions for your API key. This step isn't strictly required, but it is a good practice to follow the principle of least privilege, which means you should only give accounts and keys the level of access necessary to do their job.

In that spirit, find the " API restrictions" field and click on the " Restrict key" radio button.

Click on the newly appeared dropdown and select the " Google Civic Information API" option, and then hit Save.

You're all done setting up your GCP project and API key. Let's go try out the API!

Try out the Civic Information API

Open a new tab in your browser and navigate to the Civic Information API documentation for getting representatives by address.The representativeInfoByAddress will be the specific method that you'll be using for this project.

You can pass a couple of parameters to the method to filter down the representative information, most importantly the required address field. This address field expects a physical mail address, however, it can be a partial address. You can pass in just the ZIP code, the city and state, or a full address including the street and number.

The HTTP response will contain divisions, offices, and officials for the given address:

divisions are the political geographic areas that the address is within. Among these you would find the U.S. congressional districts.
offices are the political offices someone can be elected to within the returned divisions.
officials are the elected officials holding the returned offices.

By default, representativeInfoByAddress will return all divisions, offices, and officials that represent the given address, all the way from the highest office of the President down to the local offices.

To filter this down, you can pass in the levels and roles parameters.

This bot will look for U.S. representatives, so to filter down to only return representatives, you'll need to pass in country into the levels parameter because the U.S. representative is a national office, and you'll need to pass in legislatorLowerBody to the roles parameter because U.S. Congress has two houses: the Senate is the upper body and the House of Representatives is the lower body.

Click the "Try it now" link at the top of the page and play around with the method.

Set the address field to 10600 Little Run Farm Ct, Vienna, the levels to country, and roles to legislatorLowerBody, and then click EXECUTE.

The response should have a single division, office, and official.

New congressional district maps are going into effect for the November 2022 elections, so the maps and data will change soon!

Now change the address field to Little Run Farm Ct, Vienna and click EXECUTE again.

This time no division, office, or official is returned. Why is that?

When you look up this street and overlay the congressional district maps, you can see that the border of district 10 and 11 cuts through this street. In fact, the border follows a creek that runs between house number 10600 and 10602.

That's why the Civic Information API cannot determine the district when you pass in the street without a house number, and as a result, representativeInfoByAddress returns nothing.

The house.gov representative lookup tool will claim that house number 10600 and 10602 are both in Virginia's 11th congressional district which is incorrect (for the pre-2022 maps which are current at the time of writing this). Luckily, the Civic Information API returns the correct result.

This does not mean you always have to enter a full address, in fact when you put in the ZIP code 20301 without anything else, representativeInfoByAddress returns the information for the 8th congressional district. That's because the entire ZIP code is located within district 8, so the API doesn't need more information to determine the district.

Now that you're more familiar with the Civic Information API and specifically the representativeInfoByAddress method, it's time to consume the API from .NET!

Build an SMS bot to look up representatives

This project will be built on ASP.NET Core Minimal APIs. Open a shell and run the following command to create the project and navigate into the project folder:

dotnet new web -o RepresentativeBot
cd RepresentativeBot

Open the project in your preferred editor.

Retrieve Representatives from the Civic Information API

You can consume the Civic Information API using an HTTP client, but Google generates .NET libraries for all of its APIs including this one, which is convenient. You can install the library by adding the Google.Apis.CivicInfo.v2 NuGet packageusing the following command:

dotnet add package Google.Apis.CivicInfo.v2

Create a new file RepresentativeLookupClient.cs and add the following C# code:

using System.Net;
using Google;
using Google.Apis.CivicInfo.v2;
using Google.Apis.CivicInfo.v2.Data;
using Google.Apis.Services;
using static Google.Apis.CivicInfo.v2.RepresentativesResource;

namespace RepresentativeBot;

public class RepresentativeLookupClient
{
    private readonly CivicInfoService service;

    public RepresentativeLookupClient(string gcpApiKey)
    {
        service = new CivicInfoService(new BaseClientService.Initializer
        {
            ApplicationName = "US Representative Lookup",
            ApiKey = gcpApiKey
        });
    }

    public async Task<Representative> GetRepresentativeByAddress(string address)
    {
        var request = new RepresentativeInfoByAddressRequest(service)
        {
            Address = address,
            // Level = Country and Roles = LegislatorLowerBody filters down to U.S. Representatives
            Levels = RepresentativeInfoByAddressRequest.LevelsEnum.Country,
            Roles = RepresentativeInfoByAddressRequest.RolesEnum.LegislatorLowerBody
        };

        RepresentativeInfoResponse response;
        try
        {
            response = await request.ExecuteAsync();
        }
        catch (GoogleApiException e) when (e.HttpStatusCode == HttpStatusCode.BadRequest &&
                                           e.Error.Message == "Failed to parse address")
        {
            throw new FailedToParseAddressException(e);
        }

        // if the address did not resolve to a specific district,
        // for example, no district, or multiple districts
        // then response.Offices will be null
        if (response.Offices == null)
        {
            throw new RepresentativeNotFoundException();
        }

        // only one office, one division, and one official will be returned
        // the office of U.S. representative, the congressional district, and the elected official
        var office = response.Offices[0];
        var division = response.Divisions[office.DivisionId];
        var official = response.Officials[0];
        return new Representative
        {
            DistrictName = division.Name,
            RepresentativeName = official.Name,
            Party = official.Party,
            PhotoUrl = official.PhotoUrl
        };
    }
}

The RepresentativeLookupClient constructor accepts the GCP API key as the gcpApiKey parameter, which is then used to create a new CivicInfoService object that is stored into the service field.

The GetRepresentativeByAddress method accepts an address as a parameter and returns a Task that will resolve to a Representative object. In this method, a RepresentativeInfoByAddressRequest object is created passing in the service into the constructor and the address into the Address property.

The Levels and Roles property are hard-coded to Country and LegislatorLowerBody to filter down to U.S. representatives and congressional districts.

The API request is made using the request.ExecuteAsync method, which is surrounded by a try/catch block to handle some of the exceptions that can be thrown. When the API fails to parse the address, a custom exception of type FailedToParseAddressException is thrown. When no offices are returned, because the API couldn't determine the correct congressional district, or for some other reason, then a custom exception of RepresentativeNotFoundException is thrown. These two custom exceptions will be caught later to provide user-friendly messages to the end user.

However, if an office is returned, then a new Representative object is created with the data from the response.

The Representative object only has a couple of properties, however, feel free to extend the class and retrieve more information from the response object. The API retrieves a bunch of information like a physical address, an email address, a phone number, social media links, etc.

For example, here's a tutorial that uses the same API to retrieve contact information of the representatives and uses Twilio SMS and SendGrid to contact them, built on Twilio Studio and Functions.

Create 3 new files named Representative.cs, FailedToParseAddressException.cs, and RepresentativeNotFoundException.cs and then update each file with the contents listed below.

Representative.cs:

namespace RepresentativeBot;

public class Representative
{
    public string DistrictName { get; set; }
    public string RepresentativeName { get; set; }
    public string Party { get; set; }
    public string PhotoUrl { get; set; }
}

FailedToParseAddressException.cs:

namespace RepresentativeBot;

public class FailedToParseAddressException : Exception
{
    public FailedToParseAddressException(Exception innerException) : base(innerException.Message, innerException)
    {
    }
}

RepresentativeNotFoundException.cs:

namespace RepresentativeBot;

public class RepresentativeNotFoundException : Exception
{
}

To use the RepresentativeLookupClient in your future API endpoints, you'll need to add it to ASP.NET Core's Dependency Injection (DI) container. Open your Program.cs file and add the highlighted lines to the existing code:

using RepresentativeBot;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddScoped(provider =>
{
    var configuration = provider.GetRequiredService<IConfiguration>();
    var gcpApiKey = configuration["GcpApiKey"] ?? throw new Exception("GcpApiKey is not configured.");
    return new RepresentativeLookupClient(gcpApiKey);
});

var app = builder.Build();
...

The GCP API key you created earlier needs to be configured using the GcpApiKey configuration key. Since the API key is a secret, you should avoid hard-coding it or storing it in source control.You can use environment variables or a secure vault service, or for local development, you can use the .NET Secrets Manager also known as user secrets.

Run the following command to initialize user secrets in your project:

dotnet user-secrets init

Next, configure the GCP API key as a user secret:

dotnet user-secrets set GcpApiKey "[YOUR_GCP_API_KEY]"

Replace [YOUR_GCP_API_KEY] with the API key secret you copied earlier.

The RepresentativeLookupClient is now ready to be used! Feel free to add some code to quickly test it out, otherwise, move to the next step where you'll integrate the client into your minimal API.

Create your Twilio Webhook

There's a useful library called Twilio.AspNet which will help you build Twilio webhooks.

Add the Twilio.AspNet.Core NuGet package to install the library:

dotnet add package Twilio.AspNet.Core

Then, open your Program.cs file and update it with the following code:

using RepresentativeBot;
using Twilio.AspNet.Core.MinimalApi;
using Twilio.TwiML;
using Twilio.TwiML.Messaging;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddScoped(provider =>
{
    var configuration = provider.GetRequiredService<IConfiguration>();
    var gcpApiKey = configuration["GcpApiKey"] ?? throw new Exception("GcpApiKey is not configured.");
    return new RepresentativeLookupClient(gcpApiKey);
});

var app = builder.Build();

app.MapPost("/message", async (
    HttpRequest request,
    HttpResponse response,
    IServiceProvider serviceProvider,
    ILogger<Program> logger
) =>
{
    var messagingResponse = new MessagingResponse();

    if (bool.Parse(request.Cookies["HasBeenGreeted"] ?? "False") == false)
    {
        response.Cookies.Append("HasBeenGreeted", "True");
        messagingResponse.Message("Welcome to the U.S. Representative lookup bot. Respond with your address.");
        return Results.Extensions.TwiML(messagingResponse);
    }

    // TODO: remove me
    messagingResponse.Message("YOU HAVE BEEN GREETED ALREADY!");

    return Results.Extensions.TwiML(messagingResponse);
});

app.Run();

The new /message endpoint accepts a couple of parameters that will be dependency injected.

The MessagingResponse object will help you construct TwiML to respond to an incoming message.

The first message you will respond with, is an introductory message. To only introduce the bot once, a cookie is used to keep track of whether the sender has been greeted with the introduction.

You can use cookies when responding to Twilio webhooks, however, the cookie will expire after 4 hours and you can only store one cookie. In this tutorial you only need to keep track of one thing using cookies, but if you need to keep track of more state you can use a session cookie instead and store state in session. Learn more about the cookie limitations with Twilio webhooks here.

The messagingResponse.Message method is used to create a TwiML Message verb that will respond to the sender. The Results.Extensions.TwiML method creates a TwiMLResult that will serialize the messagingResponse to XML and set the correct content-type header.

If the sender has already been greeted, the bot responds with "YOU HAVE BEEN GREETED ALREADY!".

However, this last message is a placeholder. Replace the placeholder with the following code:

var form = await request.ReadFormAsync().ConfigureAwait(false);
var body = form["Body"][0];

var representativeLookupClient = serviceProvider.GetRequiredService<RepresentativeLookupClient>();
try
{
    var representative = await representativeLookupClient.GetRepresentativeByAddress(body);
    messagingResponse.Message(
        $"Your representative is {representative.RepresentativeName} ({representative.Party})" +
        $", representing {representative.DistrictName}."
    );

    if (representative.PhotoUrl is not null)
    {
        messagingResponse.Append(new Message().Media(new Uri(representative.PhotoUrl)));
    }
}
catch (FailedToParseAddressException)
{
    messagingResponse.Message("The address you entered is invalid.");
}
catch (RepresentativeNotFoundException)
{
    messagingResponse.Message("Your representative could not be determined. " +
                              "This may be because there's no representative or multiple representatives for the given location. " +
                              "Try entering a more specific address.");
}
catch (Exception ex)
{
    logger.LogError(ex, "An unexpected error occurred when looking up representative");
    messagingResponse.Message("An unexpected error occurred.");
}

Once the sender has been greeted, the bot will assume that whatever message is sent next will be the address to return representative information for. The message that is sent will be stored in the form encoded "Body" parameter.

After getting the body of the message, the bot will request an instance of RepresentativeLookupClient from the DI container, then the bot invokes the RepresentativeLookupClient.GetRepresentativeByAddress method passing in the body as a parameter.

If no exception occurs, two messages will be added. One message will describe the district and representative, and the other will return the image of the elected official, if an image is provided.

A TwiML Message with Media will send the media as an MMS message, not as an SMS. You can choose to create a single message with the representative information and the image which looks great!

However, I chose to create separate messages because of these reasons:

An SMS is smaller and will be transmitted to the user faster, giving them the information as quickly as possible.
MMS uses mobile internet which may not be turned on, or there may be no mobile internet connectivity in rural areas.
MMS may not be properly configured or disabled.

Your project is ready! Start your project using dotnet run.

To quickly test out your /message endpoint, you can use the following PowerShell or Bash script in a new shell tab:

PowerShell:

Invoke-WebRequest [YOUR_LOCALHOST_URL]/message `
    -Method Post `
    -Body @{ Body = 'Hi' } `
    -ContentType 'application/x-www-form-urlencoded' `
    -SessionVariable SmsBotSession

Invoke-WebRequest [YOUR_LOCALHOST_URL]/message `
    -Method Post `
    -Body @{ Body = '10602 Little Run Farm Ct, Vienna' } `
    -ContentType 'application/x-www-form-urlencoded' `
    -WebSession $SmsBotSession

Bash:

curl -X POST [YOUR_LOCALHOST_URL]/message \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "Body=Hi" \
    --cookie-jar SmsBotCookieJar

curl -X POST [YOUR_LOCALHOST_URL]/message \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "Body=10602 Little Run Farm Ct, Vienna" \
    --cookie SmsBotCookieJar

rm SmsBotCookieJar

Replace [YOUR_LOCALHOST_URL] with one of the localhost URLs printed out when running your .NET project.

The first web request will be responded to with the following TwiML:

<?xml version="1.0" encoding="utf-8"?>
<Response>
  <Message>Welcome to the U.S. representative lookup bot. Respond with your address.</Message>
</Response>

The subsequent request will be responded to with the following TwiML:

<?xml version="1.0" encoding="utf-8"?>
<Response>
  <Message>Your representative is Gerald E. "Gerry" Connolly (Democratic Party), representing Virginia's 11th congressional district.</Message>
  <Message>
    <Media>http://bioguide.congress.gov/bioguide/photo/C/C001078.jpg</Media>
  </Message>
</Response>

If everything is working as expected, you can now configure your Twilio Phone Number to use your Minimal API endpoint as the SMS webhook.

Configure your Twilio SMS Webhook

Start your project if it isn't running yet (dotnet run) and take note of one of the localhost URLs printed out by the application. For Twilio to be able to send HTTP requests to your local web server, the server needs to become publicly accessible. ngrok is a free secure tunneling service that can make your local web servers public.

Run the following ngrok command in a separate shell:

ngrok http [YOUR_ASPNET_URL]

Replace [YOUR_ASPNET_URL] with the localhost URL from your .NET application. If you're using an HTTPS localhost URL, you'll need to authenticate ngrok.

The ngrok command will display an HTTPS Forwarding URL that makes your local web server public.

Now it's time to update your Twilio Phone Number to send HTTP requests to your /message endpoint via the ngrok Forwarding URL. The URL should look something like https://1cc74f4c9f70.ngrok.io/message.

Go to the Active Phone Numbers section in the Twilio Console and click on your Twilio Phone Number.

This will take you to the configuration for the phone number. Find the Messaging section and under the " A MESSAGE COMES IN" label, set the dropdown to Webhook. In the text field next to it, enter your ngrok forwarding URL with /message appended to it. Select “ HTTP POST ” in the last dropdown.

Finally, click the Save button at the bottom of the page.

Test your SMS Twilio Bot

To test your bot, you can either use a personal phone to send text messages, or you can use the Twilio Dev Phone to test.

Send a text message to your Twilio Phone Number with anything as the body. You should receive the greeting you configured. Once you've been greeted, reply with any address that you want to retrieve representative and district information for.

Future improvements

This bot is a great start, however, you can improve this solution in a couple of ways:

You can respond to the user with more information about the elected official and how to reach them. And instead of only returning U.S. representatives, you could return elected officials from every level.

Currently, anyone can send HTTP requests to your webhook and pretend to be Twilio. This bot doesn't respond with any sensitive information so the risk is lower, however, it is always a good idea to secure your webhooks using webhook signature validation.

In this tutorial, you manually spun up a secure tunnel using ngrok, but you could also do this programmatically so that a tunnel is created and your Twilio SMS webhook is updated whenever you start your .NET application.

Next steps

If you made it this far, a big shout-out to you! 🎉

In this tutorial, you learned how to respond to incoming text messages with Twilio, but if you’re looking to learn more, you can also initiate text messages yourself using the Twilio SDK, or send emails using Twilio SendGrid.

If you found this useful, let me know and share what you're working on. I can't wait to see what you build!

Image credit: Matthew Geason has kindly allowed us to use his picture of the U.S. Capitol.

How to Bulk Email with C# and .NET: Zero to Hero

Niels Swimburger.NET 🍔 — Tue, 02 Aug 2022 00:00:00 +0000

This blog post was written for Twilio and originally published at the Twilio blog.

In a previous tutorial, I shared how you can send individual emails using the SendGrid API. This use case is perfect for transactional emails where you send an email to a single recipient or a small number of recipients. But what if you need to send emails to a very large audience? Well, in this tutorial you'll learn how to send bulk emails using the SendGrid API and C# .NET.

If you're not familiar with sending transactional emails using .NET, I advise you go through the previous post about sending emails with C# and SendGrid first.

Prerequisites

Here’s what you will need to follow along:

Git CLI
.NET 6 SDK
A code editor or IDE (I recommend VS Code with the C# plugin, Visual Studio, or JetBrains Rider)
A Twilio SendGrid account. Sign up for a SendGrid account here to send up to 100 emails per day completely free of charge.
You'll need an Email Sender configured in SendGrid to send emails from, and you'll need an API key with permission to send emails. Both of these steps can be found in the Configuring your SendGrid account to send emails section in the previous tutorial.
An email address for testing, preferably from an email service that supports Subaddressing.

Many email services like Gmail and Outlook allow you to put a + sign and any string before the @ symbol like this youremail+test123@gmail.com. Emails sent to this type of address will still be delivered to the original email address. This feature is called Subaddressing. By using subaddressing, you will be able to test sending multiple emails to "different" addresses, however, email services will still prevent large amount of emails from coming through even when using subaddressing.

You can find the source code for this tutorial on GitHub. Use it if you run into any issues, or submit an issue, if you run into problems.

Send bulk email with C# .NET

As is common in software development, there are many solutions to a given problem, and the best solution depends on your use case; the same goes for sending email in bulk. This tutorial will walk you through all the different ways of sending bulk email, and you'll learn which to use for your specific use case.

Setup

For this tutorial, I have provided a starter project. Open a shell and run the following commands to clone the project and navigate to the project folder:

git clone https://github.com/Swimburger/BulkEmail.git --branch start
cd BulkEmail

The project is a console application which currently only sends one email.

The console app has the following C# files:

Program.cs: This is the starting point of the application, it will configure everything and then send the emails.
SenderOptions.cs: This file has the SenderOptions class which is used to store some configuration about the SendGrid Email Sender.
SubscriberRepository.cs: This file has the SubscriberRepository class which is responsible for returning your imaginary subscribers, represented as Person objects. The Person class is provided by the Bogus library and the subscribers are fake data generated using the same library, for testing purposes. Let's pretend this class retrieves real data from a SQL database as it would look exactly the same from the outside.

Feel free to take a look at these C# files, but don't worry about them, because the only important C# file is EmailSender.cs. This file has the EmailSender class which you will update so that it sends bulk email.

This project does need some configuration which you will store as user secrets. Run the following commands:

dotnet user-secrets set SendGridApiKey [SENDGRID_API_KEY]
dotnet user-secrets set Sender:Email [SENDER_EMAIL]
dotnet user-secrets set Sender:Name '[SENDER_NAME]'
dotnet user-secrets set ToEmailTemplate '[YOUR_EMAIL_TEMPLATE]'

Replace:

[SENDGRID_API_KEY] with the API key you created in SendGrid,
[SENDER_EMAIL] with your Sender email address that you verified in SendGrid,
[SENDER_NAME] with the name you want the recipients to see,
[YOUR_EMAIL_TEMPLATE] with the email address you use to test. If you're using subaddressing, use this format: youremail+{0}@gmail.com. {0} will be replaced by the program with unique numbers. If you're not using subaddressing, use your email address without any special modifications.

Now your project should be ready. Try it out by running the project using this command:

dotnet run --SubscriberCount 5

Even though you specified 5 subscribers, you should only receive one email in your inbox. That's because the EmailSender class only sends one email at the moment.

Let's take a look at the EmailSender.cs file:

using System.Text.Encodings.Web;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using SendGrid;
using SendGrid.Helpers.Mail;

namespace BulkEmail;

public class EmailSender
{
    private readonly SubscriberRepository subscriberRepository;
    private readonly ISendGridClient sendGridClient;
    private readonly ILogger<EmailSender> logger;
    private readonly HtmlEncoder htmlEncoder;
    private readonly SenderOptions sender;

    public EmailSender(
        SubscriberRepository subscriberRepository,
        ISendGridClient sendGridClient,
        IOptions<SenderOptions> senderOptions,
        ILogger<EmailSender> logger,
        HtmlEncoder htmlEncoder
    )
    {
        this.subscriberRepository = subscriberRepository;
        this.sendGridClient = sendGridClient;
        this.logger = logger;
        this.htmlEncoder = htmlEncoder;
        this.sender = senderOptions.Value;
    }

    public async Task SendToSubscribers()
    {
        var subscribers = subscriberRepository.GetAll();
        var subscriber = subscribers.First();

        var message = new SendGridMessage
        {
            From = new EmailAddress(sender.Email, sender.Name),
            Subject = "Ahoy matey!",
            HtmlContent = "Welcome aboard <b>friend</b> ⚓️"️,
        };
        message.AddTo(new EmailAddress(subscriber.Email, subscriber.FullName));

        var response = await sendGridClient.SendEmailAsync(message);
        if (response.IsSuccessStatusCode) logger.LogInformation("Email queued");
        else logger.LogError("Email not queued");
    }
}

The EmailSender receives a bunch of parameters via its constructor and stores them into fields. Some of these are unused right now but will be used later. The SendToSubscribers method is responsible for sending an email to all subscribers coming from the SubscriberRepository, but currently it only grabs the first subscriber and stores it in the subscriber variable.

The SendToSubscribers method then creates a SendGridMessage from your configured sender and adds the subscriber as the recipient. Next, the SendGridMessage is passed into the SendEmailAsync method which sends the email to the SendGrid API. The SendGrid API will queue the email and return an HTTP success status code in the response if successful. Lastly, the method logs whether the email was queued or not.

Currently, the program only emails one subscriber, however, the goal is to send an email to all subscribers. Let's fix that!

Bulk email using loops

The first solution is to wrap the email code in a loop. In this example, you can use a foreach -loop like this:

var subscribers = subscriberRepository.GetAll();
foreach (var subscriber in subscribers)
{
    var message = new SendGridMessage
    {
        From = new EmailAddress(sender.Email, sender.Name),
        Subject = "Ahoy matey!",
        HtmlContent = "Welcome aboard <b>friend</b> ⚓️"️,
    };

    message.AddTo(new EmailAddress(subscriber.Email, subscriber.FullName));

    var response = await sendGridClient.SendEmailAsync(message);
    if (response.IsSuccessStatusCode) logger.LogInformation("Email queued");
    else logger.LogError("Email not queued");
}

Replace lines 34 to 47 in the EmailSender.cs file with the above code and save the file. Use the following command to try it out with 5 subscribers, or however many you'd like to spam your own inbox with:

dotnet run --SubscriberCount 5

This is the easiest and most flexible solution, however, it is also the least performant solution.

You could further optimize this solution using parallelization or using Task.WhenAll, however, keep in mind that you can send a maximum of 10,000 API requests per second as noted in the v3 Mail Send API FAQ.

Customize the email per recipient

When you send emails in bulk by submitting a SendGridMessage for every recipient, you have complete control over every email. To customize the subject and email body, you can use any means necessary.

Here's an example that uses string interpolation to customize the subject and email body:

var message = new SendGridMessage
{
    From = new EmailAddress(sender.Email, sender.Name),
    Subject = $"Ahoy {subscriber.FirstName}!",
    HtmlContent = $"Welcome aboard <b>{htmlEncoder.Encode(subscriber.FullName)}</b> ⚓️"️
};

When you build HTML templates and embed user input, your application may become vulnerable to HTML injection attacks. To prevent HTML injection attacks, always encode user input. In the example above the subscriber's full name is HTML encoded using the HtmlEncoder.Encode method. For more details, read How to prevent email HTML injection in C# and .NET.

This works fine for a proof of concept, but in a real application you could use a template engine to generate your HTML. Check out this article about rendering emails using Razor templates to learn more.

Bulk email using Personalizations

The loop solution sends a new API request for every subscriber, but there is actually a way to send many emails using a single API request.

The SendGridMessage class has a property called Personalizations which is of type List<Personalization>. Using these personalizations, you can customize the message for specific recipients using properties like From, Tos, Ccs, Bccs, Subject, etc. However, you cannot override the TextContent or HtmlContent property from the SendGridMessage.

Take a look at this example:

new SendGridMessage
{
    From = new EmailAddress(sender.Email, sender.Name),
    Subject = "Ahoy matey!",
    HtmlContent = "Welcome aboard <b>friend</b> ⚓️"️,
    Personalizations = new List<Personalization>
    {
        new Personalization
        {
            Tos = new List<EmailAddress>
            {
                new EmailAddress("jon@localhost", "Jon")
            }
        },
        new Personalization
        {
            Tos = new List<EmailAddress>
            {
                new EmailAddress("jill@localhost", "Jill"),
                new EmailAddress("jane@localhost", "Jane")
            },
            Subject = "Hello world!"
        }
    }
};

The SendGridMessage in the snippet above will send 2 emails because there are 2 personalizations. One email with the subject "Ahoy matey!" to jon@localhost, and 1 email with the subject "Hello world!" to jill@localhost and jane@localhost.

When you add multiple email addresses to the Tos property, each recipient can see and reply to all the other recipients. So Jill and Jane in the example above will be able to see and reply to each other. To avoid this you can create separate Personalization objects for each recipient. In fact, when you previously used the SendGridMessage.AddTo method, the method created a personalization for you.

You can have up to 1,000 recipients per SendGridMessage. Tos, Ccs, and Bccs across all personalizations all add up to the 1,000 limit. The maximum number of Personalization objects per SendGridMessage is also 1,000.

Since you can only have 1,000 recipients per message, you'll need to paginate over the subscribers. There is a GetByPage(int pageSize, int pageIndex) method in the SubscriberRepository to help with pagination. The following code will paginate over all subscribers by 1,000 subscribers at a time.

var pageSize = 1_000;
var subscriberCount = subscriberRepository.Count();
var amountOfPages = (int) Math.Ceiling((double) subscriberCount / pageSize);

for (var pageIndex = 0; pageIndex < amountOfPages; pageIndex++)
{
    var subscribers = subscriberRepository.GetByPage(pageSize, pageIndex);
    ...
}

Even if you weren't limited by 1,000 recipients per message, it would still be a good idea to paginate over the subscribers to reduce the memory usage of your application. As the number of subscribers increases, your application would run out of memory when loading all subscribers into memory at once.

Now that you have your subscribers, you can create a Personalization object for every one of them. Here's how you can do this using a LINQ query:

var message = new SendGridMessage
{
    From = new EmailAddress(sender.Email, sender.Name),
    Subject = "Ahoy matey!",
    HtmlContent = "Welcome aboard <b>friend</b> ⚓️"️,

    // max 1000 Personalizations
    Personalizations = subscribers.Select(s => new Personalization
    {
        Tos = new List<EmailAddress> {new EmailAddress(s.Email, s.FullName)},
    }).ToList(),
};

After putting all the previous code snippets together, your SendToSubscribers method should look like this:

public async Task SendToSubscribers()
{
    var pageSize = 1_000;
    var subscriberCount = subscriberRepository.Count();
    var amountOfPages = (int) Math.Ceiling((double) subscriberCount / pageSize);

    for (var pageIndex = 0; pageIndex < amountOfPages; pageIndex++)
    {
        var subscribers = subscriberRepository.GetByPage(pageSize, pageIndex);

        var message = new SendGridMessage
        {
            From = new EmailAddress(sender.Email, sender.Name),
            Subject = "Ahoy matey!",
            HtmlContent = "Welcome aboard <b>friend</b> ⚓️"️,

            // max 1000 Personalizations
            Personalizations = subscribers.Select(s => new Personalization
            {
                Tos = new List<EmailAddress> {new EmailAddress(s.Email, s.FullName)},
            }).ToList(),
        };

        var response = await sendGridClient.SendEmailAsync(message);
        if (response.IsSuccessStatusCode) logger.LogInformation("Email queued");
        else logger.LogError("Email not queued");
    }
}

You can lower the pageSize number to test pagination without sending 1,000 emails to your inbox.

For example, for testing purposes, you could set the pageSize to 5 and the SubscriberCount to 20:

dotnet run --SubscriberCount 20

Customize the email per recipient

As I mentioned before, you can override the email subject in a Personalization object, but not the HtmlContent or TextContent. However, you can still customize the email body per recipient using Substitution Tags.

First, add substitution tags to your content like this:

HtmlContent = "Welcome aboard <b>-FullName-</b> ⚓️"️

Then, add substitutions to your Personalization objects like this:

new Personalization
{
    ...
    // Substitutions data is max 10,000 bytes per Personalization object
    Substitutions = new Dictionary<string, string>
    {
        {"-FullName-", htmlEncoder.Encode(s.FullName)}
    }
}

The substitution tag is decorated with dashes (-) in this example, however, you can use any type of decoration characters, as long as the substitution tags in the HtmlContent and TextContent match with the keys of the Substitutions dictionary.

You can also use these substitution tags inside of your email subject. Putting this together, you can send personalized bulk emails like this:

var message = new SendGridMessage
{
    From = new EmailAddress(sender.Email, sender.Name),
    Subject = "Ahoy -FirstName_Raw-!",
    HtmlContent = "Welcome aboard <b>-FullName-</b> ⚓️"️,

    // max 1000 Personalizations
    Personalizations = subscribers.Select(s => new Personalization
    {
        Tos = new List<EmailAddress> {new EmailAddress(s.Email, s.FullName)},
        // Substitutions data is max 10,000 bytes per Personalization object
        Substitutions = new Dictionary<string, string>
        {
            {"-FirstName_Raw-", s.FirstName},
            {"-FullName-", htmlEncoder.Encode(s.FullName)}
        }
    }).ToList(),
};

I chose to suffix the first name substitution tag with _Raw to indicate to myself and others that this variable is not HTML encoded and should not be used in HTML content, to avoid HTML injection.

Send bulk email using Dynamic Email Templates

Thus far, you provided the email subject and body from code, however, you can also use Dynamic Email Templates. You can create these templates using the SendGrid UI or API, and then instead of specifying the subject and content in your SendGridMessage, you set the ID of your template to the SendGridMessage.TemplateId property. Dynamic Email Templates use the Handlebars templating language, which allows you to do variable substitution, conditional rendering, looping, and more.

Implementing Dynamic Email Templates is out of the scope of this tutorial, however, here is what your SendGridMessage would look like to achieve the same result as before:

var message = new SendGridMessage
{
    From = new EmailAddress(sender.Email, sender.Name),
    TemplateId = "d-0a664e681ed14d76bd452637a15b20ab",
    Personalizations = subscribers.Select(s => new Personalization
    {
        Tos = new List<EmailAddress> {new EmailAddress(s.Email, s.FullName)},
        TemplateData = new
        {
            FirstName = s.FirstName,
            FullName = s.FullName
        }
    }).ToList(),
};

Instead of using the Substitutions property on your Personalization, you set the TemplateData property with an object. The Dynamic Email Template will be able to access all the data from the TemplateData object.

Want an in depth guide? Read this article on how to Send Emails with C#, Handlebars templating, and Dynamic Email Templates.

Since Dynamic Email Templates use the same SendGridMessage and Personalization classes, everything you learned about bulk email so far also applies here.

Send bulk email using Single Sends in SendGrid Marketing Campaigns

SendGrid Marketing Campaigns are also out of scope for this tutorial, but for the sake of completeness, I will lightly touch on it. With SendGrid Marketing Campaigns you can create signup forms, manage contacts, organize contacts into lists and segments, create email designs, and more.

And of course, you can send emails to those contacts stored in SendGrid.

You can manage all of the previous features using the SendGrid UI or API. For example, you can manage contacts using the SendGrid UI or programmatically via the API, and you can also send emails to your contacts, lists, and segments using the Single Send API. Since the contacts are all stored in SendGrid, you don't have to worry about any looping and paginating.

With the Single Send API you can either provide the email body via the API or you can specify the ID of the email design stored in SendGrid. For either option, you cannot pass on data through the API to use in the email template. However, the templates have access to the data stored on the contacts. Once you created the Single Send, you can schedule the Single Send to be sent "now" or up to 72 hours from now.

Schedule your bulk email

When you're sending a lot of emails, SendGrid recommends scheduling them to be sent in the near future instead of sending them immediately. Quoting from the SendGrid docs:

This technique allows for a more efficient way to distribute large email requests and can improve overall mail delivery time performance. This functionality:

Improves efficiency of processing and distributing large volumes of email.
Reduces email pre-processing time.
Enables you to time email arrival to increase open rates.
Is available for free to all SendGrid customers.

To schedule emails you can set the SendAt property on the SendGridMessage or Personalization object. The SendAt property is a long representing a Unix timestamp.

To calculate this Unix timestamp, you can use the DateTimeOffset.ToUnixTimeSeconds() method.

For example, this will generate the long timestamp for 5 minutes from now:

DateTimeOffset.Now.AddMinutes(5).ToUnixTimeSeconds()

If you're using DateTime instead of DateTimeOffset, you can implicitly and explicitly cast a DateTime to a DateTimeOffset, like this:

DateTimeOffset fiveMinutesFromNow = DateTime.Now.AddMinutes(5); // implicit cast
fiveMinutesFromNow = (DateTimeOffset) DateTime.Now.AddMinutes(5); // explicit cast

Check out this Microsoft doc on converting between DateTime and DateTimeOffset to learn more.

Here's the SendToSubscribers method for sending the Bulk Email 5 minutes from now:

public async Task SendToSubscribers()
{
    var sendAt = DateTimeOffset.Now.AddMinutes(5).ToUnixTimeSeconds();

    var pageSize = 1_000;
    var subscriberCount = subscriberRepository.Count();
    var amountOfPages = (int) Math.Ceiling((double) subscriberCount / pageSize);

    for (var pageIndex = 0; pageIndex < amountOfPages; pageIndex++)
    {
        var subscribers = subscriberRepository.GetByPage(pageSize, pageIndex);

        var message = new SendGridMessage
        {
            From = new EmailAddress(sender.Email, sender.Name),
            Subject = "Ahoy -FirstName_Raw-!",
            HtmlContent = "Welcome aboard <b>-FullName-</b> ⚓️"️,

            // max 1000 Personalizations
            Personalizations = subscribers.Select(s => new Personalization
            {
                Tos = new List<EmailAddress> {new EmailAddress(s.Email, s.FullName)},
                // Substitutions data is max 10,000 bytes per Personalization object
                Substitutions = new Dictionary<string, string>
                {
                    {"-FirstName_Raw-", s.FirstName},
                    {"-FullName-", htmlEncoder.Encode(s.FullName)}
                }
            }).ToList(),

            // max 72 hours from now
            SendAt = sendAt
        };

        var response = await sendGridClient.SendEmailAsync(message);
        if (response.IsSuccessStatusCode) logger.LogInformation("Email queued");
        else logger.LogError("Email not queued");
    }
}

You can schedule emails to be sent up to 72 hours from now. If you need to schedule beyond that time, I recommend scheduling emails using a job scheduler like Quartz.NET or Hangfire.

Unsubscribe recipients

When recipients mark your emails as spam, it hurts your reputation. As an email sender, you want to maintain a good reputation to maximize your email deliverability. You must also comply with anti-spam laws. Make sure to use a double opt-in process for things like newsletters, and always provide an unsubscribe link in your emails. You can add your own unsubscribe logic, or you can use Global Unsubscribes or Group Unsubscribes from SendGrid.

MailHelper

The SendGrid SDK contains a helper class called MailHelper. MailHelper has convenient static methods for the most common email scenarios, including bulk email.

The CreateSingleEmailToMultipleRecipients method lets you conveniently create a SendGridMessage to send emails to many recipients. By default it will create a Personalization for every recipient, but there's an overload where you can set the showAllRecipients parameter to true. When this parameter is set to true, the method will create one Personalization with all the recipients in it.

The CreateSingleTemplateEmailToMultipleRecipients method will create a SendGridMessage configured with a Dynamic Email Template and a Personalization for every recipient.

The CreateMultipleEmailsToMultipleRecipients method will create a SendGridMessage configured with a Personalization for every recipient and Substitution Tokens.

Which bulk email technique should you use?

You just learned many different ways to send email in bulk, but which should you use?

Not to be cliche, but it depends… Let's compare each technique:

When you're using loops, you have full control over every email you send and there are no limitations.However, this is the least performant solution because you have to send an HTTP request for each email.

Use loops when you need to do advanced customization of the subject and email body that is not possible using Substitution Tags, or with the Handlebars templating language. This solution is ideal if you want to generate the email body using the Razor templating language.

Using Personalizations will greatly improve the performance of your application because you can send 1,000 emails per HTTP request. If you don't need to customize the email body for each recipient, you can set the content once for all emails, without the need for Substitution Tokens or Dynamic Email Templates.

Personalizations with Substitution Tokens works great for doing simple email customizations where you need to substitute predefined variables for every recipient. You cannot do more complex templating like looping and conditional rendering.

When you're doing Personalizations with Dynamic Email Templates, you have to manage the email templates in SendGrid which could be a benefit or a drawback depending on your needs. Dynamic Email Templates use a fully featured templating language, Handlebars, which you can use to render the simplest to the most advanced templates.

If you don't want to store your contacts in your own database, you can store contacts in SendGrid and send emails to them using Single Sends. Single Sends uses the same Handlebar templating language, but can only access the data that is stored on the contact. This means you have to upload the data to your SendGrid contacts before sending the email that requires it. You can send emails to all your contacts, specific contact lists, or segments of your contacts and you can generate unsubscribe links. The unsubscribe links allow the contact to remove themselves from the contacts list. You also don't have to worry about looping or paginating over your contacts as SendGrid will do this for you. This is ideal for marketing emails and newsletters.

If you're still not sure, you could go down this decision tree:

Next steps

Big congratulations if you made it this far! 🎉

You learned how to send emails in bulk using a bunch of methods, each with their own advantages. However, this tutorial only covers the code side of things, but you should check out this guide on bulk emails to maximize the deliverability, engagement, and minimize the unsubscription rates.

If you want to see a practical example of bulk email in action, check out this tutorial on how to build an Email Newsletter application using ASP.NET Core and SendGrid. This tutorial manages the newsletter subscribers using Entity Framework Core and uses a form to upload the HTML newsletter which is then sent using Personalizations and Substitution Tokens.

How to test SMS and Phone Call applications with the Twilio Dev Phone

Niels Swimburger.NET 🍔 — Wed, 15 Jun 2022 00:00:00 +0000

This blog post was written for Twilio and originally published at the Twilio blog.

Twilio empowers you to build applications using phone numbers, text messaging, and voice calling. You can test these phone network based applications using any phone and phone number, but how do you test these applications without a phone? Maybe you're wondering, why not use your phone, which I'll get to later, but first how?!

Twilio Dev Phone to the rescue

What is the Twilio Dev Phone

The Twilio Dev Phone is a tool built on top of Twilio products that will let you send and receive phone calls and text messages from the browser. The Dev Phone is an open-source project on GitHub so feel free to read the source code and contribute to it. You can learn more about the Twilio Dev Phone in the docs.

Why use Twilio Dev Phone

As promised, here are some good scenarios when you'd want to use the Twilio Dev Phone instead of your own personal phone.

🌍 International apps

When you're building applications for an international audience, you'll have a local Twilio Phone Number for each country. However, in most cases, you probably don't and you don't want to incur those international charges to your personal phone plan. So instead, you can buy a Twilio Phone Number local to the desired country and then use the Twilio Dev Phone to make and receive phone calls and SMS!

You could even use this to test out Alpha Numeric Senders which may be available in other countries, but potentially not yours.

📶 Bad connection

Depending on where you live or work, you may have unreliable connectivity or no connectivity at all. Maybe your place of work is highly secured and communication is jammed, or you just lost your phone.You may not be able to use your phone in this scenario, but if you have an internet connection, you can use the Twilio Dev Phone!

🚤 Fast and convenient

When you're building applications on your computer, you have to find your phone, unlock it, enter a phone number with some clunky UI, and then finally make or receive that call or SMS.

This flow can be quite disrupting. Instead of doing all that, keep the Twilio Dev Phone in one of your browser tabs and test your applications to increase your inner dev loop!

There are more scenarios where Dev Phone can help. We'd love to hear what you are using it for!

How to test Twilio applications using the Twilio Dev Phone

Provision Twilio SMS and Voice applications

Before you can test a Twilio application with the Dev Phone, you’ll need to have one up and running.

If you already do, you can skip this section.

Alternatively, instead of deploying your own Twilio apps, you can text and call this phone number we provisioned for demo purposes: +19032962250. You'll only be able to reach the phone number from an upgraded Twilio account, as trial accounts can only communicate with Verified Caller IDs.

You can find a lot of samples on Twilio CodeExchange, but to deploy Twilio apps in an instant, you can filter them down to samples with "Quick Deploy", like the Voice Auto-response and the SMS Auto-response sample.

First, make sure you have a Twilio Account and a Twilio Phone Number. If you register here, you'll receive $10 in Twilio credit when you upgrade to a paid account! Follow these instructions to buy a Twilio Phone Number if you haven't already.

Next, open the Voice Auto-response sample in a new browser tab, select your Twilio Phone Number, and deploy the application. Now follow the same steps for the SMS Auto-response sample.

Congratulations, you now have two Twilio applications, one that will respond when you call or text your Twilio Phone Number! 🎉

Install the Twilio Dev Phone

Before you can use the Twilio Dev Phone, you'll need to acquire another Twilio Phone Number, install Twilio CLI, and install the Twilio Dev Phone plugin.

You can't buy two separate phone numbers on a trial account, so if you're using a trial account, you'll need to upgrade your account.

Buy another Twilio Phone Number, which will be used by the Dev Phone to make and receive calls and text messages.

Next, follow these instructions to install the Twilio CLI on your machine.

Then log in to your account using the following command:

twilio login

Finally, install the Twilio Dev Phone plugin using this command:

twilio plugins:install @twilio-labs/plugin-dev-phone

Great, you're ready to use the Twilio Dev Phone. Start the Dev Phone with the following command:

twilio dev-phone

A new tab in your browser should open showing the Dev Phone and your terminal output should look something like this:

Hello 👋 I'm your dev-phone and my name is dev-phone-600487

✅ I'm using your profile API key.

💻 Creating a new conversation...
✅ I'm using the conversation CHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx from service ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

💻 Creating a new sync list for call history...
✅ I'm using the sync service ISxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

💻 Deploying a Functions Service to handle incoming calls and SMS...
✅ I'm using the Serverless Service ZSxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

💻 Creating a new TwiML App to allow voice calls from your browser...
✅ I'm using the TwiML App APxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

🚀 Your local webserver is listening on port 3001
🌐 Opening http://localhost:3001/ your browser
▶️ Use ctrl-c to stop your dev-phone

As you can see, the Twilio Dev Phone is using a lot of Twilio services like Conversations, Sync, Functions , and TwiML apps so you can make and receive phone calls from the browser in real time.

All these services are created when you start the Twilio Dev Phone, and when you stop it (by pressing ctrl + c), the Twilio Dev Phone will delete them again for you.

Head over to the Dev Phone tab on your browser:

Choose your Twilio Phone Number and click " Use this phone number".

You will see a warning if your phone number is already configured to respond to phone calls or text messages using a webhook, Function, Flow, TwiML app, or something else. The Twilio Dev Phone will overwrite these settings if proceed with that phone number.

You now have a virtual phone on your computer. 🎉

Send Outbound Calls and SMS using the Twilio Dev Phone

Start testing by entering your application’s phone number in the Destination Number field.

Then, enter a message into the Message field and click Send. Your application will respond with its configured response to inbound SMS (e.g., "Hello World" in this screenshot.)

Finally, to test out the voice capabilities of your application, click the Call button. You should also hear the response you’ve configured (e.g., "Hello World".)

You just tested the incoming message and voice call functionality, however, don't forget that your Dev Phone can also receive inbound communications. Go ahead and give your Dev Phone Number a call or text it with your application. You can find this number in the top right corner for your convenience.

Next steps

You've learned how to set up and use the Twilio Dev Phone to test your Twilio applications. The Twilio Dev Phone is an open-source project on GitHub, so if you're curious, go and read the code, also issues and pull requests are welcome!

Congratulations on making it till the end 🎉

We hope you find this tool helpful and we can't wait to see what you build!

Provide default configuration to your .NET applications

Niels Swimburger.NET 🍔 — Mon, 23 May 2022 00:00:00 +0000

This blog post was written for Twilio and originally published at the Twilio blog.

In a previous post I shared how you can better configure your .NET applications for Twilio and SendGrid using the Microsoft.Extensions.Configuration APIs. In this tutorial, I'll build upon the techniques from those tutorials and you'll learn how to store default options in one section of your configuration and override them with specific options from another section. Let me clarify using an example. Applications often send different types of emails, like welcome emails, password reset emails, offer emails, etc. Depending on the type of email, you may want to send them from a different email address. For most emails, you may be using something like 'no-reply@yourdomain.tld', but for offer emails, the replies to the email could be of value. So instead of using the same no-reply address, you could use an email address that will be routed to a sales person and maybe automatically integrates with a Customer Relationship Management (CRM) system.

In this example, you'd want to store 'no-reply@yourdomain.tld' as the default reply address, but for offer-emails, you want to use another email address, for example, 'offers@yourdomain.tld'.

Prerequisites

To follow along, I recommend having

Some experience with C# and .NET
An OS that supports .NET (Windows/macOS/Linux)
Git CLI
.NET 6 SDK (older or newer should work too)
A code editor or IDE (I recommend VS Code with the C# plugin, Visual Studio, or JetBrains Rider)

You can find the source code for this tutorial on GitHub. Use it as a reference if you run into any issues, or submit an issue if you need assistance.

Getting started

You can apply these concepts to any scenario, but let's continue using the email scenario throughout this tutorial.

Run the following commands to clone the tutorial project to your machine using git and navigate into the project:

git clone https://github.com/Swimburger/DotNetDefaultConfiguration.git --branch start
cd DotNetDefaultConfiguration

The git repository you cloned contains a .NET 6 console application that already contains some JSON configuration and code to load the configuration.

Here's what the appsettings.json file looks like:

{
  "Emails": {
    "Welcome": {
      "FromEmail": "no-reply@yourdomain.tld",
      "FromName": "Your App Name",
      "ToEmail": "jon@doe.com",
      "ToName": "Jon Doe",
      "Subject": "Welcome to our service!",
      "Body": "Thank you for signing up!"
    },
    "PasswordReset": {
      "FromEmail": "no-reply@yourdomain.tld",
      "FromName": "Your App Name",
      "ToEmail": "jon@doe.com",
      "ToName": "Jon Doe",
      "Subject": "Reset your password",
      "Body": "Click the link below to reset your password."
    },
    "Offer": {
      "FromEmail": "offers@yourdomain.tld",
      "FromName": "Jane",
      "ToEmail": "jon@doe.com",
      "ToName": "Jon Doe",
      "Subject": "Don't miss this offer!",
      "Body": "We have an amazing offer for you!"
    }
  }
}

Here's what the Program.cs file looks like:

using Microsoft.Extensions.Configuration;

IConfiguration config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .Build();

EmailOptions GetEmailOptions(string emailSectionName)
{
    var emailOptions = new EmailOptions();

    var emailsSection = config.GetSection("Emails");
    var emailSection = emailsSection.GetSection(emailSectionName);

    emailOptions.FromEmail = emailSection["FromEmail"];
    emailOptions.FromName = emailSection["FromName"];
    emailOptions.ToEmail = emailSection["ToEmail"];
    emailOptions.ToName = emailSection["ToName"];
    emailOptions.Subject = emailSection["Subject"];
    emailOptions.Body = emailSection["Body"];

    return emailOptions;
}

void LogEmailOptions(EmailOptions emailOptions)
{
    Console.WriteLine(@"Logging Email Option:
    FromEmail: {0}
    FromName: {1}
    ToEmail: {2}
    ToName: {3}
    Subject: {4}
    Body: {5}", 
        emailOptions.FromEmail, 
        emailOptions.FromName, 
        emailOptions.ToEmail, 
        emailOptions.ToName, 
        emailOptions.Subject, 
        emailOptions.Body
    );
}

var welcomeEmail = GetEmailOptions("Welcome");
LogEmailOptions(welcomeEmail);

var passwordResetEmail = GetEmailOptions("PasswordReset");
LogEmailOptions(passwordResetEmail);

var offerEmail = GetEmailOptions("Offer");
LogEmailOptions(offerEmail);

public class EmailOptions
{
    public string FromEmail { get; set; }
    public string FromName { get; set; }
    public string ToEmail { get; set; }
    public string ToName { get; set; }
    public string Subject { get; set; }
    public string Body { get; set; }
}

The code builds configuration using only JSON as a source and then the GetEmailOptions local function is used to fetch the configuration and create an instance of EmailOptions for the welcome-email, password-reset-email, and offer-email. You would probably dynamically generate the body of the emails and dynamically fetch the recipient email address in a real application, but this will work fine for the purpose of this tutorial.

After each EmailOptions object is created for each email section, the configuration is logged via the LogEmailOptions local function, so you can see the result of this code.

You may notice that there's a lot of redundancy in the JSON, which is why you'll introduce a defaults section in the next part of this tutorial.

Run the project using the .NET CLI:

dotnet run
# Output:
# Logging Email Option:
# FromEmail: no-reply@yourdomain.tld
# FromName: Your App Name
# ToEmail: jon@doe.com
# ToName: Jon Doe
# Subject: Welcome to our service!
# Body: Thank you for signing up!
# Logging Email Option:
# FromEmail: no-reply@yourdomain.tld
# FromName: Your App Name
# ToEmail: jon@doe.com
# ToName: Jon Doe
# Subject: Reset your password
# Body: Click the link below to reset your password.
# Logging Email Option:
# FromEmail: offers@yourdomain.tld
# FromName: Jane
# ToEmail: jon@doe.com
# ToName: Jon Doe
# Subject: Don't miss this offer!
# Body: We have an amazing offer for you!

You can see that the configuration is pulled from the JSON file and then written to the console.

Add a defaults section for redundant configuration elements

You can add a Defaults section to remove the redundant configuration elements. Open appsettings.json and in front of the Welcome section, add a Defaults section:

{
  "Emails": {
    "Defaults": {
      "FromEmail": "no-reply@yourdomain.tld",
      "FromName": "Your App Name",
      "ToEmail": "jon@doe.com",
      "ToName": "Jon Doe"
    },
    "Welcome": {
      "Subject": "Welcome to our service!",
      "Body": "Thank you for signing up!"
    },
    "PasswordReset": {
      "Subject": "Reset your password",
      "Body": "Click the link below to reset your password."
    },
    "Offer": {
      "FromEmail": "offers@yourdomain.tld",
      "FromName": "Jane",
      "Subject": "Don't miss this offer!",
      "Body": "We have an amazing offer for you!"
    }
  }
}

As shown above, also remove the redundant FromEmail, FromName, ToEmail, and ToName properties from the Welcome and PasswordReset section. However, only remove the redundant ToEmail and ToName properties from the Offer section and leave the FormEmail and FromName properties be.

Now, update the code in the Program.cs file so that the configuration is retrieved from the specific email section, but if null (??), then retrieve it from the Defaults section.

EmailOptions GetEmailOptions(string emailSectionName)
{
    var emailOptions = new EmailOptions();

    var emailsSection = config.GetSection("Emails");
    var defaultsSections = emailsSection.GetSection("Defaults");
    var emailSection = emailsSection.GetSection(emailSectionName);

    emailOptions.FromEmail = emailSection["FromEmail"] ?? defaultsSections["FromEmail"];
    emailOptions.FromName = emailSection["FromName"] ?? defaultsSections["FromName"];
    emailOptions.ToEmail = emailSection["ToEmail"] ?? defaultsSections["ToEmail"];
    emailOptions.ToName = emailSection["ToName"] ?? defaultsSections["ToName"];
    emailOptions.Subject = emailSection["Subject"] ?? defaultsSections["Subject"];
    emailOptions.Body = emailSection["Body"] ?? defaultsSections["Body"];

    return emailOptions;
}

?? is the null-coalescing operator which returns the value on the right side if the value on the left side is null. This allows you to succinctly check for null and if null, provide a fallback value.

Run the project again using the .NET CLI:

dotnet run

As you can see, the output has not changed, but now you can set configuration on specific sections and fallback on configuration from the Defaults section.

This code gets the job done, but the same result could be achieved more eloquently by binding configuration sections to strongly-typed objects.

Bind defaults and override defaults using the configuration binder

Instead of retrieving each configuration element individually, you can use the configuration binder to bind configuration sections to strongly-typed objects. There are two methods you can use to bind configuration sections to an instance of EmailOptions: Get() and Bind(object).

To use the Get method, pass in the desired type as a generic type parameter and the Get method create an instance of that type and bind the configuration to the object.

var emailsSection = config.GetSection("Emails");
var emailOptions = emailsSection.GetSection(emailSectionName)
    .Get<EmailOptions>();

To use the Bind method, create an instance of EmailOptions and then pass it as a parameter to the Bind method.

var emailOptions = new EmailOptions();

var emailsSection = config.GetSection("Emails");
emailsSection.GetSection(emailSectionName)
    .Bind(emailOptions);

What's even more interesting is that you can use the Bind method multiple times! So, if you'd like to bind both the defaults and the email specific configuration, you could do that as follows:

var emailOptions = new EmailOptions();

var emailsSection = config.GetSection("Emails");
emailsSection.GetSection("Defaults").Bind(emailOptions);
emailsSection.GetSection(emailSectionName).Bind(emailOptions);

Using this technique, update the GetEmailOptions local function to create an instance of EmailOptions, then bind the Defaults section to it, and then override the defaults by binding the specific section to it:

EmailOptions GetEmailOptions(string emailSectionName)
{
    var emailOptions = new EmailOptions();

    var emailsSection = config.GetSection("Emails");
    emailsSection.GetSection("Defaults").Bind(emailOptions);
    emailsSection.GetSection(emailSectionName).Bind(emailOptions);

    return emailOptions;
}

Hardcoding defaults

In addition to pulling defaults from the configuration, you may also opt to add default values directly into your code. For example, if you're developing a library for others to consume, it would be convenient for some of the configuration elements to have default values.

If you're pulling individual configuration elements, you could add default values like this:

emailOptions.FromEmail = emailSection["FromEmail"]
    ?? defaultsSections["FromEmail"]
    ?? "no-reply@yourdomain.tld";

Maybe it doesn't make sense to hardcode a default value, but the configuration element is required, so you want to throw an exception if the configuration element is null. In that case, you can also use the null-coalescing operator to throw an exception inline like this:

emailOptions.FromEmail = emailSection["FromEmail"]
    ?? throw new Exception($"Emails:{emailSectionName}:FromEmail has to be configured");

However, if you're using the configuration binder, you don't need to use the null-coalescing operator, and you can instead specify the default values in the object initializer like this:

var emailOptions = new EmailOptions
{
    FromEmail = "no-reply@yourdomain.tld",
    ...
};

var emailsSection = config.GetSection("Emails");
emailsSection.GetSection("Defaults").Bind(emailOptions);
emailsSection.GetSection(emailSectionName).Bind(emailOptions);

Alternatively, you could specify default values in the class definition itself like this:

public class EmailOptions
{
    public string FromEmail { get; set; } = "no-reply@yourdomain.tld";
    public string FromName { get; set; }
    public string ToEmail { get; set; }
    public string ToName { get; set; }
    public string Subject { get; set; }
    public string Body { get; set; }
}

Next steps

You've learned how to provide default configuration values through code and through a dedicated Defaults configuration section. If you haven't already, I recommend learning about more configuration techniques in a tutorial applied to Twilio configuration, or applied to SendGrid configuration.

If you found this useful, let me know and share what you're working on. I can't wait to see what you build!

Send Email and SMS from Google Forms using Zapier, SendGrid, and Twilio

Niels Swimburger.NET 🍔 — Wed, 18 May 2022 00:00:00 +0000

This blog post was written for Twilio and originally published at the Twilio blog.

Forms are one of the fundamental building blocks of the web. Almost all websites use forms to get feedback from users and to gather leads. Many of these forms integrate directly with a Customer Relationship Management (CRM) system, while others forward the form data directly to an email inbox.

If you're building a form using a web framework, you can quickly integrate SendGrid's Email API or one of the SendGrid libraries to forward the data to an email inbox. However, sometimes there's no time to build a fully fledged form yourself, or the form's purpose is for a single short-lived campaign. In that case, you could use an off-the-shelf form product like Google Forms to get the job done quickly with minimal investment. You don't even have to sacrifice the form integrations, because with Zapier's workflow automation, you can integrate Google Forms with tons of products including SendGrid to send emails and Twilio Messaging to send SMS.

In this tutorial, you'll learn how to forward form submission data via email and send a notification via SMS using Google Forms, Zapier, and Twilio. This is a very common scenario on the web, but with these tools you don't even need to write any code to make it happen!

Zapier workflow automation with Google Forms, SendGrid, and Twilio SMS

If you're looking to build a form for users to signup for your newsletter, you can use SendGrid’s Signup Forms to build and manage your email contact list for newsletters.

Prerequisites

You will need these things to follow along:

A free or paid SendGrid account. Sign up here to send up to 100 emails per day completely free of charge.
A free or paid Twilio account (If you register here, you'll receive $10 in Twilio credit when you upgrade to a paid account!)
A free Zapier account, or even better, a paid or Zapier trial account (more on that later)
A Google account

Create a Google Form

You can skip this step if you already set up a Google Form. If not, head over to forms.new which will automatically create a blank new form in Google Forms for you. Give your new form a name and use the interface to build your form out until you're happy with the result.

For example, here's a form that will contact me, so I added a Name, Email Address, and Question field to the form.

Click on the Responses tab, click the 3 dotted icon to open the overflow menu, and click Select response destination.

A modal will appear where you can decide which Google Sheet (spreadsheet) will be used to store the form submissions in. Select the Create a new spreadsheet option and, if desired, change the name of the spreadsheet and then click Create.

This spreadsheet will be used to store responses in rows whenever the form gets filled out and submitted.

Later, you will configure Zapier to watch this spreadsheet and run your automation workflow whenever a new row appears on the spreadsheet.

Configure your SendGrid account to send emails

In SendGrid, you'll need to configure two things before you can send emails: First, you’ll need to set up Sender Authentication. This will verify that you own the email address or domain that you will send emails from. Second, you’ll need to create a SendGrid API Key with permission to send emails.

Sender Authentication

To quickly get started, you will use Single Sender Verification for this tutorial. This verifies that you own the email address that the application will send emails from. Single Sender Verification is great for testing purposes , but it is not recommended for production.

Twilio recommends Domain Authentication for production environments. An authenticated domain proves to email providers that you own the domain, and removes the "via sendgrid.net" text that inbox providers would otherwise append to your from address.

To set up Single Sender Verification, click the Settings tab in the left menu. Once the settings tab opens, click Sender Authentication.

Then, click Get Started under the Single Sender Verification section.

This opens a form in the right-side panel. Fill out the form with your information and email address.

Click Create after filling out the form. Another panel will appear on the right, asking you to confirm your email address in your email inbox.

Go to your personal email inbox, open the email from SendGrid, and click Verify Single Sender.

Your email address has been verified. You can now use it to send emails!

Create a SendGrid API key to send emails

Back on the SendGrid website, click API Keys under the Settings tab , then click Create API Key in the top right-hand corner. This opens another form in the right-side panel.

Give your API Key a useful name. You can assign different permissions to the API Key. For optimal security, you should only give the minimum amount of permissions that you need.

Next, click Restricted Access.

Scroll down to the Mail Send accordion item and click on it to reveal the permissions underneath. Drag the slider to the right for the Mail Send permission.

Scroll to the bottom of the form and click Create & View. The API key will now be displayed on your screen.

You will not be able to retrieve the API key again once you leave this screen, so make sure you copy the API Key somewhere safe.

With the sender verified and the API Key created, you’ll now be able to send emails from Zapier's workflow automation.

Get Your Twilio Configuration

To send text messages from Zapier, you'll first need to buy a Twilio Phone Number. If you're using a trial account, the cost for the phone number will be applied to the complimentary trial credit. If you don't already have a phone number, go and buy a phone number via the Twilio Console.

Next, you'll need some configuration elements from Twilio to send text messages from Zapier. Back in the Twilio Console, take note of your Twilio Account SID and Auth Token located at the bottom left of the page.

After all these steps you should have:

The name of the spreadsheet that hosts your Google Form data
The email address of your Verified Sender on SendGrid.
The API Key from SendGrid to send emails
The Account SID and Auth Token from Twilio to send SMS

Fantastic! Time to create the automation with Zapier.

Create workflow automation with Zapier

Head over to the Zapier dashboard and click on the Create Zap button on the top left.

In Zapier's words: "A Zap is an automated workflow that connects your apps and services together". After creating the Zap, change the name of the Zap to something meaningful. This can be done by clicking on the pen icon next to Untitled Zap in the top left corner of the page.

Configure the Google Forms Trigger to receive the form submission

Every Zap needs to have a Trigger; a trigger is an event that will start the workflow. In the App Event search bar, enter " Google Forms" and then click on the "Google Forms" entry.

In the Event dropdown, select the " New Response in Spreadsheet" option, and click Continue.

Click on Sign in, authenticate with Google, and share the necessary permissions with Zapier. Once authenticated, click Continue.

Now, click on the Spreadsheet dropdown and select the spreadsheet that you created earlier for your Google Form.

A single spreadsheet can contain multiple worksheets, so Zapier will also prompt you to select the Worksheet of which there is only one in this case. Select the Worksheet and then click Continue.

You may be asked to test the trigger; if so, click Skip test since testing will be done at the end of the tutorial.

Configure the SendGrid Action to send an email

After the Trigger, there's already an empty action added to your Zap. Click on the action and search for the SendGrid app. For the Event dropdown, select " Send Email", and then click Continue.

Now you have to help Zapier authenticate to your SendGrid account. Click on the Sign In button and a window will pop up asking you for the " Mail API Key", enter the SendGrid API Key you took note of earlier and click " Yes, Continue".

Now that Zapier has your SendGrid API Key, click Continue and configure the action.

As you can see in the screenshot below, I configured the fields as follows:

To: The email address of the person that will review the form submission. You can use your own email address for this.
From : The Verified Sender email address that you configured earlier in SendGrid.
- From Name : A name that uniquely identifies the form. This is added using the "Insert Data …" popover that lets you use the data from a trigger or a previous action. In this case, the data is pulled from the Google Form trigger.- Reply To : This is optional, but if your form is like mine and has an input for the user's email address, this field can be used to reply directly to the form submitter through the email instead of replying to the From email address.
- Subject : The title that will be shown on the subject line of the email.
- HTML : The HTML will be the content of your email. You can also use the Text field if you don't want to use HTML.

Here's the HTML I used for my email:

<p>Someone submitted the Contact Niels Form:</p>
<ul>
<li>Name: [FORM SUBMISSION NAME]</li>
<li>Email Address: [FORM SUBMISSION EMAIL ADDRESS]</li>
<li>Question: <br />
[FORM SUBMISSION QUESTION]
</li>
</ul>

If you have a similar form as mine, you'll have to replace the [FORM SUBMISSION …] placeholders with the data from the Google Forms trigger.

Click Continue. The last step is to Test action which you can skip by clicking Skip test since you will be coming back at the end to it to test it out.

Configure the Twilio Action to send an SMS

The next action you will create is to send an SMS notification when the form has been submitted.

This will require you to add a second action to your Zap, which is only possible for paid Zapier plans. If you don't have a paid Zapier plan or trial, you can only create Zaps with a single action. However, as a workaround, you could create a second Zap with the same Google Forms trigger and the Twilio action for sending SMS.

Click on the plus-icon below the SendGrid action you just created. Look for "Twilio" in the App Event search box and click on the Twilio option.

Next, select " Send SMS" in the Event dropdown, and click Continue.

Click on Sign in to share the Twilio credentials with Zapier. Enter the Twilio Account SID and Auth Token you took note of earlier and click " Yes, Continue".

Back in your Zap, click Continue.

Select your Twilio Phone Number from the "From Number" dropdown. Next, enter your phone number into the " To Number" field, and enter some text into the Message field.

Click Continue , then Skip test and finally Publish Zap. You’ll be asked to confirm to turn on your Zap; click Publish & Turn On.

Testing your Zap

While creating your Zap, you may have noticed that you can test the trigger and actions from Zapier's interface. Go to your trigger and under the " Test trigger" section, click on the " Test trigger" button.

If someone already submitted the form before, Zapier will grab the form submission data and use it to test your Zap. Be mindful tho, this data may be a real submission, not just your own test data. Now head over to each of your actions and test them out as well.

To do an end-to-end test, go to your Google Form and submit it and wait until you get your email and text message.

Next steps

You just created one of the most commonly requested form flows without writing any code; well apart from some HTML that is. However, there are many more triggers and actions you could build automations with, and if you want to build and explore more communication applications, check out our no-code application builder, Twilio Studio. For example, learn how to build an Interactive Voice Response (IVR) application with Twilio Studio so you can take phone calls to help out customers without having a call representative.

How to better configure C# and .NET applications for SendGrid

Niels Swimburger.NET 🍔 — Thu, 12 May 2022 00:00:00 +0000

This blog post was written for Twilio and originally published at the Twilio blog.

There are a hundred different ways to provide configuration to your applications. For almost any programming language, you can use environment variables and .env files, but configuration can also be stored in other file formats like JSON, YAML, TOML, XML, INI, and the list keeps on going. However, in some scenarios configuration isn't pulled from files, but instead is pulled from Azure Key Vault, HashiCorp Vault, or a similar vault service. It is rare that your configuration will come from a single source. Luckily, there are APIs in .NET that can help you grab configuration from multiple sources and merge them together.

In this tutorial, you'll start with an application that sends emails using Twilio SendGrid, where the configuration is fetched directly from the environment variables. You'll then refactor the app to

fetch configuration from multiple sources, specifically, JSON files, user-secrets, environment variables, and command-line arguments
bind the configuration to strongly-typed objects
inject configuration using dependency injection following the options pattern

Prerequisites

You will need these things to follow along with this tutorial:

An OS that supports .NET (Windows/macOS/Linux)
Git CLI
.NET 6 SDK
A code editor or IDE (I recommend VS Code with the C# plugin, Visual Studio, or JetBrains Rider)
A free or paid Twilio account (If you register here, you'll receive $10 in Twilio credit when you upgrade to a paid account!)
A Twilio SendGrid account. Sign up here to send up to 100 emails per day completely free of charge.

You can find the source code for this tutorial on GitHub. Use it if you run into any issues, or submit an issue if you run into problems.

Configure your SendGrid account to send emails

There are two things you need to configure before you can send emails. First, you’ll need to set up Sender Authentication. This will verify that you own the email address or domain that you will send emails from. Second, you’ll need to create a SendGrid API Key with permission to send emails.

Sender Authentication

To set up Single Sender Verification, click the Settings tab in the left menu. Once the settings tab opens, click Sender Authentication.

Then, click Get Started under the Single Sender Verification section.

This opens a form in the right-side panel. Fill out the form with your information and email address.

Click Create after filling out the form. Another panel will appear on the right, asking you to confirm your email address in your email inbox.Go to your personal email inbox, open the email from SendGrid, and click Verify Single Sender.

Your email address has been verified. You can now use it to send emails!

Create a SendGrid API Key to send emails

Back on the SendGrid website, click API Keys under the Settings tab , then click Create API Key in the top right-hand corner. This opens another form in the right-side panel.

Give your API Key a meaningful name. You can assign different permissions to the API Key. For optimal security, you should only give the minimum amount of permissions that you need.

Next, click Restricted Access.

Scroll down to the Mail Send accordion item and click on it to reveal the permissions underneath. Drag the slider to the right for the Mail Send permission.

Scroll to the bottom of the form and click Create & View. The API key will now be displayed on your screen.

You will not be able to retrieve the API key again once you leave this screen, so make sure you copy the API Key somewhere safe.

With the sender verified and the API Key created, you’re ready to write some code!

For any of the upcoming commands and code, replace the following placeholders like this:

Replace [SENDGRID_API_KEY] with the API Key you just took note of
Replace [FROM_EMAIL_ADDRESS] and [FROM_NAME] with the email address you verified earlier and the name you want your recipients to see.
Replace [TO_EMAIL_ADDRESS] and [TO_NAME] with the email address and name of the desired recipient of the email.

Get configuration directly from environment variables

To get the project up and running quickly on your machine, open your preferred shell, and use the following git command to clone the source code:

git clone https://github.com/Swimburger/SendGridOptionsPattern.git --branch Step1

Then navigate into the SendGridOptionsPattern folder using cd SendGridOptionsPattern. This project is a console application with only one C# file, Program.cs, which has the following code:

using SendGrid;
using SendGrid.Helpers.Mail;

var apiKey = Environment.GetEnvironmentVariable("SendGridApiKey");
var fromEmailAddress = Environment.GetEnvironmentVariable("FromEmailAddress");
var fromName = Environment.GetEnvironmentVariable("FromName");
var toEmailAddress = Environment.GetEnvironmentVariable("ToEmailAddress");
var toName = Environment.GetEnvironmentVariable("ToName");

var client = new SendGridClient(apiKey);
var message = new SendGridMessage
{
    From = new EmailAddress(fromEmailAddress, fromName),
    Subject = "Sending with Twilio SendGrid is Fun",
    PlainTextContent = "and easy to do anywhere, especially with C#"
};
message.AddTo(new EmailAddress(toEmailAddress, toName));
var response = await client.SendEmailAsync(message);

// A success status code means SendGrid received the email request and will process it.
// Errors can still occur when SendGrid tries to send the email. 
// If email is not received, use this URL to debug: https://app.sendgrid.com/email_activity 
Console.WriteLine(response.IsSuccessStatusCode ? "Email queued successfully!" : "Something went wrong!");

The application pulls the SendGrid API Key, as well as the email address and name for the sender and recipient from the environment variables. The code then creates a new SendGridClient with the API key, creates an email message using SendGridMessage, and then sends the email.

The application uses the SendGrid library for C# and .NET to authenticate with and send emails through the SendGrid API. The SendGrid NuGet package has been added into the project as part of the source code you cloned. You can find this dependency in the csproj-file.

Before you can run this application, you'll need to configure the environment variables that the project depends on. Back in your shell, set these environment variables using the following commands.

If you're using Bash or a similar shell:

export SendGridApiKey=[SENDGRID_API_KEY]
export FromEmailAddress=[FROM_EMAIL_ADDRESS]
export FromName="[FROM_NAME]"
export ToEmailAddress=[TO_EMAIL_ADDRESS]
export ToName="[TO_NAME]"

If you're using PowerShell:

$Env:SendGridApiKey = "[SENDGRID_API_KEY]"
$Env:FromEmailAddress = "[FROM_EMAIL_ADDRESS]"
$Env:FromName = "[FROM_NAME]"
$Env:ToEmailAddress = "TO_EMAIL_ADDRESS]"
$Env:ToName = "[TO_NAME]"

If you're using CMD:

set "SendGridApiKey=[SENDGRID_API_KEY]"
set "FromEmailAddress=[FROM_EMAIL_ADDRESS]"
set "FromName=[FROM_NAME]"
set "ToEmailAddress=[TO_EMAIL_ADDRESS]"
set "ToName=[TO_NAME]"

Once the environment variables have been set, you can run the project using the following .NET CLI command:

dotnet run

The application will send an email from your verified email address to the recipient.

When the SendGrid API responds with a successful HTTP status code, that does not necessarily mean that the email was successfully received by the recipient. It does however mean that the SendGrid API has accepted your request and will send the email. If the recipient does not receive the email, you can use the Email Activity Feed to find out why.

Pulling the configuration from the environment variables works great, but instead of using environment variables, you could've simply hardcoded all the configuration, right?

Many of these configuration elements, especially the API Key, are sensitive secrets which you do not want to share with others. By pulling them from external configuration like the environment variables, you ensure that you don't accidentally check them into your public source code for everyone to see. And whenever someone else wants to run the same code, they can configure their own API Key configuration into the environment variables and run it.

This is why in SendGrid samples, we will always use environment variables. Although it's an extra step compared to hard coding configuration, it is the fastest way to get you up and running with SendGrid without compromising your API Key by accident.

However, in .NET, there's a better way to retrieve external configuration, using the ConfigurationBuilder.

Build your Configuration with the .NET configuration builder

There are many ways to configure .NET applications, and typically the configuration is composed from multiple sources. ASP.NET Core originally introduced APIs to easily load configuration from a bunch of different sources using configuration providers and merge them all together with the ConfigurationBuilder. These APIs were moved into the Microsoft.Extensions.Hosting NuGet package so it could be used in any .NET application.

Not only can you use the new Configuration APIs on .NET (Core) — you can even use them on .NET Framework. .NET Framework has its own configuration APIs, but they are less intuitive and dated compared to the new Configuration APIs.

Back in your shell, run the following .NET CLI commands to add NuGet packages for the configuration extensions and some of the configuration providers:

dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.Configuration.CommandLine
dotnet add package Microsoft.Extensions.Configuration.EnvironmentVariables
dotnet add package Microsoft.Extensions.Configuration.UserSecrets

The Microsoft.Extensions.Configuration package contains the main APIs for building configuration and also the JSON configuration provider.
The Microsoft.Extensions.Configuration.CommandLine package adds a configuration provider that builds configuration from command-line arguments.
The Microsoft.Extensions.Configuration.EnvironmentVariables package adds a configuration provider that builds configuration from environment variables.
The Microsoft.Extensions.Configuration.UserSecrets package adds a configuration provider that builds configuration from the Secret Manager.

To start using the configuration APIs, update the Program.cs file with the following code:

using System.Reflection;
using Microsoft.Extensions.Configuration;
using SendGrid;
using SendGrid.Helpers.Mail;

IConfiguration config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json", optional: true, reloadOnChange: false)
    .AddUserSecrets(Assembly.GetExecutingAssembly(), optional: true, reloadOnChange: false)
    .AddEnvironmentVariables()
    .AddCommandLine(args)
    .Build();

var apiKey = config["SendGrid:ApiKey"];
var fromEmailAddress = config["Email:From:Email"];
var fromName = config["Email:From:Name"];
var toEmailAddress = config["Email:To:Email"];
var toName = config["Email:To:Name"];
var emailSubject = config["Email:Subject"];
var emailBody = config["Email:Body"];

var client = new SendGridClient(apiKey);
var message = new SendGridMessage
{
    From = new EmailAddress(fromEmailAddress, fromName),
    Subject = emailSubject,
    PlainTextContent = emailBody
};
message.AddTo(new EmailAddress(toEmailAddress, toName));
var response = await client.SendEmailAsync(message);

// A success status code means SendGrid received the email request and will process it.
// Errors can still occur when SendGrid tries to send the email. 
// If email is not received, use this URL to debug: https://app.sendgrid.com/email_activity 
Console.WriteLine(response.IsSuccessStatusCode ? "Email queued successfully!" : "Something went wrong!");

The resulting app is the same as before but is now loading configuration from multiple sources instead of directly from the environment variables. The ConfigurationBuilder is a class that uses the builder pattern so you can chain together multiple configuration providers using the Add… extension methods. When configuration elements coming from different providers have the same key, the configuration added later to the chain will overwrite the configuration added earlier in the chain. This means that the order in which you add configuration providers matters! In this case:

User Secrets overwrites configuration from JSON
Environment Variables overwrites configuration from User Secrets and JSON
Command-Line Arguments overwrites configuration from User Secrets, JSON, and Environment Variables.

The optional parameter specifies whether or not the application should throw an exception if the underlying source is missing. The reloadOnChange parameter specifies whether or not to update the configuration when the underlying source changes. For example, if there's an issue in your production application, but for performance reasons, the logging level is set to Warning in appsettings.json, you can change the logging level to Debug. Once you save the file, the application begins writing logs from the Debug level and up, without having to restart your application!

After the configuration is built, the app will grab the configuration elements from the configuration, but notice how the configuration keys now use two different prefixes: SendGrid: and Email:.

You can organize your configuration into hierarchical sections by adding colons : as separators. So in this case, ApiKey is part of the SendGrid section, and all the other configuration is part of the Email section. You can also nest sections as shown in the Email section. The Email section contains child sections From and To which hold on to the email address and name of the sender and recipient. There are a lot of different ways you could structure your configuration, but how you organize your configuration all depends on your needs.

Now that the application loads configuration from multiple sources, in which source should you store configuration? It depends on the configuration, your use-case, and personal preference:

Use JSON for configuration that does not contain secrets or other sensitive information.
Use User Secrets only for local development to configure secrets and other sensitive information.
Use Environment Variables for environment specific configuration including secrets or other sensitive information. However, User Secrets is preferred for local development. Environment Variables are a powerful source of configuration because all operating systems, container technology, and cloud infrastructure supports them.
Use Command-Line Arguments to configure execution specific settings.

Create a new file called appsettings.json and add the following JSON:

{
  "Email": {
    "From": {
      "Email": "[FROM_EMAIL_ADDRESS]",
      "Name": "[FROM_NAME]"
    },
    "Subject": "Ahoy from JSON!",
    "Body": "Thank you for signing up to our website. See you around!"
  }
}

The appsettings.json file will provide the FromEmailAddress, FromName, Subject, and Body configuration, even though it would also make sense to pass this configuration in as command-line arguments.

By default, in a console app, the appsettings.json file will not be copied to the output of the project. As a result the configuration provider will not find the underlying source, which means the configuration in your JSON will not be loaded. To make sure the the appsettings.json file is copied to the output, add a Content node to the csproj-file as shown below:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>...</PropertyGroup>
  <ItemGroup>...</ItemGroup>

  <ItemGroup>
    <Content Include="appsettings.json" CopyToOutputDirectory="Always" />
  </ItemGroup>
</Project>

To start using the Secret Manager, you first need to initialize it for your project using the following command:

dotnet user-secrets init

Now you can set the SendGrid:ApiKey configuration like this:

dotnet user-secrets set SendGrid:ApiKey [SENDGRID_API_KEY]

It's likely you would configure the API Key as an environment variable in other environments, but since you're running this locally, the Secret Manager is preferred. So, in this case, you don't need to configure any environment variables.

The application now has configuration for who the email will be sent from, but not who the email will be sent to. Instead of configuring it using one of the previous sources, run the project using the .NET CLI and pass it in as a command-line argument:

dotnet run --Email:To:Email [TO_EMAIL_ADDRESS] --Email:To:Name "[TO_NAME]"

Just like before, the recipient will receive an email, but now the subject will be "Ahoy from JSON!".

Run the command again, but overwrite the Email:Subject configuration using a command-line argument:

dotnet run --Email:To:Email [TO_EMAIL_ADDRESS] --Email:To:Name "[TO_NAME]" --Email:Subject "Ahoy from the CLI"

Now the recipient will receive an email with the subject "Ahoy from the CLI".

The end result may be the same, but your application is a lot more flexible now because it can be configured in many different ways. However, these are not the only configuration providers. Microsoft has 5 more configuration providers, and if those don't meet your needs, you can also develop your own provider or use someone else's.

Some operating systems and shells may not allow you to use colons. In that case you can use a double underscore __ as a separator, and .NET will replace it with the colon for you.

Bind configuration to strongly-typed objects

You just learned how to use the configuration builder to get configuration from multiple sources, but the amount of configuration can quickly get out of hand. A more manageable solution to this is to bind your configuration to strongly-typed objects.

To starting binding configuration, add the Microsoft.Extensions.Configuration.Binder NuGet package with the following command:

dotnet add package Microsoft.Extensions.Configuration.Binder

Update the Program.cs file with the code below:

using System.Reflection;
using Microsoft.Extensions.Configuration;
using SendGrid;
using SendGrid.Helpers.Mail;

IConfiguration config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json", optional: true, reloadOnChange: false)
    .AddUserSecrets(Assembly.GetExecutingAssembly(), optional: true, reloadOnChange: false)
    .AddEnvironmentVariables()
    .AddCommandLine(args)
    .Build();

var apiKey = config["SendGrid:ApiKey"];

var emailOptions = config.GetSection("Email").Get<EmailOptions>();

var client = new SendGridClient(apiKey);
var message = new SendGridMessage
{
    From = emailOptions.From,
    Subject = emailOptions.Subject,
    PlainTextContent = emailOptions.Body
};
message.AddTo(emailOptions.To);
var response = await client.SendEmailAsync(message);

// A success status code means SendGrid received the email request and will process it.
// Errors can still occur when SendGrid tries to send the email. 
// If email is not received, use this URL to debug: https://app.sendgrid.com/email_activity 
Console.WriteLine(response.IsSuccessStatusCode ? "Email queued successfully!" : "Something went wrong!");

public class EmailOptions
{
    public EmailAddress From { get; set; }
    public EmailAddress To { get; set; }
    public string Subject { get; set; }
    public string Body { get; set; }
}

At the bottom of Program.cs, there is a new class which has properties with names that match your configuration. By matching the name of the properties and the keys of the configuration, you will be able to bind the configuration to instances of said class. You can grab sections from the configuration using config.GetSection("YourSectionName") and then bind the section to strongly-typed objects using .Get<YourClass>(). This way, the Email section is bound to instances of EmailOptions which is then used to send the email as before.

For the EmailOptions class, the From and To properties are defined using the EmailAddress class provided by the SendGrid library. The EmailAddress class contains two properties: Email and Name. Because these properties names match the names of your configuration, even these nested objects will be bound.

If you run the project now, you will continue to get the same result:

dotnet run --Email:To:Email [TO_EMAIL_ADDRESS] --Email:To:Name "[TO_NAME]" --Email:Subject "Ahoy from the CLI"

If reloadOnChange is enabled on the configuration providers, and the configuration changes in the configuration source, the configuration object will be updated, but any strongly-typed object that has already been bound will not be updated accordingly.

Swap configuration builder with the default host builder

If you've used the ASP.NET templates, you may notice that the configuration has already been set up without any ConfigurationBuilder code. That's because ASP.NET templates use the default Web Host which sets up the default configuration, logging, dependency injection, web related functionality, and more.

If you want the same configuration, logging, and dependency injection from the web host builder, but not the web related functionality, you can use the Generic Host instead of the Web Host.

Add the Microsoft.Extensions.Hosting NuGet package using the .NET CLI:

dotnet add package Microsoft.Extensions.Hosting

In Program.cs, Replace the using statements and the ConfigurationBuilder code with the following code:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using SendGrid;
using SendGrid.Helpers.Mail;

using IHost host = Host.CreateDefaultBuilder(args).Build();
var config = host.Services.GetRequiredService<IConfiguration>();

Instead of building the configuration yourself, the project now uses the defaults that come with the Generic Host. The code then retrieves the configuration from the dependency injection container (host.Services), and continues using the configuration object as before.

The default Generic Host will build configuration similarly to how you did it yourself, but there are some differences. You can find an overview of the Generic Host defaults in the Microsoft Documentation.

The default Generic Host builds configuration slightly differently. More specifically, your user secrets will only be loaded if the Environment is configured as Development. There are multiple ways to configure the environment, but for this tutorial, pass in the Environment argument when you run your project, like this:

dotnet run --Environment Development  --Email:To:Email [TO_EMAIL_ADDRESS] --Email:To:Name "[TO_NAME]" --Email:Subject "Ahoy from the CLI"

Get configuration from dependency injection using the options pattern

Now that you're using the Generic Host, you can start using the dependency injection (DI) that comes with it, just like you can on ASP.NET applications.

Replace your existing code in Program.cs with the following code:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Options;
using SendGrid;
using SendGrid.Helpers.Mail;

using IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureServices((context, services) =>
    {
        services.Configure<EmailOptions>(context.Configuration.GetSection("Email"));
        services.AddTransient<EmailSender>();
    })
    .Build();

var config = host.Services.GetRequiredService<IConfiguration>();

var apiKey = config["SendGrid:ApiKey"];
var client = new SendGridClient(apiKey);

var emailSender = host.Services.GetRequiredService<EmailSender>();
await emailSender.SendEmail(client);

public class EmailSender
{
    private readonly EmailOptions emailOptions;

    public EmailSender(IOptions<EmailOptions> emailOptions)
    {
        this.emailOptions = emailOptions.Value;
    }

    public async Task SendEmail(ISendGridClient client)
    {
        var message = new SendGridMessage
        {
            From = emailOptions.From,
            Subject = emailOptions.Subject,
            PlainTextContent = emailOptions.Body
        };
        message.AddTo(emailOptions.To);
        var response = await client.SendEmailAsync(message);

        // A success status code means SendGrid received the email request and will process it.
        // Errors can still occur when SendGrid tries to send the email. 
        // If email is not received, use this URL to debug: https://app.sendgrid.com/email_activity 
        Console.WriteLine(response.IsSuccessStatusCode ? "Email queued successfully!" : "Something went wrong!");
    }
}

public class EmailOptions
{
    public EmailAddress From { get; set; }
    public EmailAddress To { get; set; }
    public string Subject { get; set; }
    public string Body { get; set; }
}

You can use the ConfigureServices method on the host builder and pass in a lambda to add more services to the DI container. In this lambda, the Email configuration section is added as configuration using services.Configure<YourOptions>. As a result, your configuration will be injected wherever DI is supported by adding a parameter of type IOptions<YourOptions> to your constructor or method signature. Microsoft calls this the Options pattern.

In addition to IOptions<T>, there's also IOptionsSnapshot<T>, IOptionsMonitor<T>, and IOptionsFactory<TOptions> which each have different behavior and use-cases. Learn more about the differences between these options interfaces at Microsoft's documentation.

After configuring the options, the program will add the EmailSender class to the CI container. EmailSender is a new class that will be responsible for sending Emails. Now that the DI container has been built, you can retrieve the services from it. So now you have your EmailOptions injected anywhere that supports DI.

Now, the code will retrieve an instance of EmailSender from the DI container, which is used to send an email using the SendEmail method.

When EmailSender is created by the DI container, the container injects an instance of IOptions<EmailOptions> into the constructor of EmailSender. EmailSender grabs the message options using the .Value property and uses it in the SendEmail method to send an email.

Add SendGridClient to the Dependency Injection Container

You've made your application more flexible and configurable, but you can also further integrate SendGrid into your application. The SendGrid SDK for .NET has an extra NuGet package that will add the SendGrid client to the dependency injection container.

Run the following command to add the SendGrid DI package:

dotnet add package SendGrid.Extensions.DependencyInjection

Then update the Program.cs file like this:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Options;
using SendGrid;
using SendGrid.Extensions.DependencyInjection;
using SendGrid.Helpers.Mail;

using IHost host = Host.CreateDefaultBuilder(args)
    .ConfigureServices((context, services) =>
    {
        services.AddSendGrid(options =>
            options.ApiKey = context.Configuration["SendGrid:ApiKey"]
        );
        services.Configure<EmailOptions>(context.Configuration.GetSection("Email"));
        services.AddTransient<EmailSender>();
    })
    .Build();

var emailSender = host.Services.GetRequiredService<EmailSender>();
await emailSender.SendEmail();

public class EmailSender
{
    private readonly ISendGridClient sendGridClient;
    private readonly EmailOptions emailOptions;

    public EmailSender(IOptions<EmailOptions> emailOptions, ISendGridClient sendGridClient)
    {
        this.sendGridClient = sendGridClient;
        this.emailOptions = emailOptions.Value;
    }

    public async Task SendEmail()
    {
        var message = new SendGridMessage
        {
            From = emailOptions.From,
            Subject = emailOptions.Subject,
            PlainTextContent = emailOptions.Body
        };
        message.AddTo(emailOptions.To);
        var response = await sendGridClient.SendEmailAsync(message);

        // A success status code means SendGrid received the email request and will process it.
        // Errors can still occur when SendGrid tries to send the email. 
        // If email is not received, use this URL to debug: https://app.sendgrid.com/email_activity 
        Console.WriteLine(response.IsSuccessStatusCode ? "Email queued successfully!" : "Something went wrong!");
    }
}

public class EmailOptions
{
    public EmailAddress From { get; set; }
    public EmailAddress To { get; set; }
    public string Subject { get; set; }
    public string Body { get; set; }
}

The application adds the SendGrid client to the DI container using the services.AddSendGrid method.

To configure the options of SendGrid, another lambda is used and passed into AddSendGrid. The lambda-inception can be tricky, so make sure to verify all your parentheses match the code above.

Instead of constructing the SendGridClient as you did before, the ISendGridClient will now be injected into the constructor of the EmailSender class, and then used to send an email as before.

Why so complicated?

You went from approximately 12 straightforward lines of code, to approximately 26 lines of code with classes, interfaces, lambda expressions, generic types, and more.

Why complicate the code so much?

For a small sample where you want to go from point A to point B as fast as possible, you can use environment variables and be done with it, but for real-world applications, although it requires extra setup up-front, the techniques from this tutorial will decrease the amount of code you need to write and increase the flexibility and maintainability of your solution.

Better .NET configuration

After following this tutorial, you have a learned how to use .NET's configuration APIs to:

securely configure secrets and sensitive information
retrieve configuration from multiple sources
override configuration from one source with another source
add configuration to the dependency inject container
inject configuration into your classes

Congratulations on making it to the end of a long post about configuration! 👏

You can start including these techniques for SendGrid, Twilio, or really any .NET applications! If you run into any problems, you can refer to the source code for this tutorial on GitHub, or you can submit an issue on the GitHub repository. In addition to the end result, you can find each step in a separate branch (Step 1, 2, 3, 4, 5, and 6)

Let me know what you're working on. I can't wait to see what you build!

How to get the full public URL of ASP.NET Core

Niels Swimburger.NET 🍔 — Mon, 25 Apr 2022 00:00:00 +0000

URLs are what makes the web the web. In ASP.NET Core Controllers, Razor Pages, and Razor views, there's a Request property which gives you access to the HttpRequest instance. The HttpRequest object gives you access to scheme, host (which is the domain and port), path, query string, body content, and headers of the incoming HTTP request.

If you need to know what the full URL is of your web application, you can put the URL together by grabbing the Scheme, Host, PathBase, Path, and QueryString and combining it like this:

$"{Request.Scheme}://{Request.Host}{Request.PathBase}{Request.Path}{Request.QueryString}"

Maybe you're only interested in the URL without the path and query string, in which case you can omit the PathBase, Path, and QueryString parameter from the string interpolation:

$"{Request.Scheme}://{Request.Host}"

If you want to generate URLs for your application, I suggest you use the UrlHelper as explained in this blog post about generating absolute URLs.

If you're using Minimal APIs, there's no Request property accessible to you, but you can accept an instance of HttpRequest as a parameter to your endpoint callback like this:

app.MapGet("/hello-world", (HttpRequest request) =>
    {
        return $"{request.Scheme}://{request.Host}{request.PathBase}{request.Path}{request.QueryString}";
    }
);

What if there's no HTTP request?

If there is no HTTP request that you're handling in your code, like when you're doing some background processing using a BackgroundWorker, you'll need to get the scheme and host some other way. You could store your desired scheme and host into your configuration, or combine them together in a single property and store it into your configuration. Once configured, extract it from configuration and use it to build your absolute URL.

Be mindful of the fact that web application can be requested from multiple URLs depending on the network and infrastructure configuration. So even though you could simply store the full public URL in configuration, that may not be the only URL that users use.

How to generate absolute URLs in ASP.NET Core

Niels Swimburger.NET 🍔 — Tue, 19 Apr 2022 00:00:00 +0000

URLs are what makes the web the web. In ASP.NET Core Controllers, Razor Pages, and Razor views, there's a Url property which gives you access to the UrlHelper. Using the UrlHelper you can generate URLs to MVC actions, pages, and routes. Take a look at this C# expression:

Url.Action(action: "Home", controller: "Privacy")

The result of this expression will be a URL string pointing to the Privacy action on the HomeController: "/Home/Privacy".

This is only the absolute path, but that is a valid URL and should work fine. However, sometimes you want to get the absolute URL which includes the scheme, the hostname or domain name, and the port. For this purpose, the methods on the UrlHelper have overloads to specify the protocol which is the scheme, and the host which is the hostname or domain name. Take a look at this C# expression:

Url.Action(action: "Home", controller: "Privacy", values: null, protocol: "https", host: "your-website")

By specifying the protocol and host, the result is now "https://your-website/Home/Privacy".

However, if you omit the host parameter but keep the protocol parameter, the result will still be an absolute URL, because the host parameter will default to the host used for the current HTTP request.

Url.Action(action: "Home", controller: "Privacy", values: null, protocol: "https")

The result will be something like "https://localhost:7184/Home/Privacy". Whatever the host and port used to make this HTTP request will be used to generate this URL.

When you're handling an HTTP request in ASP.NET Core, you can also access the Scheme property on the HttpRequest, so you could pass the scheme as the protocol parameter to generate the URL with same scheme and host as the current HTTP request.

Url.Action(action: "Privacy", controller: "Home", values: null, protocol: Request.Scheme)

You could also pass in Request.Host as the host parameter, but you don't need to as it already uses the host from the current HTTP request when you specify the protocol without specifying the host parameter.

What if you don't have access to the UrlHelper or you need to build a URL in a way that the UrlHelper doesn't support?

You can also create the absolute base URL for the current HTTP request by grabbing the properties from the HttpRequest. The following code builds the absolute URL for the absolute path "/your/custom/path":

$"{Request.Scheme}://{Request.Host}{Request.PathBase}/your/custom/path"

The result of this expression looks like "https://localhost:7184/your/custom/path".

If you need the full absolute URL including the current absolute path, you could use the following C# expression:

$"{Request.Scheme}://{Request.Host}{Request.PathBase}{Request.Path}"

What if there's no HTTP request?

Conclusion

By default, the UrlHelper methods will generate absolute paths which isn't the same as a full absolute URL because it doesn't contain the scheme, hostname, and port number. However, the UrlHelper methods do contain overloads which allow you to generate the full absolute URL.

You can also manually build the absolute URL using the HttpRequest properties or by storing the desired scheme and hostname from configuration and then extracting it.

In most cases, using an absolute path will be sufficient and it'll save some characters in your HTML, but absolute URLs are sometimes required such as for the technical SEO and social meta tags.