DEV Community: Sébastien Pertus

How to Secure Your TanStack React Start App with Light-Auth

Sébastien Pertus — Wed, 20 Aug 2025 14:47:42 +0000

Light-Auth is a lightweight authentication solution designed for simplicity and ease of integration.
It provides essential authentication features with minimal setup, making it ideal for React developers, prototypes, and SSR frameworks.

You can find an introduction to Light-Auth here: Light-Auth: Authentication for SSR Frameworks

✅ Why Use Light-Auth?

Quick Setup: Minimal configuration required.
Supports OAuth Providers: Google, GitHub, and more.
Lightweight: Minimal dependencies.
Extensible: Easily customize for advanced use cases.
Works Everywhere: Compatible with SSR frameworks like Next.js, Astro, SvelteKit, Nuxt, and TanStack Start.

🔐 How to Use Light-Auth with TanStack Start

This guide walks you through the steps to add authentication and authorization to your Tanstack Start application using Light-Auth.

👉 You can find the complete code for a sample Tanstack Start application here: Tanstack Start Sample with Light-Auth

1) Install Light-Auth

Once you have created your Tanstack Start application (you can follow this tutorial: Tanstack Start Build from Scratch), you can add Light-Auth for Tanstack using your preferred package manager:

npm -i @light-auth/tanstack-react-start

2) Add your OAUTH providers

Light-Auth uses Arctic providers

You will find the complete list of Arctic providers on the official website: Arctic v3

Each provider needs to be configure, usually with a ClientId, a Client Secret and a Redirect URI.

As an example, we are going to use a Google provider.

Note that Light-Auth can use multiple providers, but for sake of simplicity, we are going to use only one here.

Once you have configure your Google OAUTH2 from the google admin console, add a .env file at the root of your project:

GOOGLE_CLIENT_ID=<your_client_id_from_google_cloud>
GOOGLE_CLIENT_SECRET=<your_client_secret_from_google_cloud>
GOOGLE_REDIRECT_URI=http://localhost/api/auth/callback/google

LIGHT_AUTH_SECRET_VALUE=<any_random_secret_used_to_secure_server_cookies>

LIGHT_AUTH_SECRET_VALUE value is used to encrypt cookies, and is mandatory.

3) Configure vite

Add @light-auth/tanstack-react-start to the vite config as noExternal to avoid the SSR context loss.

If you want more info on why this step is mandatory, you can read more info here: SSR context loss

// file: "./vite.config.ts"

export default defineConfig({
  ...,
  ...,
  ssr: {
    noExternal: ['@light-auth/tanstack-react-start'],
  },
})

4) Configure Light-Auth

This file contains the authentication logic and configuration.
The exports consts are providers, handlers, signIn, signOut, getAuthSession, and getUser.

These constants are used throughout the application to manage authentication.

// file: "./lib/auth.ts"

import { Google} from "arctic";
import { CreateLightAuth } from "@light-auth/nextjs";

const googleProvider = {
  providerName: "google",
  arctic: new Google(
    process.env.GOOGLE_CLIENT_ID,
    process.env.GOOGLE_CLIENT_SECRET,
    process.env.GOOGLE_REDIRECT_URI
  ),
};

export const { providers, handlers, signIn, signOut, getAuthSession, getUser } = CreateLightAuth({
  providers: [googleProvider]
})

5) Add Light-Auth Handlers

This file contains the authentication handlers for the API.
These handlers are responsible for processing authentication requests and returning the appropriate responses.
The handlers are exported as GET and POST methods.

// file: "./routes/api/auth/$.tsx"

import { createServerFileRoute } from '@tanstack/react-start/server';
import { handlers } from "@/lib/auth";
export const ServerRoute = createServerFileRoute('/api/auth/$').methods(handlers)

That's it. Everything is now configured.
You just need now to implement your login page and use the exports constants everywhere you need them.

6) Add login page

This file contains the login page using a form action to login using your provider.

Note: You can also use client components to trigger the login process.
See the documentation Client Components for more information.

// file: "./routes/login.tsx"

import { createFileRoute } from '@tanstack/react-router'
import { createServerFn } from '@tanstack/react-start';
import { signIn } from '@/lib/auth';

export const Route = createFileRoute('/login')({
  component: RouteComponent,
})

export const actionSignIn = createServerFn().handler(() => signIn("google", "/profile"));


function RouteComponent() {
  return (
    <div>
      <form action={actionSignIn.url} method="POST">
        <button type="submit">login using a form action</button>
      </form>
    </div>
  );
}

7) Use Light-Auth in your Profile page

Retrieves the session information to check if user is authenticated or not and displays it.

// file: "./routes/profile.tsx"

