Skip to content

Commit b26d6b3

Browse files
anthonyreillyanthonyreilly
committed
docs: doc update
1 parent ecb32ea commit b26d6b3

2 files changed

Lines changed: 130 additions & 7 deletions

File tree

‎docs/docfx.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,9 @@
66
{
77
"src": "../src",
88
"files": [
9-
"NetCoreForce.Client/*.csproj"
9+
"NetCoreForce.Client/*.csproj",
10+
"NetCoreForce.Models/*.csproj",
11+
"NetCoreForce.ModelGenerator/*.csproj"
1012
]
1113
}
1214
],

‎docs/index.md‎

Lines changed: 127 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,136 @@
22
_layout: landing
33
---
44

5-
# This is the **HOMEPAGE**.
65

7-
Refer to [Markdown](http://daringfireball.net/projects/markdown/) for how to write markdown files.
86

9-
## Quick Start Notes:
7+
* [ForceClient](~/api/NetCoreForce.Client.ForceClient.yml)
8+
-[NetcoreForce.Client](~/api/NetCoreForce.Client.yml)
109

11-
1. Add images to the *images* folder if the file is referencing an image.
1210

11+
# NetCoreForce
1312

14-
[NetcoreForce.Client](~/api/NetcoreForce.Client.yml)
13+
## A .NET Salesforce REST API integration library
14+
*This project is not offered, sponsored, or endorsed by Salesforce.*
1515

16-
[ForceClient](~/api/NetCoreForce.Client.ForceClient.yml)
16+
Targets .NET Standard 2.0 - this means it will be generally compatible with .NET Framework 4.6.1+ and .NET Core 2.0+
17+
For more info on .NET Standard 2.0 compatiblity [see the Microsoft documentation here](https://learn.microsoft.com/en-us/dotnet/standard/net-standard?tabs=net-standard-2-0)
18+
19+
Full tested support is for .NET Core 6.0 - 9.0 as tooling and tests target those.
20+
21+
![NuGet Downloads](https://img.shields.io/nuget/dt/NetCoreForce.Client)
22+
23+
[GitHub Repository](https://github.com/anthonyreilly/NetCoreForce)
24+
25+
### NuGet Packages
26+
* [NetCoreForce.Client](https://www.nuget.org/packages/NetCoreForce.Client/)
27+
* [NetCoreForce.Models](https://www.nuget.org/packages/NetCoreForce.Models/)
28+
* [NetCoreForce.ModelGenerator](https://www.nuget.org/packages/NetCoreForce.ModelGenerator/)
29+
30+
### [CHANGELOG](CHANGELOG.md)
31+
32+
CI main:
33+
[![CI](https://github.com/anthonyreilly/NetCoreForce/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/anthonyreilly/NetCoreForce/actions/workflows/ci.yml)
34+
CI dev:
35+
[![CI](https://github.com/anthonyreilly/NetCoreForce/actions/workflows/ci.yml/badge.svg?branch=dev)](https://github.com/anthonyreilly/NetCoreForce/actions/workflows/ci.yml)
36+
37+
38+
### Projects in this solution:
39+
* [NetCoreForce.Client](src/NetCoreForce.Client)
40+
- Main library
41+
* [NetCoreForce.Client.Tests](src/NetCoreForce.Client.Tests)
42+
- Unit tests (offline/mocked)
43+
* [NetCoreForce.FunctionalTests](src/NetCoreForce.FunctionalTests)
44+
- Online Unit tests (Needs valid login credentials)
45+
* [NetCoreForce.ModelGenerator](src/NetCoreForce.ModelGenerator)
46+
- Check [README](src/NetCoreForce.ModelGenerator/README.md) for docs
47+
- Optional custom dotnet-cli tool for code generation of custom objects/fields.
48+
* [NetCoreForce.Models](src/NetCoreForce.Models)
49+
- Check [README](src/NetCoreForce.Models/README.md) for docs
50+
- Optional library with a set of pre-generated standard models
51+
* [SampleConsole](src/SampleConsole)
52+
- A simple .NET Core console app to demonstrate the library.
53+
54+
55+
56+
### Designed to minimize dependencies:
57+
* [Newtonsoft.Json](https://www.nuget.org/packages/Newtonsoft.Json) (JSON Serialization)
58+
* [System.Text.Encodings.Web](https://www.nuget.org/packages/System.Text.Encodings.Web) (URL formatting)
59+
* [Microsoft.Bcl.AsyncInterfaces](https://www.nuget.org/packages/Microsoft.Bcl.AsyncInterfaces/)
60+
- Only included in .netstandard2.0, .netcoreapp2.0 targets
61+
- Provides await using, async disposables
62+
63+
(Migration from Newtonsoft.Json to System.Text.Json is planned)
64+
65+
Feedback and suggestions welcome.
66+
67+
Licensed under the MIT license.
68+
69+
70+
### Basic Usage Example
71+
72+
```csharp
73+
///Initialize the authentication client
74+
AuthenticationClient auth = new AuthenticationClient();
75+
76+
//Pass in the login information
77+
await auth.UsernamePasswordAsync("your-client-id", "your-client-secret", "your-username", "your-password", "token-endpoint-url");
78+
79+
//the AuthenticationClient object will then contain the instance URL and access token to be used in each of the API calls
80+
ForceClient client = new ForceClient(auth.AccessInfo.InstanceUrl, auth.ApiVersion, auth.AccessInfo.AccessToken);
81+
82+
//Retrieve an object by Id
83+
SfAccount acct = await client.GetObjectById<SfAccount>(SfAccount.SObjectTypeName, "001i000002C8QTI");
84+
//Modify the record and update
85+
acct.Description = "Updated Description";
86+
await client.UpdateRecord<SfAccount>(SfAccount.SObjectTypeName, acct.Id, acct);
87+
//Delete the record
88+
await client.DeleteRecord(SfAccount.SObjectTypeName, acct.Id);
89+
90+
//Get the results of a SOQL query
91+
List<SfCase> cases = await client.Query<SfCase>("SELECT Id,CaseNumber,Account.Name,Contact.Name FROM Case");
92+
```
93+
94+
### Nested Query Results
95+
96+
When you include related objects in a SOQL query:
97+
```
98+
SELECT Id,CaseNumber,Account.Name,Contact.Name FROM Case
99+
```
100+
101+
And get the results via the client, you can then access the related objects and fields included in the query in a fluent manner.
102+
```csharp
103+
List<SfCase> cases = await client.Query<SfCase>("SELECT Id,CaseNumber,Account.Name,Contact.Name FROM Case");
104+
SfCase firstCase = cases[0];
105+
string caseNumber = firstCase.CaseNumber;
106+
string caseAccountName = firstCase.Account.Name;
107+
string caseContactName = firstCase.Contact.Name;
108+
```
109+
110+
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.
111+
```
112+
// *NOT* fully supported
113+
"SELECT Id,CaseNumber, (Select Contact.Name from Account) FROM Case"
114+
```
115+
116+
### Asynchronous Batch Processing
117+
118+
Query<T> method will retrieve the full result set before returning. By default, results are returned in batches of 2000.
119+
In cases where you are working with large result sets, you may want to use QueryAsync<T> to retrieve the batches asynchronously for better performance.
120+
121+
```csharp
122+
// First create the async enumerable. At this point, no query has been executed.
123+
// batchSize can be omitted to use the default (usually 2000), or given a custom value between 200 and 2000.
124+
IAsyncEnumerable<SfContact> contactsEnumerable = client.QueryAsync<SfContact>("SELECT Id, Name FROM Contact ", batchSize: 200);
125+
126+
// Get the enumerator, in a using block for proper disposal
127+
await using (IAsyncEnumerator<SfContact> contactsEnumerator = contactsEnumerable.GetAsyncEnumerator())
128+
{
129+
// MoveNext() will execute the query and get the first batch of results.
130+
// Once the inital result batch has been exhausted, the remaining batches, if any, will be retrieved.
131+
while (await contactsEnumerator.MoveNextAsync())
132+
{
133+
SfContact contact = contactsEnumerator.Current;
134+
// process your results
135+
}
136+
}
137+
```

0 commit comments

Comments
 (0)