Force.com Toolkit for .NET

This SDK is now targeting .NET Standard 2.0, .NET 4.5.2, .NET 4.6.2, and .NET 4.7.2.

The Force.com Toolkit for .NET provides an easy way for .NET developers to interact with the Lighting Platform APIs using native libraries.

The Common Libraries for .NET provides functionality used by the Force.com Toolkit for .NET and the Chatter Toolkit for .NET. While you can use the Common Libraries for .NET independently, it is recommended that you use it through one of the toolkits.

NuGet Packages

Published Packages

You can try the libraries immmediately by installing the DeveloperForce.Force and DeveloperForce.Chatter packages:

Package Manager:

Install-Package DeveloperForce.Force
Install-Package DeveloperForce.Chatter

.NET CLI:

dotnet add package DeveloperForce.Force
dotnet add package DeveloperForce.Chatter

Operations

Currently the following operations are supported.

Authentication

To access the Force.com APIs you must have a valid Access Token. Currently there are two ways to generate an Access Token: the Username-Password Authentication Flow and the Web Server Authentication Flow

Username-Password Authentication Flow

The Username-Password Authentication Flow is a straightforward way to get an access token. Simply provide your consumer key, consumer secret, username, and password concatenated with your API Token.

varauth=newAuthenticationClient();awaitauth.UsernamePasswordAsync("YOURCONSUMERKEY","YOURCONSUMERSECRET","YOURUSERNAME","YOURPASSWORDANDTOKEN");

You can also specify a SalesForce API version when creating an authentication client if your use case requires it. The default API Version is currently v36.0

varauth=newAuthenticationClient("v44.0");

You can get the latest API version from your Force.com instance in authentication client.

varauth=newAuthenticationClient();awaitauth.GetLatestVersionAsync();

Web-Server Authentication Flow

The Web-Server Authentication Flow requires a few additional steps but has the advantage of allowing you to authenticate your users and let them interact with the Force.com using their own access token.

First, you need to authenticate your user. You can do this by creating a URL that directs the user to the Salesforce authentication service. You'll pass along some key information, including your consumer key (which identifies your Connected App) and a callback URL to your service.