import { createFileRoute, Link } from '@tanstack/react-router'
import { createServerFn } from '@tanstack/react-start';
import { getAuthSession as laGetAuthSession } from "@/lib/auth";

const getAuthSession = createServerFn({
  method: 'GET',
}).handler(() => {
  return laGetAuthSession()
})

export const Route = createFileRoute('/profile')({
  component: RouteComponent,
  loader: async () => {
    const session = await getAuthSession();
    return { session };
  },
})

function RouteComponent() {
  const state = Route.useLoaderData()
  const session = state.session;

  return (
    <div>
      {session != null ? (
        <div>
          <p>✅ You are logged in!</p>
          <div>Session Email: {session.email}</div>
          <div>Session Provider: {session.providerName}</div>
        </div>
      ) : (
        <div>
          <p>⚠️ You are not logged in</p>
          <a href="/login"> Go to Login Page </a>
        </div>
      )}
    </div>
  );
}

✅ Conclusion

By following these steps, you’ve successfully integrated Light-Auth into your TanStack React Start application.

This setup provides a secure, scalable, and easy-to-maintain authentication system with minimal configuration.

Next steps:

Add more OAuth providers (GitHub, Twitter, etc.)
Implement role-based access control
Secure API routes with session validation

For more details, visit the Light-Auth official website.

Light-Auth: A lightweight auth. sdk for SSR frameworks

Sébastien Pertus — Thu, 07 Aug 2025 11:14:00 +0000

Light-Auth is a lightweight authentication solution designed for simplicity and ease of integration.

It provides essential authentication features with minimal configuration, making it ideal for small projects, prototypes, or applications that require straightforward user sign-in functionality.

Features

Simple setup and configuration
Supports basic authentication flows
Minimal dependencies
Easily extensible for custom requirements
Server side an Client side components

Framework Compatibility

Light-Auth shines across your favorite frameworks! Whether you’re building with:

Framework	NPM Package	GitHub Sample
Next.js	light-auth-nextjs	Next.js Sample
Astro	light-auth-astro	Astro Sample
Nuxt	light-auth-nuxt	Nuxt Sample
SvelteKit	light-auth-sveltekit	SvelteKit Sample
Express	light-auth-express	Express Sample
Tanstack Start	light-auth-tanstack-react-start	Tanstack Start Sample

Light Auth integrates seamlessly, letting you add authentication with a sparkle ✨ to any stack!

Getting Started

This getting started is based on the light-auth-nextjs package.

You will find examples for all others frameworks in each relevant repository

The Light Auth documentation has also a lot of code examples for various scenario.

1) Installing Light Auth

npm -i @light-auth/nextjs

2) Configuring Light Auth

Light-Auth is using Arctic providers: Arctic is a collection of OAuth 2.0 clients for popular providers.

You will find the complete list of Arctic providers on the official website: Arctic v3

Each provider needs to be configure, usually with a ClientId, a Client Secret and a Redirect URI.

As an example, we are going to use a Google provider.

Note that Light-Auth can use multiple providers, but for sake of simplicity, we are going to use only one here.

Once you have configure your Google OAUTH2 from the google admin console, add a .env file at the root of your project:

GOOGLE_CLIENT_ID=<your_client_id_from_google_cloud>
GOOGLE_CLIENT_SECRET=<your_client_secret_from_google_cloud>
GOOGLE_REDIRECT_URI=http://localhost/api/auth/callback/google

LIGHT_AUTH_SECRET_VALUE=<any_random_secret_used_to_secure_server_cookies>

LIGHT_AUTH_SECRET_VALUE value is used to encrypt cookies, and is mandatory.

Now, you can add a new file to configure Light-auth.

The results from the CreateLightAuth call will be used everywhere else to allow you to login, logout, get session and user metadata.

You can place this file wherever you want.

// file: "./lib/auth.ts"

import { Google} from "arctic";
import { CreateLightAuth } from "@light-auth/nextjs";

const googleProvider = {
  providerName: "google",
  arctic: new Google(env.GOOGLE_CLIENT_ID, 
      env.GOOGLE_CLIENT_SECRET, 
      env.GOOGLE_REDIRECT_URI),
};

export const { providers, handlers, signIn, signOut, getAuthSession, getUser } 
     = CreateLightAuth({providers: [googleProvider]})

3) Adding Light Auth Handlers

Handlers are here to intercept all authentication requests used to authenticate your users:

// file: "./app/api/auth/[...lightauth].ts"

import { handlers } from "@/lib/auth";
export const { GET, POST } = handlers;

4) Adding login page

You have multiple way to launch the authentication process. For this example, we are going to use a Server Function.

You can also used a full client side technic, if you want to.

Check the official documentation for more on client side interaction.

// file: "./app/login.tsx"

import { signIn } from "@/lib/auth";

