Using the New Salesforce Toolkit for .NET

Wade Wegner, a friend of the blog and an evangelist for, just built a new .NET Toolkit for Salesforce developers. This Toolkit is open source and available on GitHub. Basically, it makes it much simpler to securely interact with the REST API from .NET code. It takes care of “just working” on multiple Windows platforms (Win 7/8, WinPhone), async processing, and wrapping up all the authentication and HTTP stuff needed to call endpoints. In this post, I’ll do a basic walkthrough of adding the Toolkit to a project and working with a resource.

After creating a new .NET project (Console project, in my case) in Visual Studio, all you need to do is reference the NuGet packages that Wade created. Specifically, look for the DeveloperForce.Force package which pulls in the “common” package (that has baseline stuff) as well as the JSON.NET package.


First up, add a handful of using statements to reference the libraries we need to use the Toolkit, grab configuration values, and work with dynamic objects.

using System.Configuration;
using Salesforce.Common;
using Salesforce.Force;
using System.Dynamic;

The Toolkit is written using the async and await model for .NET, so calling this library requires some knowledge of this. To make life simple for this demo, define an operation like this that can be called from the Main entry point.

static void Main(string[] args)

static async Task Do()

Let’s fill out the “Do” operation that uses the Toolkit. First, we need to capture our credentials. The Toolkit supports a handful of viable authentication flows. Let’s use the “username-password” flow. This means we need OAuth/API credentials from In the Setup screens, go to Create, then Apps and create a new application. For a full walkthrough of getting credentials for REST calls, see my article on the DeveloperForce site.


With the consumer key and consumer secret in hand, we can now authenticate using the Toolkit. In the code below, I yanked the credentials from the app.config accompanying the application.

//get credential values
string consumerkey = ConfigurationManager.AppSettings["consumerkey"];
string consumersecret = ConfigurationManager.AppSettings["consumersecret"];
string username = ConfigurationManager.AppSettings["username"];
string password = ConfigurationManager.AppSettings["password"];

//create auth client to retrieve token
var auth = new AuthenticationClient();

//get back URL and token
await auth.UsernamePassword(consumerkey, consumersecret, username, password);

When you call this, you’ll see that the AuthenticationClient now has populated properties for the instance URL and access token. Pull those values out, as we’re going to use them when interacting the the REST API.

var instanceUrl = auth.InstanceUrl;
var accessToken = auth.AccessToken;
var apiVersion = auth.ApiVersion;

Now we’re ready to query with the Toolkit. In this first instance, create a class that represents the object we’re querying.

public class Contact
        public string Id { get; set; }
        public string FirstName { get; set; }
        public string LastName { get; set; }

Let’s instantiate the ForceClient object and issue a query. Notice that we pass in a SQL-like syntax when querying the system. Also, see that the Toolkit handles all the serialization for us!

var client = new ForceClient(instanceUrl, accessToken, apiVersion);

//Toolkit handles all serialization
var contacts = await client.Query<Contact>("SELECT Id, LastName From Contact");

//loop through returned contacts
foreach (Contact c in contacts)
      Console.WriteLine("Contact - " + c.LastName);

My app has the following three contacts in the system …


Calling the Toolkit using the code above results in this …


Easy! But does the Toolkit support dynamic objects too? Let’s assume you’re super lazy and don’t want to create classes that represent the objects. No problem! I can use late binding through the dynamics keyword and get back an object that has whatever fields I requested. See here that I added the “FirstName” to the query and am not passing in a known class type.

var client = new ForceClient(instanceUrl, accessToken, apiVersion);

var contacts = await client.Query<dynamic>("SELECT Id, FirstName, LastName FROM Contact");

foreach (dynamic c in contacts)
      Console.WriteLine("Contact - " + c.FirstName + " " + c.LastName);

What happens when you run this? You should have all the queried values available as properties.


The Toolkit supports more than just “query” scenarios. It also works great for create/update/delete as well. Like before, these operations worked with strongly typed objects or dynamic ones. First, add the code below to create a contact using our known “contact” type.

Contact c = new Contact() { FirstName = "Golden", LastName = "Tate" };

string recordId = await client.Create("Contact", c);


That’s a really simple way to create records. Want to see another way? You can use the dynamic ExpandoObject to build up an object on the fly and send it in here.

dynamic c = new ExpandoObject();//
c.FirstName = "Marshawn";
c.LastName = "Lynch";
c.Title = "Chief Beast Mode";

string recordId = await client.Create("Contact", c);


After running this, we can see this record in our database.



This is super useful and a fantastic way to easily interact with from .NET code. Wade’s looking for feedback and contributions as he builds this out further. Add issues if you encounter bugs, and issue a pull request if you want to add features like error handling or support for other operations.


Categories: .NET, Cloud,