varurl=Common.FormatAuthUrl("https://login.salesforce.com/services/oauth2/authorize",// if using sandbox org then replace login with testResponseTypes.Code,"YOURCONSUMERKEY",HttpUtility.UrlEncode("YOURCALLBACKURL"));

After the user logs in you'll need to handle the callback and retrieve the code that is returned. Using this code, you can then request an access token.

awaitauth.WebServerAsync("YOURCONSUMERKEY","YOURCONSUMERSECRET","YOURCALLBACKURL",code);

You can see a demonstration of this in the following sample application: https://github.com/developerforce/Force.com-Toolkit-for-NET/tree/master/samples/WebServerOAuthFlow

Creating the ForceClient

After this completes successfully you will receive a valid Access Token and Instance URL. The Instance URL returned identifies the web service URL you'll use to call the Force.com REST APIs, passing in the Access Token. Additionally, the authentication client will return the API version number, which is used to construct a valid HTTP request.

Using this information, we can now construct our Force.com client.

varinstanceUrl=auth.InstanceUrl;varaccessToken=auth.AccessToken;varapiVersion=auth.ApiVersion;varclient=newForceClient(instanceUrl,accessToken,apiVersion);varbulkClient=newBulkForceClient(instanceUrl,accessToken,apiVersion);

Sample Code

Below you'll find a few examples that show how to use the toolkit.

Create

You can create with the following code:

publicclassAccount{publicstringId{get;set;}publicstringName{get;set;}publicstringDescription{get;set;}}varaccount=newAccount(){Name="New Account",Description="New Account Description"};varid=awaitclient.CreateAsync("Account",account);

You can also create with a non-strongly typed object:

varclient=newForceClient(_consumerKey,_consumerSecret,_username,_password);varaccount=new{Name="New Name",Description="New Description"};varid=awaitclient.CreateAsync("Account",account);

Update

You can update an object:

varaccount=newAccount(){Name="New Name",Description="New Description"};varid=awaitclient.CreateAsync("Account",account);account.Name="New Name 2";varsuccess=awaitclient.UpdateAsync("Account",id,account);

Delete

You can delete an object:

varaccount=newAccount(){Name="New Name",Description="New Description"};varid=awaitclient.Create("Account",account);varsuccess=awaitclient.DeleteAsync("Account",id)

Query

You can query for objects:

publicclassAccount{publicstringId{get;set;}publicstringName{get;set;}publicstringDescription{get;set;}}varaccounts=awaitclient.QueryAsync<Account>("SELECT id, name, description FROM Account");foreach(varaccountinaccounts.records){Console.WriteLine(account.Name);}

You can query for metadata:

vardescribe=awaitclient.DescribeAsync<JObject>("Account");foreach(varfieldin(JArray)describe["fields")){Console.WriteLine(field["label"]);}

Bulk Sample Code

Below are some simple examples that show how to use the BulkForceClient

NOTE: The following features are currently not supported

• CSV data type requests / responses
• Zipped attachment uploads
• Serial bulk jobs
• Query type bulk jobs

Create

You can create multiple records at once with the Bulk client:

publicclassAccount{publicstringId{get;set;}publicstringName{get;set;}publicstringDescription{get;set;}}varaccountsBatch1=newSObjectList<Account>{newAccount{Name="TestStAccount1"},newAccount{Name="TestStAccount2"}};varaccountsBatch2=newSObjectList<Account>{newAccount{Name="TestStAccount3"},newAccount{Name="TestStAccount4"}};varaccountsBatch3=newSObjectList<Account>{newAccount{Name="TestStAccount5"},newAccount{Name="TestStAccount6"}};varaccountsBatchList=newList<SObjectList<Account>>{accountsBatch1,accountsBatch2,accountsBatch3};varresults=awaitbulkClient.RunJobAndPollAsync("Account",BulkConstants.OperationType.Insert,accountsBatchList);

The above code will create 6 accounts in 3 batches. Each batch can hold upto 10,000 records and you can use multiple batches for Insert and all of the operations below. For more details on the Salesforce Bulk API, see the documentation.

You can also create objects dynamically using the inbuilt SObject class:

varaccountsBatch1=newSObjectList<SObject>{newSObject{{"Name"= "TestDyAccount1"}},newSObject{{"Name"= "TestDyAccount2"}}};varaccountsBatchList=newList<SObjectList<SObject>>{accountsBatch1};varresults=awaitbulkClient.RunJobAndPollAsync("Account",BulkConstants.OperationType.Insert,accountsBatchList);

Update

Updating multiple records follows the same pattern as above, just change the BulkConstants.OperationType to BulkConstants.OperationType.Update

varaccountsBatch1=newSObjectList<SObject>{newSObject{{"Id"= "YOUR_RECORD_ID"},{"Name"= "TestDyAccount1Renamed"}},newSObject{{"Id"= "YOUR_RECORD_ID"},{"Name"= "TestDyAccount2Renamed"}}};varaccountsBatchList=newList<SObjectList<SObject>>{accountsBatch1};varresults=awaitbulkClient.RunJobAndPollAsync("Account",BulkConstants.OperationType.Update,accountsBatchList);

Delete

As above, you can delete multiple records with BulkConstants.OperationType.Delete

varaccountsBatch1=newSObjectList<SObject>{newSObject{{"Id"= "YOUR_RECORD_ID"}},newSObject{{"Id"= "YOUR_RECORD_ID"}}};varaccountsBatchList=newList<SObjectList<SObject>>{accountsBatch1};varresults=awaitbulkClient.RunJobAndPollAsync("Account",BulkConstants.OperationType.Delete,accountsBatchList);

Upsert

If your object includes a custom field with the External Id property set, you can use that to perform bulk upsert (update or insert) actions with BulkConstants.OperationType.Upsert. Note that you also have to specify the External Id field name when starting the job.

// Assumes you have a custom field "ExampleId" on your Account object// that has the "External Id" flag set.varaccountsBatch1=newSObjectList<SObject>{newSObject{{"Name"= "TestDyAccount1"},{"ExampleId"= "ID00001"}},newSObject{{"Name"= "TestDyAccount2"},{"ExampleId"= "ID00002"}}};varaccountsBatchList=newList<SObjectList<SObject>>{accountsBatch1};varresults=awaitbulkClient.RunJobAndPollAsync("Account","ExampleId"
BulkConstants.OperationType.Upsert,accountsBatchList);

Contributing to the Repository

If you find any issues or opportunities for improving this respository, fix them! Feel free to contribute to this project by forking this repository and make changes to the content. Once you've made your changes, share them back with the community by sending a pull request. Please see How to send pull requests for more information about contributing to Github projects. You will be required to sign a Salesforce CLA for your submission to be considered.

Reporting Issues

If you find any issues with this demo that you can't fix, feel free to report them in the issues section of this repository.