export default function LoginPage() {
  return (
    <div>
      <form
        action={async () => {
          "use server";
          await signIn("google", "/profile");
        }}
      >
        <button type="submit">login</button>
      </form>
    </div>
  );
}

5) Using Light Auth

Once your user is authenticated, you can use the Light-Auth SDK to access various information about the logged (or not) user.

In this small example, we are using the session to check if user is authenticated and can access privates ressources:

// file: "./app/profile.tsx"

import { getAuthSession, signIn  } from "@/lib/auth";

export default async function Home() {
  const session = await getAuthSession();

  return (
    <div>
      {session != null ? (
        <div>
          <p>✅ You are logged in!</p>
          <div>Session Email: {session.email}</div>
          <div>Session Provider: {session.providerName}</div>
        </div>
      ) : (
        <div>
            <p> You are not logged </p>
        </div>
      )}
    </div>
  );
}

If you need more info, do not hesitate to ping me @sebpertus

You can also check the complete documentation here: https://lightauth.github.io

Using DNS01 challenge and Let's Encrypt to secure your AKS kubernetes cluster

Sébastien Pertus — Fri, 12 Jun 2020 12:02:04 +0000

TL;DR;

This blog post is all about "how to get a certificate using the DNS01 challenge" to secure your Kubernetes cluster running inside AKS.

You will find the repository code source on github : https://github.com/Mimetis/AKS_DNS01Solver

To be able to continue, you need to :

Own a domain name.
Be able to create an NS record from within your domain provider to be able to redirect all that sub domain queries to Azure DNS Zone.
Have an Azure subscription to create your own AKS cluster.

Intoduction

The most common way to secure an AKS entry endpoint cluster (basically your ingress) is to allow only https queries through your ingress (like nginx or traefik)

A usefull pattern is to use the combo Let's Encrypt and Cert manager to get a valid certificate from Let's encrypt, that will be renewed over time, automatically.

Let's Encrypt uses the ACME protocol to verify that you control a given domain name and then to issue a valid certificate.

Solving challenges

In order for the ACME CA server to verify that a client owns the domain, a certificate is being requested for, the client must complete challenges.

We have mainly two types of challenges available:

HTTP01 challenge is completed by presented a computed key on a regular HTTP url endpoint.
DNS01 challenge is completed by presented a computed key that is present in a DNS TXT record.

HTTP01 problem

In some circumstances, you just want your cluster to be available using only a secure connection over https.

The main issue with the HTTP01 solving challenge is that you have to let an url endpoint opened on port 80.

IF you are considering this as a security issue, you may want to resolve your challenge, using the DNS01 challenge.

Using DNS01 challenge

We're going to explain how to implement a DNS01 challenge in an Azure environnement, using:

AKS as a kubernetes cluster.
NGINX as ingress.
Cert Manager as a certificate management controller.
Azure DNS Zone as a dns resolution engine.

Obviously we will use some useful (and almost mandatory is you are working with kubernetes) tools like kubectl and helm.

The sample application used is the Azure voting application sample that will be slightly modified to add an nginx controller as an ingress.

DNS zone

In this example, I'm working with my own domain called dotmim.com (I used to have a blog on this domain.. long time ago !)

I will create a sub domain that will redirect all the trafic for this sub domain to my DNS Zone.

First of all, you may want to create your Azure DNS zone.

Keep in mind that your dns zone should be a sub domain of your domain.

In the screenshot below, we will manage a subdomain called vote.dotmim.com:

Once created, just copy the Name server 1 property (in my case ns1-02.azure-dns.com.)

From my domain provider, i'm registering a new NS entry that will redirect everything to my DNS Zone:

You can check that the redirection is working by doing a quick ns lookup:

nslookup -type=SOA dotmim.com
Non-authoritative answer:
dotmim.com
        origin = ns1.amen.fr


nslookup -type=SOA vote.dotmim.com
Non-authoritative answer:
vote.dotmim.com
        origin = ns1-02.azure-dns.com

(Some informations have been removed for clarity)

As you can see the root domain is handled by my domain provider and the vote.* sub domain is now handled by my new created Azure DNS Zone.

nginx ingress controller

The application we want to deploy is quite simple and based on the Azure voting application sample.

You will find the deployment script here : https://github.com/Mimetis/AKS_DNS01Solver/vote.yaml

The only modification is that we will use an nginx ingress as entry point instead of exposing the vote application directly.

Adding nginx is quite straightforward using the official helm chart:

# Create a namespace for your ingress resources
kubectl create namespace ingress-basic

# Use Helm to deploy an NGINX ingress controller
helm install nginx stable/nginx-ingress \
    --namespace ingress-basic \
    --set controller.replicaCount=2 \
    --set controller.nodeSelector."beta\.kubernetes\.io/os"=linux \
    --set defaultBackend.nodeSelector."beta\.kubernetes\.io/os"=linux

