C# SDK
Last updated
This guide covers behavior specific to Viio.SyncApi.Sdk 1.1.0. For record types and properties, use the Model Reference.
Installation
dotnet add package Viio.SyncApi.Sdk --version 1.1.0
The package targets .NET 10.
Usage
using Viio.SyncApi;
using Viio.SyncApi.V1.Contracts;
using var client = new SyncApiClient(
new SyncApiClientOptions(
new Uri("https://sync.viio.io"),
SyncApiAuthentication.ApiKey(apiKey)
)
);
using var batch = await client.StartBatch(installationId, cancellationToken);
await batch.Write(
new SyncRecordsRequest
{
Accounts = new AccountRecords
{
Records =
{
new Account
{
Generic = new GenericAccountDetails
{
Id = "account-1",
Email = "person@example.com",
},
},
},
},
},
cancellationToken
);
await batch.Complete(cancellationToken);
Client Configuration
| Property | Required | Default | Description |
|---|---|---|---|
Endpoint | Yes | — | Absolute HTTPS Sync API endpoint; HTTP is allowed only for loopback development |
Authentication | Yes | — | API-key or Viio-managed authentication |
MaxReceiveMessageSize | No | 16 MiB | Maximum response-message size accepted by the client |
MaxSendMessageSize | No | gRPC default | Maximum request-message size |
Timeout | No | 100 seconds | Per-operation timeout |
HttpMessageHandlerFactory | No | SDK default | Factory for proxies, custom certificates, or test transports |
Customer-managed integrations use SyncApiAuthentication.ApiKey(apiKey). The key must have the integration:sync permission and belong to the target installation's workspace.
Batch Lifecycle
SyncApiBatch implements ISyncApiBatch and IDisposable.
| Member | Description |
|---|---|
BatchId | Server-generated batch identifier |
Write(request, cancellationToken) | Send one typed collection |
Complete(cancellationToken) | Complete the batch and make the local handle terminal |
Abort(cancellationToken) | Abort the batch and make the local handle terminal |
Dispose() | Release local resources without completing or aborting the server batch |
Writes are serialized. A successful completion or abort rejects later operations on the same batch object.
Error Handling
| Exception | Meaning |
|---|---|
SyncApiBatchAlreadyInProgressException | Another batch owns the installation lock |
SyncApiProtocolException | The server rejected an SDK operation |
SyncApiAuthenticationException | Authentication could not produce a usable credential |
Grpc.Core.RpcException | Transport or server RPC failure |
ArgumentException | Invalid client input or configuration |
InvalidOperationException | The batch was already completed or aborted |
For retry and abort guidance, see the Quickstart.
Requests and Models
Write accepts SyncRecordsRequest. Set exactly one typed collection per call; the SDK adds BatchId automatically.
The dedicated Model Reference lists every supported collection and record property, including its C# name, type, and requiredness.