Skip to content

Commit 8f3cb58

Browse files
fuzzzerdfuzzzerd
authored
docs: update docs website with more content and examples (#416)
1 parent 9d1e073 commit 8f3cb58

17 files changed

Lines changed: 1261 additions & 244 deletions

‎docs/configuration.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
layout: default
3+
nav_order: 5
4+
title: Configuration
5+
---
6+
7+
## Configuration
8+
9+
### ConnectionInfo
10+
11+
All clients require a `ConnectionInfo` object:
12+
13+
```csharp
14+
var conn = new ConnectionInfo
15+
{
16+
FmsUri = "https://your-server.com",
17+
Database = "YourDatabase",
18+
Username = "admin",
19+
Password = "password"
20+
};
21+
```
22+
23+
#### REST API Version
24+
25+
Set `RestTargetVersion` to target a specific Data API version:
26+
27+
```csharp
28+
conn.RestTargetVersion = RestTargetVersion.v1; // default
29+
conn.RestTargetVersion = RestTargetVersion.v2;
30+
conn.RestTargetVersion = RestTargetVersion.vLatest;
31+
```
32+
33+
### Creating a Client Directly
34+
35+
```csharp
36+
var client = new FileMakerRestClient(new HttpClient(), conn);
37+
```
38+
39+
### Using Dependency Injection
40+
41+
#### Standard (Scoped) Lifetime
42+
43+
Register `IFileMakerApiClient` with `AddHttpClient` for managed `HttpClient` lifetime:
44+
45+
```csharp
46+
services.AddSingleton<ConnectionInfo>(new ConnectionInfo
47+
{
48+
FmsUri = "https://your-server.com",
49+
Database = "YourDatabase",
50+
Username = "admin",
51+
Password = "password"
52+
});
53+
54+
services.AddHttpClient<IFileMakerApiClient, FileMakerRestClient>();
55+
```
56+
57+
This creates a new `FileMakerRestClient` per scope (typically per HTTP request in ASP.NET Core).
58+
59+
#### Singleton Lifetime
60+
61+
For better performance when making many Data API calls per request, register as a singleton:
62+
63+
```csharp
64+
services.AddHttpClient(); // register IHttpClientFactory
65+
66+
services.AddSingleton<ConnectionInfo>(new ConnectionInfo
67+
{
68+
FmsUri = "https://your-server.com",
69+
Database = "YourDatabase",
70+
Username = "admin",
71+
Password = "password"
72+
});
73+
74+
services.AddSingleton<IFileMakerApiClient, FileMakerRestClient>(sp =>
75+
{
76+
var hcf = sp.GetRequiredService<IHttpClientFactory>();
77+
var ci = sp.GetRequiredService<ConnectionInfo>();
78+
return new FileMakerRestClient(hcf.CreateClient(), ci);
79+
});
80+
```
81+
82+
The singleton approach reuses the FileMaker Data API token across requests, reducing authentication overhead.
83+
84+
### FileMaker Cloud Authentication
85+
86+
For FileMaker Cloud (Claris Connect), use `FileMakerCloudAuthTokenProvider`:
87+
88+
```csharp
89+
var conn = new ConnectionInfo
90+
{
91+
FmsUri = "https://yourhost.account.filemaker-cloud.com",
92+
Database = "YourDatabase",
93+
Username = "user@domain.com",
94+
Password = "password"
95+
};
96+
97+
var client = new FileMakerRestClient(
98+
new HttpClient(),
99+
new FileMakerCloudAuthTokenProvider(conn));
100+
```
101+
102+
`FileMakerCloudAuthTokenProvider` handles authentication via AWS Cognito. The default Cognito settings are pre-configured for FileMaker Cloud:
103+
104+
| Property | Default |
105+
|---|---|
106+
| `CognitoUserPoolID` | `us-west-2_NqkuZcXQY` |
107+
| `CognitoClientID` | `4l9rvl4mv5es1eep1qe97cautn` |
108+
| `RegionEndpoint` | `us-west-2` |
109+
110+
Override these on `ConnectionInfo` if your FileMaker Cloud instance uses different values.
111+
112+
For a full description of using the FileMaker Data API with FileMaker Cloud, see [this discussion](https://github.com/fuzzzerd/fmdata/issues/217#issuecomment-1203202293).

‎docs/containers.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
layout: default
3+
parent: Guide
4+
nav_order: 7
5+
title: Container Data
6+
---
7+
8+
## Container Data
9+
10+
Container fields in FileMaker store files (images, PDFs, etc.). FMData handles downloading and uploading container data separately from regular field data.
11+
12+
### Model Setup
13+
14+
Add a `byte[]` property with `[ContainerDataFor]` referencing the container field's C# property name:
15+
16+
```csharp
17+
[DataContract(Name = "Documents")]
18+
public class Document
19+
{
20+
[DataMember]
21+
public string Title { get; set; }
22+
23+
[DataMember]
24+
public string Attachment { get; set; } // container field
25+
26+
[ContainerDataFor("Attachment")] // references the C# property name
27+
public byte[] AttachmentData { get; set; }
28+
}
29+
```
30+
31+
### Downloading Container Data
32+
33+
After finding records, use `ProcessContainers` to download all container data for a collection:
34+
35+
```csharp
36+
var results = await client.FindAsync(new Document { Title = "Report" });
37+
await client.ProcessContainers(results);
38+
// each result's AttachmentData now contains the file bytes
39+
```
40+
41+
For a single record:
42+
43+
```csharp
44+
await client.ProcessContainer(singleDocument);
45+
```
46+
47+
#### Auto-load on Find
48+
49+
Set `LoadContainerData` on a find request to automatically download container data with the results:
50+
51+
```csharp
52+
var req = client.GenerateFindRequest<Document>();
53+
req.Layout = "Documents";
54+
req.AddQuery(new Document { Title = "Report" }, omit: false);
55+
req.LoadContainerData = true;
56+
57+
var results = await client.SendAsync(req);
58+
// container data is already loaded
59+
```
60+
61+
### Uploading Container Data
62+
63+
Use `UpdateContainerAsync` to upload data to a container field:
64+
65+
```csharp
66+
var fileBytes = File.ReadAllBytes("report.pdf");
67+
68+
await client.UpdateContainerAsync(
69+
"Documents", // layout
70+
recordId, // FileMaker record ID
71+
"Attachment", // container field name
72+
"report.pdf", // file name
73+
fileBytes); // file content
74+
```
75+
76+
For repeating container fields, specify the repetition number:
77+
78+
```csharp
79+
await client.UpdateContainerAsync(
80+
"Documents", recordId, "Attachment", "report.pdf",
81+
repetition: 2, content: fileBytes);
82+
```
83+
84+
> **Note:** Creating a record with container data requires two calls — one to create the record, then a second to upload the container data.

‎docs/creating-records.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
layout: default
3+
parent: Guide
4+
nav_order: 3
5+
title: Creating Records
6+
---
7+
8+
## Creating Records
9+
10+
### Basic Create
11+
12+
Pass a model instance to `CreateAsync`. The layout is determined by the `[DataContract(Name = "...")]` attribute:
13+
14+
```csharp
15+
var invoice = new Invoice
16+
{
17+
InvoiceNumber = "INV-001",
18+
Amount = 150.00m,
19+
Status = "Open"
20+
};
21+
22+
var response = await client.CreateAsync(invoice);
23+
```
24+
25+
### Layout Override
26+
27+
Specify a layout explicitly:
28+
29+
```csharp
30+
var response = await client.CreateAsync("AlternateLayout", invoice);
31+
```
32+
33+
### Null and Default Value Control
34+
35+
By default, properties with `null` or default values are excluded from the request. To include them:
36+
37+
```csharp
38+
var response = await client.CreateAsync(invoice,
39+
includeNullValues: true,
40+
includeDefaultValues: true);
41+
```
42+
43+
### Create with Scripts
44+
45+
Run FileMaker scripts as part of the create operation. Scripts execute in this order: pre-request, pre-sort, then post-request (after the record is created).
46+
47+
```csharp
48+
var response = await client.CreateAsync(invoice,
49+
script: "AfterCreate", scriptParameter: "param1",
50+
preRequestScript: "BeforeCreate", preRequestScriptParam: "param2",
51+
preSortScript: "SortSetup", preSortScriptParameter: "param3");
52+
```
53+
54+
### Reading Script Results
55+
56+
The `ICreateResponse` contains an `ActionResponse` with script results:
57+
58+
```csharp
59+
var response = await client.CreateAsync(invoice,
60+
script: "AfterCreate", scriptParameter: "param");
61+
62+
var scriptResult = response.Response.ScriptResult;
63+
var scriptError = response.Response.ScriptError; // 0 = no error
64+
65+
var preReqResult = response.Response.ScriptResultPreRequest;
66+
var preSortResult = response.Response.ScriptResultPreSort;
67+
```
68+
69+
### Advanced: SendAsync with ICreateRequest
70+
71+
For full control, build a request manually:
72+
73+
```csharp
74+
var req = client.GenerateCreateRequest(invoice);
75+
req.Layout = "Invoices";
76+
req.Script = "AfterCreate";
77+
req.ScriptParameter = "param";
78+
79+
var response = await client.SendAsync(req);
80+
```

‎docs/deleting-records.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
layout: default
3+
parent: Guide
4+
nav_order: 5
5+
title: Deleting Records
6+
---
7+
8+
## Deleting Records
9+
10+
### Delete by Model Type
11+
12+
Delete using the layout from the model's `[DataContract]` attribute:
13+
14+
```csharp
15+
var response = await client.DeleteAsync<Invoice>(recordId);
16+
```
17+
18+
### Delete by Layout and Record ID
19+
20+
Specify the layout explicitly:
21+
22+
```csharp
23+
var response = await client.DeleteAsync(recordId, "Invoices");
24+
```
25+
26+
### Delete with Scripts
27+
28+
Use `SendAsync` with an `IDeleteRequest` to run scripts alongside a delete:
29+
30+
```csharp
31+
var req = client.GenerateDeleteRequest();
32+
req.Layout = "Invoices";
33+
req.RecordId = recordId;
34+
req.Script = "AfterDelete";
35+
req.ScriptParameter = "param";
36+
req.PreRequestScript = "BeforeDelete";
37+
req.PreRequestScriptParameter = "preParam";
38+
39+
var response = await client.SendAsync(req);
40+
```
41+
42+
### Reading Script Results
43+
44+
The `IDeleteResponse` contains an `ActionResponse` with script results:
45+
46+
```csharp
47+
var scriptResult = response.Response.ScriptResult;
48+
var scriptError = response.Response.ScriptError; // 0 = no error
49+
50+
var preReqResult = response.Response.ScriptResultPreRequest;
51+
var preSortResult = response.Response.ScriptResultPreSort;
52+
```

0 commit comments

Comments
 (0)