Next Generation C# / .NET Helper Library Release

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.

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.

 

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.

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.

 

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:

 

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

 

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.

  • Gordon Weis

    The Twilio LookUps Api is dependent on Twilio 4.X … are there plans to update the LookUps Api to version 5.X? If yes, any idea on timing?

  • Jluis

    What was the architectural decision behind replacing regular object invocation with static calls? Also, This approach breaks with code practices like unit testing or dependency injection

    • dprothero

      Jluis, it’s merely a shortcut, but by no means required. You can instantiate your own client and use it with a dependency injection framework and mock it in your unit tests. More docs are coming, but here’s a quick note about it: https://www.twilio.com/docs/libraries/csharp/migrating-your-csharp-dot-net-application-twilio-sdk-4x-5x#custom-client

      • Jluis

        So, the concept of Client object was discarded? Or how it’s used with the new *Resource object?

        • dprothero

          Every method on the *Resource objects has an optional client parameter that you can pass in anything that inherits from ITwilioRestClient. Here’s a gist that creates a client manually: https://gist.github.com/dprothero/165f0544d752ade2c29841d7882efa8e

          • Jluis

            The MessageReource object is static, and its not mockeable

          • dprothero

            Correct, but you shouldn’t need to mock those. Just mock a client and pass the mocked client object into the calls on the resources.

          • Jluis

            Another question. Why you guys decided to have this *Resource objects with static methods that retrieves instances of that very same objects? What is the intended goal compared with the previous wrapper version?

          • dprothero

            Short answer was ease of use. I saw your question on Stack Overflow and tried to provide a more complete answer there: http://stackoverflow.com/questions/42520591/architectural-reasons-behind-the-twilio-c-sharp-5-x-library

          • Jluis

            Thank you so much for the reply.

            It shocked me a little bit at first because the usability changed radically from previous version, and I felt it like a step backwards. Specially in how I’ve been using the wrapper in my implementation.

            I hope in the future you can provide more samples for the different possible scenarios. At this point I think Ill wrap this up with another object and inject that object into my system.

            Thanks for all

          • David Benson

            This really needs to be added to the documentation!
            The migration guide ought to have a mapping of old method to new method. Sure, I dug through the documentation and found most of it. If you are asking us to upgrade within 3 months, please make it easy!

  • Evan

    A new blog post on implementing ITwilioRestClient might be helpful (some examples, modfiying the request, etc…).

    • dprothero

      Thanks @rossiter10:disqus, that’s the plan. I will let you know when this is live

      • Pablo C

        Hi, I need to implement the ITwilioRestClient to support a proxy. Are there any examples of how to implement this class? I couldn’t find anything online and I’m finding it a bit hard :(

  • David Benson

    In the 4.x API, the MessageListRequest interface had a comparison type, ex DateSentComparison = ComparisonType.GreaterThanOrEqualTo. The 5.0 API has dateSentAfter is this inclusive or exclusive? The documentation doesn’t mention this:
    https://twilio.github.io/twilio-csharp/5.0.0/class_twilio_1_1_rest_1_1_api_1_1_v2010_1_1_account_1_1_read_message_options.html#aae0de4a5d26814fc646b96b577171d23

    • Jingming Niu

      Hey @disqus_Qp6bYgPXHW:disqus, this field is inclusive to the second! For example, you can query anything that was sent after ‘2017-02-01T02:30:00Z’.