cert-manager

to be able to manage everything, we are installing as well cert-manager on the cluster:

# Deploy custom resources definition
kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.14.1/cert-manager.crds.yaml

# create namespace for cert
kubectl create namespace cert-manager  

# Add repo
helm repo add jetstack https://charts.jetstack.io
helm repo update

# Label the ingress-basic namespace to disable resource validation
kubectl label namespace ingress-basic cert-manager.io/disable-validation=true

# Install cert manager
helm install cert-manager jetstack/cert-manager \
     --namespace cert-manager \
     --version v0.14.1 \
     --set ingressShim.defaultIssuerName=letsencrypt-staging \
     --set ingressShim.defaultIssuerKind=ClusterIssuer

Service principal

Once it's done, we need a service principal to be able to reach the DNS Zone from within our cluster.

For the sake of simplicity, I will create a simple service principal without any role assignement, but you may want to look at the cert-manager official documentation to ensure you have the least privileges assigned to your spn : Azure DNS configuration

Once created, we will save it as a secret in the AKS cluster.

# Create a service principal for DNS validation
$ az ad sp create-for-rbac --name spcertmanageridentity

Creating a role assignment under the scope of "/subscriptions/subid000-eeee-ffff-gggg-hhhhhhhhhhhh"
{
  "appId": "appid000-aaaa-bbbb-cccc-dddddddddddd",
  "displayName": "spcertmanageridentity",
  "name": "http://spcertmanageridentity",
  "password": "password-aaaa-bbbb-cccc-dddddddddddd",
  "tenant": "tenant00-aaaa-bbbb-cccc-dddddddddddd"
}

kubectl create secret generic azuredns-config --from-literal=client-secret=password-aaaa-bbbb-cccc-dddddddddddd -n cert-manager

DNS Issuer

This is where everything is happening.