59 replies

  1. Hi,

    Its fantastic way to connect to Salesforce.

    The above code is only working in console Application not on web Application. Could please shed some light on it.

    Thanks & Regards !!!
    Inderpal Singh Uppal

  2. Could you please tell, how to access a custom app using this.

  3. I have tries a lot but it is not able to integrate it with it.

    Is there any other way of accessing the custom apps from salesforce to the .Net

  4. I’ve been trying this as well (from both and projects) but I cannot seem to connect to my SANDBOX environment. I keep this exception: “Salesforce.Common.ForceException: expired access/refresh token”.

    I have revoked/refreshed my personal security token, but it doesn’t seem to help.

    When I follow the older instructions (which use the old HTTPClient/Dictionary combo) I can successfully log in.

    Anybody else having that issue? Perhaps I am missing something in my setup.

  5. How do you query more than 2000 records using this toolkit?

  6. Can you do a similar sample for WebServerOAuthFlow? The GIThub sample ( for this doesn’t seem to work; I am not able to get the AccessToken.

  7. When this line is called

    await authentication.UsernamePasswordAsync(“consumer_key”, “consumer_secret”, “username”, “password”);

    I get Salesforce.Common.ForceAuthException with message “authentication failure – Failed: API security token required”

    Any ideas why this is happening? How can this be fixed?

  8. What are you supposed to use as the tokenRequestEndpointUrl when you are connecting to a sandbox org ?

    I am currently getting a ForceAuthException stating expired access/refresh token no matter what I do..

    I have reset my security token twice with no effect…


  9. is there a way to use dyanmic with queryById?

  10. Hi Richard,

    Great post. It helped me to do a benchmark test of the new toolkit compared to the old API. I am sure you will not be surprised to hear that the new method is much faster (duh). The results were published on my blog here:

  11. I’m trying to create a REST service that is used by this salesforce toolkit, but while debugging in visual studio works, when published on IIS I got an error message SalesforceRestService.Lead.d__3.MoveNext(),

  12. Hi Richard
    I’m trying to create a REST service that is used by this salesforce toolkit, but while debugging in visual studio works, when published on IIS I got an error message SalesforceRestService.Lead.d__3.MoveNext(),

  13. Hi – I’m having an issue where when I call auth.UsernamePasswordAysnc…it just never comes back from that call – any ideas?

    • Any chance it’s an async issue where your code moves on and you don’t catch the callback?

    • Upon further review – I do not have this issue with a console app…however I’m trying to create my own webapi app that utilizes the methods of this toolkit, and it seems that I run into issues when creating a class that uses these objects that is utilized by my webapi. I also created a simple web form, and I ran into the same issues.

      • Hi, any luck ? I just tried the same, works great in console app but it does not in the web app, I have also made the following changes to make the it async: the page Async=”true” and RegisterAsyncTask(new PageAsyncTask(RunSample)); in the Page_Load but it just times out

  14. Hi, just tried to test this sample code and am running into a couple of issues. First, the ForceClient object doesn’t appear to have a Query method, but it has a QueryAsync method. So when I tried that, I get a compile error telling me that the contacts returned by this method “does not contain a public definition for ‘GetEnumerator'”.

    Any suggestions appreciated.

  15. My tutorial on accessing Salesforce data from .Net using a Windows Phone app was recently published on Wrox at

  16. I cannot install the packes. I receive this error message. Can somebody help me with this?

    Install-Package : Unable to read package from path ‘Microsoft.Bcl.1.1.9.nupkg’.
    At line:1 char:16
    + Install-Package <<<< DeveloperForce.Force
    + CategoryInfo : NotSpecified: (:) [Install-Package], InvalidDataException
    + FullyQualifiedErrorId : NuGetCmdletUnhandledException,NuGet.PowerShell.Commands.InstallPackageCommand

  17. var contacts = await client.Query(“SELECT Id, LastName From Contact”);
    On this line i am getting following error:
    “The requested resource does not exist”

  18. hi richard, the same code is working well and good for me. how to fetch records from the attachment object and create those attachments using this method? with attachment, it is not working for me.. Could you please advise me a code example. Thanks

  19. Is it possible to authentication with sessionId instead of ( without consumer key,consumerSecret / UserName, password)?

  20. Hello, Could you tell how to access entities metadata?

  21. Having trouble using this toolkit when deploying my app to IIS. Locally everything works perfectly but once deployed to our dev server I am getting the following error when querying salesforce:

    Could not load type ‘d__7`1’ from assembly ‘Salesforce.Common, Version=, Culture=neutral, PublicKeyToken=9f7864e53fb79388’ due to value type mismatch.

    Any help would be greatly appreciated.

  22. Hi Richard,

    Can you please guide how we can use this SDK to convert lead into account


  23. Hi, I am new to Powershell and Salesforce, and I have been looking for ways to query Salesforce objects directly from within Powershell but with no luck so far, and this toolkit definitely offers a lot of what I have been looking for quite some time. Can anyone tell me if there is a way to use the Toolkit in Powershell? Thanks in advance.

  24. Hi Richard,

    I’m getting an Error “Task was cancelled” while fetching up to 75000 records.
    Could you Please Look into it.

    Any help would be greatly appreciated.

  25. What message will return SF if token expires? var contacts = await client.Query(“SELECT Id, LastName From Contact”);

  26. You should update the article to comply with the new salesforce requirement to use
    ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12 | SecurityProtocolType.Tls11 | SecurityProtocolType.Tls; before making any call to salesforce. The library doesn’t do it so the call fail. It’s not huge but it took me quite some time to find out (and i think it should have been fixed in the library but they don’t seems to want to fix it)

  27. Hello, do you know why this solution does not work in .net web api project? In console application it works great, but in web api controller it hangs on that line:

    await auth.UsernamePasswordAsync(consumerkey, consumersecret, username, password, url);

  28. Super lazy? Bro there’s thousands of properties, who in their right mind would recreate all the classes/properties/relationships. Why aren’t they offering a library with all the DTOs in there?


  1. Announcing the Salesforce Toolkits for .NET | Developer Force Blog
  2. Comparing the SOAP API to the New Salesforce Toolkit for .NET | Sara Has No Limits

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: