Next Generation C# / .NET Helper Library Release

Time to read: 5 minutes

February 28, 2017
Written by
Dan Theurer
Twilion

csharp blog logo

Today, we are excited to announce the general availability of our next generation C# helper library. Get ready to enjoy a whole new level of productivity.

The approach

C# is the latest addition to the Twilio next-generation helper library family along with newly released helper libraries for PHP and Java. We rebuilt the C# library from the ground up, incorporating the .NET developer community’s feedback.

To learn more about our novel approach to make the helper-libraries more consistent, enable faster iteration, and improve the libraries by having a shared foundation across languages, check out our blog post that introduced the next generation Twilio Helper Libraries.

The next language that we will release is Python, but first things first, let’s have a deeper look at C#.

What’s new

The Twilio C# helper library is now more intuitive to use and has extend framework compatibility.

The major enhancements in the new library are

  • Full cross-platform .NET Core support (.NET Standard 1.4)
  • Support for async/await
  • Automatic paging when requesting a list of resources
  • Addition of helper classes to generate TwiML
  • Still compatible all the way back to .NET Framework version 3.5

 

We were working hard to ensure the new library is compatible with a wide range of .NET platforms, particularly .NET Standard 1.4. We couldn’t have done it without the help of the .NET community, especially Gutemberg Ribeiro from Brazil who helped us navigate the new .NET build system so we could target .NET Standard as well as still target v3.5.

Targeting .NET Standard means you can use the Twilio C# helper library with cross-platform .NET Core applications, meaning all of the code examples for our docs will work on Mac and Linux in addition to Windows.

Speaking of examples, let’s take a look at some.

The Basics

Initializing the client for future REST API calls is now a static method. There is no need to create a client object.

// Find your Account Sid and Auth Token at twilio.com/user/account
var accountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
var authToken = "your_auth_token";
TwilioClient.Init(accountSid, authToken);

This only needs to be done once. All subsequent calls to the Twilio API will be authenticated using the credentials passed to the Init method. In fact, on .NET 4.5.1 and above (including .NET Core), this creates a static HttpClient that will be reused for all of your API requests (translation: making multiple API requests will be much faster).

Actions

Each resource in the Twilio REST API has a corresponding C# class. Want to work with SMS messages? You need the MessageResource class. Phone calls? Check out CallResource.

Each resource class has a set of static methods

  • Fetch: Gets an instance of a resource
  • Create: Makes a new instance of a resource
  • Update: Modifies an instance of a resource
  • Delete: Removes an instance of a resource
  • Read: Lists instances of a resource

Where a method isn’t supported by Twilio for a given resource, it is omitted from the class.

var message = MessageResource.Fetch("SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
Console.WriteLine(message.Sid);
// message sid: SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

 

Paging

In prior versions of the helper library, you had to worry about paging. You would retrieve one page of results and then continue requesting pages until you’d retrieved all of the resources you needed. Now, paging is handled automatically.

var thirtyDaysAgo = DateTime.UtcNow.AddDays(-30);
var messages = MessageResource.Read(dateSentAfter: thirtyDaysAgo);
// Iterating automatically requests additional pages 
// from the Twilio REST API
foreach (var message in messages)
{
    Console.WriteLine(message.Body);
}
// list of message bodies

For more examples on how the Resource Classes are used, have look at the C# Migration Guide.

Asynchronous Methods

If you’re using .NET Framework 4.5.1+ or .NET Core 1.0+, then you can use asynchronous versions of the Create, Fetch, Read, Update, and Delete resource methods. Predictably, these methods are named CreateAsync, FetchAsync, ReadAsync, UpdateAsync, and DeleteAsync.

public async Task PhoneHomeAsync()
{
    var call = await CallResource.CreateAsync(
        to: new PhoneNumber("+15558675309"),
        from: new PhoneNumber("+15017250604"),
        url: new Uri("http://demo.twilio.com/docs/voice.xml")
    );
    return call;
}

 

TwiML Support

The Twilio C# SDK now includes helper classes to generate TwiML. There are two classes you can use to generate TwiML: Twilio.TwiML.VoiceResponse and Twilio.TwiML.MessagingResponse. You would use the former when handling a voice call and the latter when responding to a text message.

To write TwiML to handle a phone call, just create an instance of the VoiceResponse class and then call methods on the new object that correspond to the various TwiML verbs. For example, here’s code that plays a greeting and then connects the call to another phone number:

var response = new VoiceResponse();
response.Say("Congratulations on being rescued.", voice: "woman");
response.Dial("+15017250604");

 

You can call response.ToString() to get the following output TwiML:

<<!--?xml version="1.0" encoding="utf-8"?-->

  Congratulations on being rescued.
  +15017250604

 

How To Get Started

The are several great resources to help you to get started with the new library:

  • The Getting Started Guide that covers installation and how to send your first message.
  • Our guides and tutorials provide code samples for several use cases.
  • The auto-generated library docs are a helpful reference documentation.
  • The Migration Guide is a great resource, especially if you are familiar with the previous generation. It covers some of the new features and highlights the differences.

 

The new libraries come in two lines based on our Versioning Strategy:

  • The ’mainline’ that contains our GA products and is the most stable release
  • ‘edge’ which includes new features that are in Developer Preview or Beta. Here is a more detailed writeup about our our Versioning Strategy.

Deprecation

New functionality will only be added to the new libraries (C# 5.x). The old libraries (C# 4.x) will be officially supported until 05/31/17. After that day, Twilio will stop providing bug fixes and Support might ask you to upgrade before debugging issues.

Next-gen Release Candidates

We’d love your get your feedback on our other release candidates. They are available on Github now and we are interested in your issue tickets and pull requests.

Related Posts

Related Resources

A newspaper article

Twilio Docs

From APIs to SDKs to sample apps

API reference documentation, SDKs, helper libraries, quickstarts, and tutorials for your language and platform.
An Open book

Resource Center

The latest ebooks, industry reports, and webinars

Learn from customer engagement experts to improve your own communication.
User group reactions

Ahoy

Twilio's developer community hub

Best practices, code samples, and inspiration to build communications and digital engagement experiences.