Updates to the Force.com Toolkit for .NET

Almost two years ago, DeveloperForce released a REST-based toolkit that offered an easy way for .NET developers to connect with the Force.com & Chatter REST API’s.

Since then, the toolkits creator has unfortunately left Salesforce, but lucky for us all, that has not stopped development. Thankfully, the newly formed alliance between Salesforce and Microsoft (along with some great pull requests made by the open source community) has allowed the update of this fantastic toolkit to continue.

There have been several big changes made to the toolkit in the past few months.

You should know that all these changes are part of the latest NuGet package, which you can update by going into Package Manager and clicking the Update button for the DeveloperForce.Force package. As you can see from the image below, the last publish was on 11/12/2015.

UpdateToolkit

One of my favorite new features is:

  • Ability to execute SOSL queries – This capability was provided by a pull request from Jerad Clingerman in August, in which he added the SearchAsync method. So now, you can do a search using code such as this:
var test = await client.SearchAsync<Contact>("FIND {617*} in Phone FIELDS RETURNING Contact(Id, FirstName, Lastname, Email, Phone, MobilePhone)");

Unfortunately, there is still no substantial documentation for how to use the toolkit. If you have a question about usage then your best resource is to look at the functional tests which are available here:

You can also check out a series of articles I wrote for DeveloperForce that was called Nothin but.NET. In this 6 part series, I go as deep as I could into how to use the Toolkit. It should be enough to get you started.

Enjoy!

How to Set the API Version using the Force.com Toolkit for .NET

toolkitIf you are doing Salesforce Integration work and working with the REST API, then you have probably already heard about the Force.com Toolkit for .NET. But, because the toolkit is unfortunately not very well documented, you probably had no idea that it defaults to using version 32 of the REST API. You also probably had no idea that you can change the api version (like to the latest version, which is currently 34) using the Toolkit.

Don’t worry, I had no idea either and I have worked with the Toolkit quite extensively. In fact, when I discovered that it was using version 32, I actually reported it as an issue (since the Toolkit is Open Source). However, as the projects owner (Wade Wegner) graciously pointed out to me, this is a purposeful feature of the Toolkit. As he states, “The SDK is designed to make it easy for you to change the API version yourself programmatically but defaults to the last known working API version. That’s not to say it won’t work with v34, only we haven’t tested it.”

So, now you may be asking, “Ok, so how do I change it?”

Glad you asked, since that is what this post is about. Turns out to be pretty easy (since the Toolkit is pretty slick like that).

The ApiVersion property can be set or retrieved after authenticating using either the UsernamePasswordAsync or WebServerAsync methods. For example, if I were to place a line of code like this in a console application after authentication, I would expect to get “v32.0” printed out to the console:

await auth.UsernamePasswordAsync(consumerKey, consumerSecret,
        username, password + token, url);
Console.WriteLine("Sucessfully Logged in. You're default API Version is: " 
        + auth.ApiVersion);

Now if I want to set it to the latest version (which is 34), I can pass that in when I get an instance of the ForceClient, which is needed to perform any operation using the Toolkit. The code to set the ApiVersion to 34 would simply look like this:

var client = new ForceClient(auth.InstanceUrl, auth.AccessToken, "v34.0");

That’s it. Just remember that the ApiVersion is a string and that it must be formatted like this: “v34.0”. Passing in “34”  or 34 will not work and will get you errors, in fact. Not sure I like that part so much, but just glad I can set it to what I want.

BTW, I tested that this would work using the Sample Console app and setting the version to 34 and it worked splendidly.

Hope that helps someone out there.