C# SDK

Install, configure, and handle lifecycle and errors with the Viio Sync API 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

PropertyRequiredDefaultDescription
EndpointYesAbsolute HTTPS Sync API endpoint; HTTP is allowed only for loopback development
AuthenticationYesAPI-key or Viio-managed authentication
MaxReceiveMessageSizeNo16 MiBMaximum response-message size accepted by the client
MaxSendMessageSizeNogRPC defaultMaximum request-message size
TimeoutNo100 secondsPer-operation timeout
HttpMessageHandlerFactoryNoSDK defaultFactory 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.

MemberDescription
BatchIdServer-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

ExceptionMeaning
SyncApiBatchAlreadyInProgressExceptionAnother batch owns the installation lock
SyncApiProtocolExceptionThe server rejected an SDK operation
SyncApiAuthenticationExceptionAuthentication could not produce a usable credential
Grpc.Core.RpcExceptionTransport or server RPC failure
ArgumentExceptionInvalid client input or configuration
InvalidOperationExceptionThe 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.