NetCoreForce

A .NET Standard and .NET Core Salesforce REST API toolkit and API wrapper

This project is not offered, sponsored, or endorsed by Salesforce.

CHANGELOG

CI main:

CI dev:

NetCoreForce v3 currently targeting netstandard 2.0 & 2.1, supports .NET Core 2.1,3.1, and 6.0 apps.

For .NET Core 1.x support, use NetCoreForce v2.7

Projects in this solution:

• NetCoreForce.Client
  • Main library
• NetCoreForce.Client.Tests
  • Unit tests (offline/mocked)
• NetCoreForce.FunctionalTests
  • Online Unit tests (Needs valid login credentials)
• NetCoreForce.ModelGenerator
  • Check README for docs
  • Optional custom dotnet-cli tool for code generation of custom objects/fields.
• NetCoreForce.Models
  • Check README for docs
  • Optional library with a set of pre-generated standard models
• SampleConsole
  • A simple .NET Core console app to demonstrate the library.

NuGet Packages

• NetCoreForce.Client
• NetCoreForce.Models
• NetCoreForce.ModelGenerator

An effort is made to minimize the dependencies:

• Newtonsoft.Json (JSON Serialization)
• System.Text.Encodings.Web (URL formatting)
• Microsoft.Bcl.AsyncInterfaces
  • Only included in .netstandard2.0, .netcoreapp2.0 targets
  • Provides await using, async disposables

Experimental Projects:

• Please note: The LINQ library has barely been tested, and is not recommended for production use. Consider it an alpha release.
• NetCoreForce.Linq - an experimental LINQ-to-SOQL query provider
• NetCoreForce.Linq.Tests - LINQ Unit tests (offline/mocked)
• NuGet package: NetCoreForce.Linq
• Retains a dependency on System.Interactive.Async

Feedback and suggestions welcome.

Licensed under the MIT license.

Basic Usage Example

///Initialize the authentication client
AuthenticationClient auth = new AuthenticationClient();

//Pass in the login information
await auth.UsernamePasswordAsync("your-client-id", "your-client-secret", "your-username", "your-password", "token-endpoint-url");

//the AuthenticationClient object will then contain the instance URL and access token to be used in each of the API calls
ForceClient client = new ForceClient(auth.AccessInfo.InstanceUrl, auth.ApiVersion, auth.AccessInfo.AccessToken);

//Retrieve an object by Id
SfAccount acct = await client.GetObjectById<SfAccount>(SfAccount.SObjectTypeName, "001i000002C8QTI");
//Modify the record and update
acct.Description = "Updated Description";
await client.UpdateRecord<SfAccount>(SfAccount.SObjectTypeName, acct.Id, acct);
//Delete the record
await client.DeleteRecord(SfAccount.SObjectTypeName, acct.Id);

//Get the results of a SOQL query
List<SfCase> cases = await client.Query<SfCase>("SELECT Id,CaseNumber,Account.Name,Contact.Name FROM Case");

Nested Query Results

When you include related objects in a SOQL query:

SELECT Id,CaseNumber,Account.Name,Contact.Name FROM Case

And get the results via the client, you can then access the related objects and fields included in the query in a fluent manner.

List<SfCase> cases = await client.Query<SfCase>("SELECT Id,CaseNumber,Account.Name,Contact.Name FROM Case");
SfCase firstCase = cases[0];
string caseNumber = firstCase.CaseNumber;
string caseAccountName = firstCase.Account.Name;
string caseContactName = firstCase.Contact.Name;

Nested queries are not fully supported - the subquery results will not be complete if they exceed the batch size as the NextRecordsUrl in the subquery results is not being acted upon. Instead use the relationship syntax in the example above.

// *NOT* fully supported
"SELECT Id,CaseNumber, (Select Contact.Name from Account) FROM Case"

Asynchronous Batch Processing

Query method will retrieve the full result set before returning. By default, results are returned in batches of 2000. In cases where you are working with large result sets, you may want to use QueryAsync to retrieve the batches asynchronously for better performance.

// First create the async enumerable. At this point, no query has been executed.
// batchSize can be omitted to use the default (usually 2000), or given a custom value between 200 and 2000.
IAsyncEnumerable<SfContact> contactsEnumerable = client.QueryAsync<SfContact>("SELECT Id, Name FROM Contact ", batchSize: 200);

// Get the enumerator, in a using block for proper disposal
await using (IAsyncEnumerator<SfContact> contactsEnumerator = contactsEnumerable.GetAsyncEnumerator())
{
    // MoveNext() will execute the query and get the first batch of results.
    // Once the inital result batch has been exhausted, the remaining batches, if any, will be retrieved.
    while (await contactsEnumerator.MoveNextAsync())
    {
        SfContact contact = contactsEnumerator.Current;
        // process your results
    }
}