Your DNS issuer is the configuration that will be used by cert manager to be able to create the TXT record requested by the ACME CA (Let's Encrypt)

Here is a DNS issuer used with the Let's Encrypt staging endpoint:

apiVersion: cert-manager.io/v1alpha2
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    email: yourname@youremail.com
    # Name of a secret used to store the ACME account private key
    privateKeySecretRef:
      name: letsencrypt
    # ACME DNS-01 provider configurations
    solvers:
    - dns01:
        azuredns:
          clientID: appid000-aaaa-bbbb-cccc-dddddddddddd
          clientSecretSecretRef:
            name: azuredns-config
            key: client-secret
          subscriptionID: subid000-eeee-ffff-gggg-hhhhhhhhhhhh
          tenantID: tenant00-aaaa-bbbb-cccc-dddddddddddd
          resourceGroupName: rgdns
          hostedZoneName: vote.dotmim.com
          environment: AzurePublicCloud

Do not hesitate to create all the cluster issuer you need: DNS with Let's Encrypt staging / DNS with Let's Encrypt production and so on...

You will use the one you need from the ingress configuration object.

kubectl apply -f dnsissuer.yaml

ingress

Now that we've deployed everything we need, just create an ingress with the correct values:

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: nginx
    ingress.kubernetes.io/ssl-redirect: "false"
    ingress.kubernetes.io/force-ssl-redirect: "false" 
    #nginx.ingress.kubernetes.io/rewrite-target: /
    cert-manager.io/cluster-issuer: letsencrypt-staging
  name: vote-ingress
spec:
  tls:
    - hosts:
        - vote.dotmim.com
      secretName: tls-secret
  rules:
    - host: vote.dotmim.com
      http:
        paths:
          - backend:
              serviceName: azure-vote-front
              servicePort: 80

Debug

Check that your certificate has been correctly issued, using the describe command on objects Certificate, CertificateRequest and Order :

(Once again, removing unrelevant part, for clarity)


kubectl describe cert tls-secret
Name:         tls-secret
Kind:         Certificate
Metadata:
  Owner References:
    Kind:                  Ingress
    Name:                  vote-ingress
Spec:
  Dns Names:
    vote.dotmim.com
  Issuer Ref:
    Group:      cert-manager.io
    Kind:       ClusterIssuer
    Name:       letsencrypt-staging
  Secret Name:  tls-secret
Events:
  Type    Reason     Age   From          Message
  ----    ------     ----  ----          -------
  Normal  Requested  8s    cert-manager  Created new CertificateRequest resource "tls-secret-1150149038"

The Certificate request:

kubectl describe  CertificateRequest tls-secret-1150149038
Name:         tls-secret-1150149038
Kind:         CertificateRequest
Metadata:
  Owner References:
    Kind:                  Certificate
    Name:                  tls-secret
Spec:
  Issuer Ref:
    Group:  cert-manager.io
    Kind:   ClusterIssuer
    Name:   letsencrypt-staging
Events:
  Type    Reason        Age   From          Message
  ----    ------        ----  ----          -------
  Normal  OrderCreated  28s   cert-manager  Created Order resource default/tls-secret-1150149038-248511818
  Normal  OrderPending  28s   cert-manager  Waiting on certificate issuance from order default/tls-secret-1150149038-248511818: ""

And eventually the Order :

kubectl describe order tls-secret-1150149038-248511818
Name:         tls-secret-1150149038-248511818
Kind:         Order
Metadata:
  Owner References:
    Kind:                  CertificateRequest
    Name:                  tls-secret-1150149038
Spec:
  Dns Names:
    vote.dotmim.com
  Issuer Ref:
    Group:  cert-manager.io
    Kind:   ClusterIssuer
    Name:   letsencrypt-staging
Status:
  Certificate:   LS0tLS1CRUdJTiBDRVJUSU....
Events:
  Type    Reason    Age   From          Message
  ----    ------    ----  ----          -------
  Normal  Created   113s  cert-manager  Created Challenge resource "tls-secret-1150149038-248511818-2518637675" for domain "vote.dotmim.com"
  Normal  Complete  49s   cert-manager  Order completed successfully

Once you've reached that point, your certificate has been issued correctly. You can check once again the certificate and confirms it's correcty configured and downloaded in your cluster:

(base) spertus@MSI2019:~/cert$ kubectl describe cert tls-secret
Name:         tls-secret
Kind:         Certificate
Metadata:
Spec:
Status:
  Conditions:
    Last Transition Time:  2020-06-12T09:57:10Z
    Message:               Certificate is up to date and has not expired
    Reason:                Ready
  Not After:               2020-09-10T08:57:10Z
Events:
  Type    Reason     Age                 From          Message
  ----    ------     ----                ----          -------
  Normal  Requested  10m                 cert-manager  Created new CertificateRequest resource "tls-secret-1150149038"
  Normal  Issued     9m25s (x2 over 8d)  cert-manager  Certificate issued successfully

Last step: Redirection

Now that you're able to reach your https entry point, don't forget to redirect all the trafic to your AKS cluster:

As you can see, I'm able to reach my vote application, using an HTTPS connection and a staging Let's Encrypt certificate !

Part 2: How to Synchronize relational databases with Dotmim.Sync

Sébastien Pertus — Wed, 19 Feb 2020 18:42:27 +0000

This post is part of a series about Dotmim.Sync on how to synchronize relations databases between a server hub and multiple client members:

Part 1: Introduction to Dotmim.Sync: Hello Sync !
Part 2: Protecting your hub behind a web API, through ASP.Net Core Web Api

In Part 1, we saw the most straightforward way to synchronize a server hub database with any kind of client database.
This first sample was based on a simple tcp connection between the server and the client.
Obviously, in a real world scenario, you don't expose your hub database directly.

Rather than exposing your database to the world, it could be better to protect it via a web proxy, usually a Web API.

To sum up, in Part 1, we saw how to use the SqlSyncProvider and SqliteSyncProvider providers to communicate with our databases (client and server), then we saw how to use a SyncAgent instance to launch a direct synchronization over tcp.

Today we are going to see how we can use the WebRemoteOrchestrator proxy from the client side and the WebServerAgent from the server side, to allow a smooth sync process from any client and our server, through a web api, managed by a simple ASP.Net Core Web Api project.

As a reminder, here is the console application we've created.
It's our base project:

private static async Task SynchronizeAdventureWorksAsync()
{
    var serverProvider = new SqlSyncProvider(GetDatabaseConnectionString("AdventureWorks"));
    var clientProvider = new SqliteSyncProvider("advworks.db");

    var setup = new SyncSetup("ProductCategory", "ProductModel", "Product", "Address", "Customer", "CustomerAddress", "SalesOrderHeader", "SalesOrderDetail");

    var agent = new SyncAgent(clientProvider, serverProvider);

    var progress = new SynchronousProgress<ProgressArgs>(s => 
            Console.WriteLine($"{s.Context.SyncStage}:\t{s.Message}"));

    do
    {
        Console.Clear();
        Console.WriteLine("Sync Start");
        try
        {
            var syncContext = await agent.SynchronizeAsync(setup, progress:progress);
            Console.WriteLine(syncContext);
        }
        catch (Exception e)
        {
            Console.WriteLine(e.Message);
        }

    } while (Console.ReadKey().Key != ConsoleKey.Escape);
}

Now, we're going to separate the server side and the client side.

Server Side

First of all, we need to create a Web API project to support our server hub proxy.
You have multiples choices to create a Web API project within .Net Core:

Using the CLI
Using Visual Studio
Using Visual Studio Code

You have a complete tutorial available here : https://docs.microsoft.com/en-us/aspnet/core/tutorials/first-web-api

Create the Web Api project

For this sample, we can use eiter the command lines or the Visual Studio wizard:

Command line:

dotnet new webapi -o DotmimSyncWebServer

Visual Studio Wizard:

Once restored, here is our final folder architecture:

Install the Dotmim.Sync packages

Now, we need to add all the Dotmim.Sync components we need on the server side:

A SqlSyncProvider for handling the communication between our Sql Server hub instance and the exposed web API.
A WebRemoteOrchestrator proxy that will encapsulate all the call to the sync provider, using a Serializer (Json as default) to send and receive messages through http.

Using nuget, here are our final web project dependencies:

Obviously, you can add these nuget packages, through the console, if you're using Visual Studio Code:

dotnet add package Dotmim.Sync.SqlServer
dotnet add package Dotmim.Sync.Web.Server

Create a new empty sync controller

Then, we can create an empty controller called SyncController inside the ./Controllers folder (you can delete the generated WeatherForecast controller if you want)

namespace DotmimSyncWebServer.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class SyncController : ControllerBase
    {
    }
}

