DotMim.Sync Documentation

DotMim.Sync (DMS) is a framework designed for synchronizing relational databases. It is built on top of .NET 8 and is compatible with .NET Standard 2.0, making it suitable for various platforms including IoT, Xamarin, UWP, and standard .NET applications.

Key features include:

• Multi-Database Support: Works across different database engines.
• Cross-Platform: Compatible with multiple operating systems and runtimes.
• High Performance: Designed for fast synchronization of changes.

When using HTTP architecture, DMS utilizes two components to handle data transmission:

1. Serializer: Transforms a database row into a serialized stream. The default is JSON.
2. Converter: Converts data types (e.g., converting a byte[] to a base64 string). DMS does not use default converters and relies on the serializer's default converter.

Note: These components are only relevant when using an HTTP architecture.

When clients are not on the same local network as the server (e.g., mobile devices), synchronization must occur over HTTP rather than TCP. In this scenario, the standard RemoteOrchestrator cannot be used because it expects a direct TCP connection. Instead, DMS uses a proxy pattern involving two new components:

• WebRemoteOrchestrator: Runs on the client side. It acts as an orchestrator for the SyncAgent but generates HTTP requests containing the synchronization payload instead of direct database commands.
• WebServerAgent: Runs on the server side, typically hosted within an ASP.NET Core Web API. It receives the incoming HTTP requests from the WebRemoteOrchestrator and translates them into calls to the server-side provider.

This architecture allows the server-side database to remain protected behind a web API.

Dotmim.Sync uses two primary configuration objects to define the synchronization model:

• SyncSetup: Contains parameters related to your database schema. These are shared between the server and all clients. In Http mode, the server defines the SyncSetup parameters and sends them to the clients.
• SyncOptions: Contains parameters that are not shared between the server and the clients (local-only settings).

Use SyncSetup to define which tables, columns, and rows are part of the synchronization scope.

You can control how the synchronization engine handles errors during the ApplyChanges phase using the ErrorResolution enum. This can be configured globally via the SyncOptions.ErrorResolutionPolicy property or dynamically per error using the OnApplyChangesErrorOccured interceptor on the LocalOrchestrator (or RemoteOrchestrator).

When an error occurs, the interceptor provides an args object containing the Exception, the ErrorRow, and a Resolution property that you must set to determine the next step.

agent.LocalOrchestrator.OnApplyChangesErrorOccured(args =>
{
    // Handle error logic here
    args.Resolution = ErrorResolution.ContinueOnError;
});

Horizontal filtering allows you to remove specific rows from the source during synchronization. You achieve this by creating a SetupFilter instance for a specific table and adding it to your SyncSetup.Filters collection.

To implement a filter, you must:

1. Define the target table in the SetupFilter constructor.
2. Register parameters using .AddParameter().
3. Define how those parameters map to columns using .AddWhere().
4. (Optional) Use .AddJoin() to link the target table to other tables that contain the filtering criteria.

This is useful when you only want to synchronize a subset of data (e.g., only customers from a specific city).

var setup = new SyncSetup(new string[] { "Table1", "Table2" });
var filter = new SetupFilter("Table1");
// ... configure parameters and where clauses ...
setup.Filters.Add(filter);

The SyncSetup object allows you to define the scope of your synchronization. You can either pass a simple array of table names to SynchronizeAsync() (which creates a default SyncSetup automatically) or provide a fully customized SyncSetup instance.

Customizing SyncSetup allows you to control schemas, column filtering, row filtering, and naming conventions for database objects.

// Option 1: Automatic setup using only table names
var tables = new string[] {"Product", "Customer"};
var agent = new SyncAgent(clientProvider, serverProvider);
var r = await agent.SynchronizeAsync(tables);

// Option 2: Manual setup for full customization
var setup = new SyncSetup("Product", "Customer");
var agent = new SyncAgent(clientProvider, serverProvider);
var r = await agent.SynchronizeAsync(setup);