SalesForce API Tutorial .NET DeveloperForce.Force NuGet Package

Below is a guide to getting started with the SalesForce API using the .NET DeveloperForce.Force NuGet package.

(GitHub Source to supplement this blog post: https://github.com/aaronhoffman/SalesForceApiTutorial)
(SalesForce API documentation: http://www.salesforce.com/us/developer/docs/api/)
(GitHub Repo: https://github.com/developerforce/Force.com-Toolkit-for-NET)

Steps:

1. Make sure the API is turned on for your Organization.

The API must be activated as part of your license. You'll have to pay for API access per seat (for every user) even if you'll only have one integration.

I was told by one SalesForce rep that you can check on the status of this feature on the Setup > Company Profile > Company Information page under the Feature Licenses section, but the API is currently enabled for my organization and I see nothing there... so I can't confirm this.  Ultimately, I had to open a support ticket to get it turned on and working for my organization.


2. Create a new "App" to generate a Consumer Key and Consumer Secret.

Go to the Setup > Build > Create > Apps page and click the "New" Button in the "Connected Apps" section.

On the "New Connected App" page you'll need to fill in the required fields. You'll also need to check the "Enable OAuth Settings" checkbox and provide a callback URL. The callback URL does not actually need to exist, and it will not be used in this tutorial. You'll also want to select an OAuth scope, in my scenario I chose "Full access (full)".

Click the save button when you are finished and you will be taken to the Connected App View screen. In the "API (Enable OAuth Settings)" section, copy your Consumer Key and Consumer Secret values, you'll need those to authenticate via the API.


3. Retrieve or generate your Security Token.

(Note: at first, I did not do this step because it is not in the least bit obvious, and I was receiving this error message from the API: "authentication failure - Failed: API security token required" (more info) - so if you Google'd this error and ended up here, please read on.)

If accessing the API from an IP Address that has not been added to a trusted list, you'll need to append your Security Token to your UserName and Password (more info).  If you're like me, you'll have no idea what your security token is, so you'll need to have SalesForce reset it, generate a new one, and email it to you.

To reset your Security Token and have SalesForce generate and email you a new one, go to the upper right-hand corner and hover over your name, in the dropdown select "My Settings", the in the left sidebar menu select "Reset My Security Token" then click the "Reset Security Token" button. SalesForce will then send you an email containing your new Security Token.

4. Add NuGet package to your project.

One nice thing about the SalesForce API for .NET developers is that they have created a SDK/client library that is available via NuGet. Simple add the "DeveloperForce.Force" NuGet package to your project to utilize it. (Always ensure that you are using the latest version of the NuGet package. At the time of writing this, it is still very new and under active development.)

Source: https://github.com/developerforce/Force.com-Toolkit-for-NET
NuGet Package: https://www.nuget.org/packages/DeveloperForce.Force/

(GitHub Source to supplement subsequent steps: https://github.com/aaronhoffman/SalesForceApiTutorial/blob/master/Source/SalesForceApiTutorial.View.Console/SalesForceController.cs)


5. Authentication

The first thing you'll need to do if you want to use the API is Authenticate. You Authenticate using your same UserName and Password as you would use to log into the website (http://www.salesforce.com/) plus the Consumer Key, Consumer Secret, and Security Token we retrieved earlier. One gotcha: you'll need to append your Password and Security Token together and use that value as your "Password" if you are attempting to authenticate from an IP Address that has not been added to your list of trusted IP Addresses. Code snippet available on GitHub.

var userName = "";
var password = "";
var passwordSecurityToken = "";
var consumerKey = "";
var consumerSecret = "";

var auth = new AuthenticationClient();

await auth.UsernamePasswordAsync(consumerKey, consumerSecret, userName, password + passwordSecurityToken);

var forceClient = new ForceClient(auth.InstanceUrl, auth.AccessToken, auth.ApiVersion);


6. Query via API

There's a good chance you might want to query your SalesForce objects using the API. The DeveloperForce project currently supports this functionality. The DeveloperForce project supports both dynamics in .NET and async/await (make sure you have a .NET 4.5 project, or can support the async/await Task pattern).

The Salesforce.Force.ForceClient is the main class you'll be working with.  It has both QueryAsync() and QueryByIdAsync() methods.

The QueryAsync() method accepts a string as a parameter.  The string represents the query you want to execute. The query is in the Salesforce Object Query Language (SOQL) syntax http://www.salesforce.com/us/developer/docs/soql_sosl/index.htm.  It is similar to SQL. Some examples:


select Id, Name from Account

select Id, Name from Account where Id = 'xxxxxxxxxx'

select Contact.Firstname, Contact.Account.Name from Contact


As far as I have found, there is no equivalent to "select * from ___" so you have to list all the fields you want to retrieve. (more about determining field names below in #8)

Alternatively, you can use the QueryByIdAsync() method. This method returns all the the fields associated with an object, but only one layer, so no complex types.

With both of these methods, the type returned can be a static type that you have defined (the properties of the static type must match the names of the fields in the query) or a dynamic. I prefer dynamics in this case, so that's what I'll be using in this example. Again, code here.

Quick Example:

var accounts = await forceClient.QueryAsync("select Id, Name from Account");

foreach (var account in accounts.records)
{
    System.Console.WriteLine(String.Format("Id:{0}, Name:{1}", account.Id, account.Name));
}



7. Modify via API

There's also a pretty good chance you'll want to update your SalesForce objects via the API. The DeveloperForce project supports those operations as well.

dynamic myAccount = new ExpandoObject();
myAccount.Name = "Aaron";
var accountId = await forceClient.CreateAsync("Account", myAccount);

myAccount.Name = "Aaron 2";
await forceClient.UpdateAsync("Account", accountId, myAccount);

await forceClient.DeleteAsync("Account", accountId);


8. Helpful Hints

To determine the object property/field names to use in the SOQL syntax, go to Setup > Build > Customize > [Object Name] > Fields and look at either the "Field Name" or the "API Name" column.

API Data Type to SalesForce Field Type: http://www.salesforce.com/us/developer/docs/api/Content/api_ui_datatype_map.htm

Value to set a multi-select picklist: If you are trying to set a picklist (multi-select) field and want to select multiple things, provide the values as a string of semi-colon separated values. https://developer.salesforce.com/forums?id=906F00000008rhVIAQ

API Limit: Your organization has an API request limit. The limit and current usage can be found on the Setup > Company Profile > Company Information page labeled "API Requests, Last 24 Hours".

Other Get Started articles:
http://seroter.wordpress.com/2014/01/16/using-the-new-salesforce-toolkit-for-net/
https://developer.salesforce.com/blogs/developer-relations/2014/01/announcing-the-salesforce-toolkits-for-net.html


That's it, enjoy!


Hope this helps,
Aaron