Add the connection string to config file

Of course, we need to connect to the database, and we don't want to hard code the connection string.
We can add this value to the appsettings.json file, already available in your root folder:

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=(localdb)\\mssqllocaldb; Initial Catalog=AdventureWorks; Integrated Security=true;"
  },

  "AllowedHosts": "*"
}

Using Dependency injection to add the Sql Provider

We are using a default ASP.Net Core web template. So far, dependency injection is something really important and used a lot.
We will use the same approach to create our sync process.

The Server side is responsible of designing your sync schema.
Once defined, this schema will be propagated to any client requesting it.

Here is ourConfigureServices() method in the ./startup.cs file:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    // [Required] Mandatory to be able to handle multiple sessions
    services.AddDistributedMemoryCache();
    services.AddSession(options => options.IdleTimeout = TimeSpan.FromMinutes(30));

    // [Required] Get a connection string for your server data source
    var connectionString = Configuration.GetSection("ConnectionStrings")["DefaultConnection"];

    // [Optional] Set the web server Options
    var options = new WebServerOptions()
    {
        BatchDirectory = Path.Combine(SyncOptions.GetDefaultUserBatchDiretory(), "server"),
    };


    // [Required] Create the setup used for your sync process
    var tables = new string[] {"ProductCategory", "ProductModel", "Product",
            "Address", "Customer", "CustomerAddress", "SalesOrderHeader", "SalesOrderDetail" };

    // [Optional] Defines the schema prefix and suffix for all generated objects
    var setup = new SyncSetup(tables)
    {
        // optional :
        StoredProceduresPrefix = "server",
        StoredProceduresSuffix = "",
        TrackingTablesPrefix = "server",
        TrackingTablesSuffix = ""
    };

    // [Required] add a SqlSyncProvider acting as the server hub
    services.AddSyncServer<SqlSyncProvider>(connectionString, setup, options);
}

Notice that:

We need a session system to handle multiple clients. That's why we're adding services.AddSession().
Only tables and connection string are mandatory. Everything else is optional.
We're using the AddSyncServer() method to inject our provider in the Dependency Injection container.

Adding handler to our Sync controller

The sync controller is really easy to implement, since everything is already handle under the cover.

We just need to:

Create a Post method.
Get our WebServerAgent instance from the dependency injection container, and then call the HandleRequestAsync() method.
[Optional]: Create a Get method to show a default page when you call the /sync web page through your browser.

So far, here is the final SyncController code source:

[Route("api/[controller]")]
[ApiController]
public class SyncController : ControllerBase
{
    private WebServerAgent webServerAgent;

    // Injected thanks to Dependency Injection
    public SyncController(WebServerAgent webServerAgent) => this.webServerAgent = webServerAgent;

    /// <summary>
    /// [Optional] This Get request is just here to show a default page
    /// </summary>
    [HttpGet]
    public async Task Get()
    {
        await this.HttpContext.WriteHelloAsync(webServerAgent);
    }

    /// <summary>
    /// [Required] This Post request is called by the all Dotmim.Sync.Web.Client apis
    /// </summary>
    [HttpPost]
    public async Task Post()
    {
        await webServerAgent.HandleRequestAsync(this.HttpContext);
    }
}

That's all you need !

If you launch the DotmimSyncWebServer project and point to the /api/sync web page, you should have this kind of page:

Note: As you can see, a lot of confidential information are shown here.

This information disappears when you go into production and your environment variable is set to production: "ASPNETCORE_ENVIRONMENT": "Production"
You can disable it by removing the public async Task Get() method from your sync controller

Client Side

The client side is pretty the same as our starter project.
We just need to:

Add a the Dotmim.Sync.Web.Client package to be able to use the WebRemoteOrchestrator remote proxy.
Change our server provider from SqlServerProvider to WebRemoteOrchestrator
[Optional] : Remove our dependency to Dotmim.Sync.SqlServer since we are not using it anymore.

Here is the final result:

var serverOrchestrator = new WebRemoteOrchestrator("https://localhost:44358/api/sync");
var clientProvider = new SqliteSyncProvider("advworks.db");;

// Using the IProgress<T> pattern to handle progession dring the synchronization
var progress = new SynchronousProgress<ProgressArgs>(s => Console.WriteLine($"{s.Context.SyncStage}:\t{s.Message}"));

// Creating an agent that will handle all the process
var agent = new SyncAgent(clientProvider, serverOrchestrator);

do
{
    // Launch the sync process
    var s1 = await agent.SynchronizeAsync(progress);
    // Write results
    Console.WriteLine(s1);

} while (Console.ReadKey().Key != ConsoleKey.Escape);

Console.WriteLine("End");

As you can see here, no tables are specified from the client side. Everything related to the schema is handled by the server side.

Don't forget to run your web server api, before launching your sync.
Eventually, you should have something like this:

If you need more information on the Dotmim.Sync framework, do not hesitate to reach me out on twitter @sebpertus

The full documentation is available here : https://mimetis.github.io/Dotmim.Sync

The source code is hosted on Github here : https://github.com/Mimetis/Dotmim.Sync

Happy sync !

Seb

How to Synchronize relational databases with Dotmim.Sync

Sébastien Pertus — Tue, 04 Feb 2020 17:41:15 +0000

This post is part of a series about Dotmim.Sync on how to synchronize relations databases between a server hub and multiple client members:

Part 1: Introduction to Dotmim.Sync: Hello Sync !
Part 2: Protecting your hub behind a web API, through ASP.Net Core Web Api

You say ... Dotmim... Sync ?

Back in the days, Microsoft released a full C# framework to allow databases synchronization, called the Sync Framework.
Today, (part of) this framework is open source but it lacks a lot of features to meet current mobile development needs, and a solid cross platform compatibility (and to be honest, a better ease of implementation without any code generation and pre-work)

The Dotmim.Sync framework is inspired from this old framework, without all the complications, glitches or code generation and adding some cool features.

The Dotmim.Sync framework works on all platforms supporting .Net Standard 2.0 librairies.
You can use it in a .Net Core application running on Windows or Linux, or you can use it embedded in your Xamarin application for iOS or Android.

Many features are available through this framework:

Multi databases support (SQL Server, MYSQL, SQLite)
Conflict resolution
Snapshot initialization
Filters
Custom serializers
Mode TCP and HTTP through ASP.NET Core Web API
Sync Direction (Bidirectional, DownloadOnly, UploadOnly)
SQL Server only: Support of change tracking / bulk operations with TVP

And more to come :)

Multi Databases	Cross Plaform	.Net Standard 2.0

Hello Sync !

One of the main objectives of the Dotmim.Sync framework is to be able to write your first synchronization with less than 5 lines of code.

Let's do it.

What you need so far for your first "Hello Sync" project:

A SQL Server / MySQL database up and running : Use this AdventureWorks script if you need something for testing purpose (and all the samples will be based on this database)
A blank console application on top of .Net Core with the Dotmim.Sync nuget packages installed (depending on the targeted databases)

We're going to create a sync between a server database hosted on SQL Server and a SQLite client database.

The Dotmim.Sync framework is built on database providers.
For instance, if you need to sync a SQL Server database, you will have to install the SqlSyncProvider provider.
For MySql, use the MySqlSyncProvider provider and of course for SQLite, the SqliteSyncProvider provider.
Each provider will manage the communication between the Dotmim.Sync core components and your database.
More providers will be (hopefully) developed later (like Oracle or PostgreSQL)

Now you have everything installed, let's go coding !

We need:

A SqlSyncProvider to communicate with the server databse.
A SqliteSyncProvider to communicate with the client database.
A SyncSetup containing the tables you want to synchronize.
A SyncAgent that will orchestrate the whole sync processus.


 csharp
var serverProvider = new SqlSyncProvider(GetDatabaseConnectionString("AdventureWorks"));
var clientProvider = new SqliteSyncProvider("advworks.db");

var setup = new SyncSetup("ProductCategory", "ProductModel", "Product", "Address", "Customer", "CustomerAddress", "SalesOrderHeader", "SalesOrderDetail");

var agent = new SyncAgent(clientProvider, serverProvider);

var syncContext = await agent.SynchronizeAsync(setup);
Console.WriteLine(syncContext);

As you can see, your SyncAgent instance has references on both server side and client side, plus the tables list.
Once initialized, just called the asynchronous method SynchronizeAsync() and you're done !

The result from this first run should looks like this:


 bash
Synchronization done.
        Total changes downloaded: 2752
        Total changes uploaded: 0
        Total conflicts: 0
        Total duration :0:0:4.280
Done

First synchronization done, with 5 lines of code :)

Note: The SQLite database did not exists before the sync process happened.
During the first sync, the Dotmim.Sync has:

1) Created the SQLite database, get the schema, created all the tables, then created all the required components (One tracking table per "synced" table, three triggers on each table)

2) Get all the data from the server and applied them in the SQLite database

Hello Sync V2

The next versin of this sample will use some nice features to get some feedbacks from your client database.

As SynchronizeAsync() is an async method, we can use a IProgress<T> to get feedbacks during the active sync:


 csharp
var progress = new SynchronousProgress<ProgressArgs>(s => Console.WriteLine($"{s.Context.SyncStage}:\t{s.Message}"));

var syncContext = await agent.SynchronizeAsync(progress);

And because we want to run the sync again and again, we can make a nice do while loop, with a little try catch to ensure the application won't crash for some reasons :)

Here is the full code:


 csharp
private static async Task SynchronizeAdventureWorksAsync()
{
    var serverProvider = new SqlSyncProvider(GetDatabaseConnectionString("AdventureWorks"));
    var clientProvider = new SqliteSyncProvider("advworks.db");

    var setup = new SyncSetup("ProductCategory", "ProductModel", "Product", "Address", "Customer", "CustomerAddress", "SalesOrderHeader", "SalesOrderDetail");

    var agent = new SyncAgent(clientProvider, serverProvider);

    var progress = new SynchronousProgress<ProgressArgs>(s => 
            Console.WriteLine($"{s.Context.SyncStage}:\t{s.Message}"));

    do
    {
        Console.Clear();
        Console.WriteLine("Sync Start");
        try
        {
            var syncContext = await agent.SynchronizeAsync(setu, progress);
            Console.WriteLine(syncContext);
        }
        catch (Exception e)
        {
            Console.WriteLine(e.Message);
        }

    } while (Console.ReadKey().Key != ConsoleKey.Escape);
}

And now, before launching again, let's add a new ProductCategory in the server database, and update a product:


 sql
Use AdventureWorks;
Update Product set Name = 'HL Road Frame - Black, 58 V2' where ProductId = 680;
Insert into ProductCategory (Name) Values ('Mono wheels');

Then launch again the sync process, you should have this result:


 bash
Sync Start
BeginSession:   18:11:24.281
ScopeLoading:   18:11:24.410     Id:932af0e6-1083-4ec4-8b39-40453e3bc586 LastSync:04/02/2020 16:49:35 LastSyncDuration:42806712
TableChangesSelected:   18:11:24.732     ProductCategory Upserts:0 Deletes:0 TotalChanges:0
TableChangesSelected:   18:11:24.732     ProductModel Upserts:0 Deletes:0 TotalChanges:0
TableChangesSelected:   18:11:24.734     Product Upserts:0 Deletes:0 TotalChanges:0
TableChangesSelected:   18:11:24.735     Address Upserts:0 Deletes:0 TotalChanges:0
TableChangesSelected:   18:11:24.736     Customer Upserts:0 Deletes:0 TotalChanges:0
TableChangesSelected:   18:11:24.737     CustomerAddress Upserts:0 Deletes:0 TotalChanges:0
TableChangesSelected:   18:11:24.738     SalesOrderHeader Upserts:0 Deletes:0 TotalChanges:0
TableChangesSelected:   18:11:24.739     SalesOrderDetail Upserts:0 Deletes:0 TotalChanges:0
TableChangesApplied:    18:11:25.415     ProductCategory State:Modified Applied:1 Failed:0
TableChangesApplied:    18:11:25.418     Product State:Modified Applied:1 Failed:0
DatabaseChangesApplied: 18:11:25.421     Changes applied on database main: Applied: 2 Failed: 0
ScopeSaved:     18:11:25.433     Id:932af0e6-1083-4ec4-8b39-40453e3bc586 LastSync:04/02/2020 17:11:25 LastSyncDuration:11541150
EndSession:     18:11:25.434
Synchronization done.
        Total changes downloaded: 2
        Total changes uploaded: 0
        Total conflicts: 0
        Total duration :0:0:1.154

Based on this running application, you can now test some inserts or deletes in both databases, and see the results in your console !

If you need more information on the Dotmim.Sync framework, do not hesitate to reach me out on twitter @sebpertus

The full documentation is available here : https://mimetis.github.io/Dotmim.Sync

The source code is hosted on Github here : https://github.com/Mimetis/Dotmim.Sync

Happy sync !

Seb