> ## Documentation Index
> Fetch the complete documentation index at: https://docs.powersync.com/llms.txt
> Use this file to discover all available pages before exploring further.

# .NET SDK (beta)

> Use PowerSync in .NET apps (beta).

<CardGroup cols={3}>
  <Card title="PowerSync SDK on NuGet" icon="nuget" href="https://www.nuget.org/packages/PowerSync.Common/">
    This SDK is distributed via NuGet
  </Card>

  <Card title="Source Code" icon="github" href="https://github.com/powersync-ja/powersync-dotnet">
    Refer to the `powersync-dotnet` repo on GitHub
  </Card>

  <Card title="API Reference (Coming soon)" icon="book">
    A full API Reference for this SDK is not yet available. This is planned for a future release.
  </Card>

  <Card title="Example Projects" icon="code" href="/intro/examples">
    Gallery of example projects/demo apps built with .NET PowerSync
  </Card>

  <Card title="Changelog" icon="megaphone" href="https://releases.powersync.com/announcements/powersync-net-sdk">
    Changelog for the SDK
  </Card>
</CardGroup>

<Note>
  This SDK is currently in a [**beta** release](/resources/feature-status). It is production-ready for tested use cases. APIs are stable and breaking changes will be communicated clearly.
</Note>

## Supported Frameworks and Targets

The PowerSync .NET SDK supports:

* **.NET Versions**: 6, 8, and 9
* **.NET Standard**: 2.0 (for compatibility with older libraries and frameworks)
* **.NET Framework**: Version 4.8 (requires additional configuration — see the package [README](https://github.com/powersync-ja/powersync-dotnet/tree/main?tab=readme-ov-file))
* **MAUI**: Cross-platform support for Android, iOS, Mac Catalyst, and Windows (targeting `net8.0` and `net9.0` mobile frameworks)
* **WPF**: Windows desktop applications
* **Console/CLI**: Windows (x64, ARM), macOS (x64, ARM), and Linux (x64, ARM)

**Current Limitations**:

* Blazor (web) platforms are not yet supported.

For more details, please refer to the package [README](https://github.com/powersync-ja/powersync-dotnet/tree/main?tab=readme-ov-file).

## SDK Features

* **Real-time streaming of database changes**: Changes made by one user are instantly streamed to all other users with access to that data. This keeps clients automatically in sync without manual polling or refresh logic.
* **Direct access to a local SQLite database**: Data is stored locally, so apps can read and write instantly without network calls. This enables offline support and faster user interactions.
* **Asynchronous background execution**: The SDK performs database operations in the background to avoid blocking the application’s main thread. This means that apps stay responsive, even during heavy data activity.
* **Query subscriptions for live updates**: The SDK supports query subscriptions that automatically push real-time updates to client applications as data changes, keeping your UI reactive and up to date.
* **Automatic schema management**: PowerSync syncs schemaless data and applies a client-defined schema using SQLite views. This architecture means that PowerSync SDKs can handle schema changes gracefully without requiring explicit migrations on the client-side.

## Quickstart

<Tabs>
  <Tab title="Common">
    For desktop/server/binary use-cases and WPF, add the [`PowerSync.Common`](https://www.nuget.org/packages/PowerSync.Common/) NuGet package to your project:

    ```bash theme={null}
    dotnet add package PowerSync.Common
    ```
  </Tab>

  <Tab title="MAUI">
    For MAUI apps, add both [`PowerSync.Common`](https://www.nuget.org/packages/PowerSync.Common/) and [`PowerSync.Maui`](https://www.nuget.org/packages/PowerSync.Maui/) NuGet packages to your project:

    ```bash theme={null}
    dotnet add package PowerSync.Common
    dotnet add package PowerSync.Maui
    ```
  </Tab>
</Tabs>

<Note>
  To install a specific version, use `--version` instead: `dotnet add package PowerSync.Common --version <version>`
</Note>

**Prerequisites**: To sync data between your client-side app and your backend source database, you must have completed the necessary setup for PowerSync, which includes connecting your source database to the PowerSync Service and deploying Sync Streams (or legacy Sync Rules) (steps 1-4 in the [Setup Guide](/intro/setup-guide)).

### 1. Define the Client-Side Schema

This refers to the <Tooltip tip="The client-side schema is typically mainly derived from your backend source database schema and Sync Streams / Sync Rules, but can also include other tables such as local-only tables.">schema</Tooltip> for the managed SQLite database exposed by the PowerSync Client SDKs, that your app can read from and write to. The schema is applied when the database is instantiated (as we'll show in the next step) — <Tooltip tip="Schema migrations are not required on the SQLite database due to the schemaless nature of the PowerSync protocol. Schemaless data is synced to the client-side SQLite database, and the schema is then applied to that data using SQLite views to allow for structured querying of the data. The exception to this is if you are using Raw Tables (see Advanced section of Client SDK docs)">no migrations are required</Tooltip>.

<Tip>
  **Generate schema automatically**

  In the [PowerSync Dashboard](https://dashboard.powersync.com/), select your project and instance and click the **Connect** button in the top bar to generate the client-side schema in your preferred language. The schema will be generated based off your Sync Streams/Rules.

  Similar functionality exists in the [CLI](/tools/cli).

  **Note:** The generated schema will not include an `id` column, as the client SDK automatically creates an `id` column of type `text`. Consequently, it is not necessary to specify an `id` column in your schema. For additional information on IDs, refer to [Client ID](/sync/advanced/client-id).
</Tip>

You can use [this example](https://github.com/powersync-ja/powersync-dotnet/blob/main/demos/CommandLine/AppSchema.cs) as a reference when defining your schema.

The types available are `text`, `integer` and `real`. These should map directly to the values produced by your [Sync Streams](/sync/streams/overview) (or legacy [Sync Rules](/sync/rules/overview)). If a value doesn't match, it is cast automatically. For details on how backend source database types are mapped to the SQLite types, see [Types](/sync/types).

#### Schema Definition Syntax

There are two supported syntaxes for defining the schema:

**Attribute-based (recommended)** — Annotate a C# class with `[Table]`, `[Column]`, and `[Index]` attributes. The same class can then be used directly as the result type in queries, so you define your data structure once:

```cs theme={null}
using PowerSync.Common.DB.Schema;
using PowerSync.Common.DB.Schema.Attributes;

[Table("todos"), Index("list", ["list_id"])]
public class Todo
{
    [Column("id")]
    public string TodoId { get; set; }

    [Column("list_id")]
    public string ListId { get; set; }

    [Column("created_at")]
    public string CreatedAt { get; set; }

    [Column("completed")]
    public bool Completed { get; set; }
    // ... other columns
}

public static Schema PowerSyncSchema = new Schema(typeof(Todo));

// The same Todo class is used for queries:
var todos = await db.GetAll<Todo>("SELECT * FROM todos");
```

<Note>
  Unlike the other syntaxes where PowerSync automatically creates an `id` column, the attribute-based syntax requires you to explicitly declare it. The SDK identifies the `id` property by looking for either a property named `id`, or any property with a `[Column("id")]` attribute (case-insensitive). Having none or more than one is an error.
</Note>

<Accordion title="Alternative: object initializer syntax">
  If you prefer to keep your schema definition separate from your data classes, you can use the object initializer syntax instead:

  ```cs theme={null}
  using PowerSync.Common.DB.Schema;

  class AppSchema
  {
      public static Table Todos = new Table
      {
          Name = "todos",
          Columns =
          {
              ["list_id"] = ColumnType.Text,
              ["created_at"] = ColumnType.Text,
              ["completed"] = ColumnType.Integer,
              // ... other columns
          },
          Indexes =
          {
              ["list"] = ["list_id"]
          }
      };

      public static Schema PowerSyncSchema = new Schema(Todos);
  }
  ```
</Accordion>

### 2. Instantiate the PowerSync Database

Next, you need to instantiate the PowerSync database. PowerSync streams changes from your backend source database into the client-side SQLite database, based on your [Sync Streams](/sync/streams/overview) (or legacy [Sync Rules](/sync/rules/overview)). In your client-side app, you can read from and write to the local SQLite database, whether the user is online or offline.

**Example**:

The initialization syntax differs slightly between the Common and MAUI SDKs:

<Tabs>
  <Tab title="Common">
    ```cs theme={null}
    using PowerSync.Common.Client;

    class Demo
    {
        static async Task Main()
        {
            var db = new PowerSyncDatabase(new PowerSyncDatabaseOptions
            {
                Database = new SQLOpenOptions { DbFilename = "tododemo.db" },
                Schema = AppSchema.PowerSyncSchema,
            });
            await db.Init();
        }
    }
    ```
  </Tab>

  <Tab title="MAUI">
    ```cs theme={null}
    using PowerSync.Common.Client;
    using PowerSync.Common.MDSQLite;
    using PowerSync.Maui.SQLite;

    class Demo
    {
        static async Task Main() 
        {
            // Ensures the DB file is stored in a platform appropriate location
            var dbPath = Path.Combine(FileSystem.AppDataDirectory, "maui-example.db");
            var factory = new MAUISQLiteDBOpenFactory(new MDSQLiteOpenFactoryOptions()
            {
                DbFilename = dbPath
            });

            var Db = new PowerSyncDatabase(new PowerSyncDatabaseOptions()
            {
                Database = factory, // Supply a factory
                Schema = AppSchema.PowerSyncSchema,
            });

            await db.Init();
        }
    }
    ```
  </Tab>
</Tabs>

### 3. Integrate with Your Backend

The PowerSync backend connector provides the connection between your application backend and the PowerSync client-side managed SQLite database. It is used to:

1. Retrieve an auth token to connect to the PowerSync instance.
2. Upload client-side writes to your backend API. Any writes that are made to the SQLite database are placed into an upload queue by the PowerSync Client SDK and automatically uploaded to your app backend (where you apply those changes to the backend source database) when the user is connected.

Accordingly, the connector must implement two methods:

1. [PowerSyncBackendConnector.FetchCredentials](https://github.com/powersync-ja/powersync-dotnet/blob/main/demos/CommandLine/NodeConnector.cs#L50) - This method is automatically invoked by the PowerSync Client SDK to obtain authentication credentials. The SDK caches credentials internally and only calls this method when needed (e.g. on initial connection or when the token is near expiry). See [When `fetchCredentials()` is Called](/configuration/app-backend/client-side-integration#when-fetchcredentials-is-called) for details, and [Authentication Setup](/configuration/auth/overview) for instructions on how the credentials should be generated.
2. [PowerSyncBackendConnector.UploadData](https://github.com/powersync-ja/powersync-dotnet/blob/main/demos/CommandLine/NodeConnector.cs#L72) - This method will be automatically invoked by the PowerSync Client SDK whenever it needs to upload client-side writes to your app's backend API. You need to implement how those writes are processed and uploaded in this method. See [When `uploadData()` is Called](/configuration/app-backend/client-side-integration#when-uploaddata-is-called) for details on triggers, throttling, and retry behavior, and [Writing Client Changes](/handling-writes/writing-client-changes) for considerations on the app backend implementation.

**Example**:

```cs theme={null}
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
using PowerSync.Common.Client;
using PowerSync.Common.Client.Connection;
using PowerSync.Common.DB.Crud;

public class MyConnector : IPowerSyncBackendConnector
{
    private readonly HttpClient _httpClient;
    
    // User credentials for the current session
    public string UserId { get; private set; }
    
    // Service endpoints
    private readonly string _backendUrl;
    private readonly string _powerSyncUrl;
    private string? _clientId;

    public MyConnector()
    {
        _httpClient = new HttpClient();
        
        // In a real app, this would come from your authentication system
        UserId = "user-123"; 
        
        // Configure your service endpoints
        _backendUrl = "https://your-backend-api.example.com";
        _powerSyncUrl = "https://your-powersync-instance.powersync.journeyapps.com";
    }

    public async Task<PowerSyncCredentials?> FetchCredentials()
    {
        try {
            // Implement fetchCredentials to obtain a JWT from your authentication service. 
            // See https://docs.powersync.com/configuration/auth/overview

            var authToken = "your-auth-token"; // Use a development token (see Authentication Setup https://docs.powersync.com/configuration/auth/development-tokens) to get up and running quickly

            // Return credentials with PowerSync endpoint and JWT token
            return new PowerSyncCredentials(_powerSyncUrl, authToken);
            
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error fetching credentials: {ex.Message}");
            throw;
        }
    }

    public async Task UploadData(IPowerSyncDatabase database)
    {
        // Get the next transaction to upload
        CrudTransaction? transaction;
        try
        {
            transaction = await database.GetNextCrudTransaction();
        }
        catch (Exception ex)
        {
            Console.WriteLine($"UploadData Error: {ex.Message}");
            return;
        }

        // If there's no transaction, there's nothing to upload
        if (transaction == null)
        {
            return;
        }

        // Get client ID if not already retrieved
        _clientId ??= await database.GetClientId();

        try
        {
            // Convert PowerSync operations to your backend format
            var batch = new List<object>();
            foreach (var operation in transaction.Crud)
            {
                batch.Add(new
                {
                    op = operation.Op.ToString(),  // INSERT, UPDATE, DELETE
                    table = operation.Table,
                    id = operation.Id,
                    data = operation.OpData
                });
            }

            // Send the operations to your backend
            var payload = JsonSerializer.Serialize(new { batch });
            var content = new StringContent(payload, Encoding.UTF8, "application/json");

            HttpResponseMessage response = await _httpClient.PostAsync($"{_backendUrl}/api/data", content);
            response.EnsureSuccessStatusCode();

            // Mark the transaction as completed
            await transaction.Complete();
        }
        catch (Exception ex)
        {
            Console.WriteLine($"UploadData Error: {ex.Message}");
            throw;
        }
    }
}
```

With your database instantiated and your connector ready, call `connect` to start syncing data with your backend:

```cs theme={null}
await db.Connect(new MyConnector());
await db.WaitForFirstSync(); // Optional, to wait for a complete snapshot of data to be available
```

<Tip>
  **Note**: This section assumes you want to use PowerSync to sync your backend source database with SQLite in your app. If you only want to use PowerSync to manage your local SQLite database without sync, instantiate the PowerSync database without calling `connect()` and refer to our [Local-Only](/client-sdks/advanced/local-only-usage) guide.
</Tip>

## Using PowerSync: CRUD functions

Once the PowerSync instance is configured you can start using the SQLite DB functions.

The most commonly used CRUD functions to interact with your SQLite data are:

* `PowerSyncDatabase.Get` - get (SELECT) a single row from a table.
* `PowerSyncDatabase.GetAll` - get (SELECT) a set of rows from a table.
* `PowerSyncDatabase.Watch` - execute a read query every time source tables are modified.
* `PowerSyncDatabase.Execute` - execute a write (INSERT/UPDATE/DELETE) query.

### Fetching a Single Item

The `Get` method executes a read-only (SELECT) query and returns a single result. It throws an exception if no result is found. Use `GetOptional` to return a single optional result (returns `null` if no result is found).

```cs theme={null}
// Define a result type with properties matching the schema columns (some columns omitted here for brevity)
// public class ListResult { public string id; public string name; public string owner_id; ... }

var list = await db.Get<ListResult>("SELECT * FROM lists WHERE id = ?", [listId]);
```

### Querying Items (PowerSync.GetAll)

The `GetAll` method returns a set of rows from a table.

```cs theme={null}
// Define a result type with properties matching the schema columns (some columns omitted here for brevity)
// public class ListResult { public string id; public string name; public string owner_id; ... }

var lists = await db.GetAll<ListResult>("SELECT * FROM lists");
```

### Watching Queries (PowerSync.Watch)

The `Watch` method executes a read query whenever a change to a dependent table is made. It returns an `IAsyncEnumerable` so you can use `await foreach` to consume results.

```csharp theme={null}
// Define a result type with properties matching the schema columns (some columns omitted here for brevity)
// public class ListResult { public string id; public string name; public string owner_id; ... }

// Optional cancellation token to stop watching
var cts = new CancellationTokenSource();

// Register listener synchronously on the calling thread...
var listener = db.Watch<ListResult>(
    "SELECT * FROM lists WHERE owner_id = ?",
    [ownerId],
    new SQLWatchOptions { Signal = cts.Token }
);

// ...then listen to changes on another thread (or await foreach directly if already in an async context)
_ = Task.Run(async () =>
{
    await foreach (var results in listener)
    {
        Console.WriteLine("Lists: ");
        foreach (var result in results)
        {
            Console.WriteLine($"{result.id}: {result.name}");
        }
    }
}, cts.Token);

// To stop watching, cancel the token: cts.Cancel();
```

### Mutations (PowerSync.Execute)

The `Execute` method can be used for executing single SQLite write statements.

```cs theme={null}
// And db.Execute for inserts, updates and deletes:
await db.Execute(
  "insert into lists (id, name, owner_id, created_at) values (uuid(), 'New User', ?, datetime())",
  [connector.UserId]
);
```

## Configure Logging

Enable logging to help you debug your app. By default, the SDK uses a no-op logger that doesn't output any logs. To enable logging, you can configure a custom logger using .NET's `ILogger` interface:

```cs theme={null}
using Microsoft.Extensions.Logging;
using PowerSync.Common.Client;

// Create a logger factory
ILoggerFactory loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddConsole();             // Enable console logging
    builder.SetMinimumLevel(LogLevel.Information);  // Set minimum log level
});

var logger = loggerFactory.CreateLogger("PowerSyncLogger");

var db = new PowerSyncDatabase(new PowerSyncDatabaseOptions
{
    Database = new SQLOpenOptions { DbFilename = "powersync.db" },
    Schema = AppSchema.PowerSyncSchema,
    Logger = logger
});
```

## Additional Usage Examples

For more usage examples including accessing connection status, monitoring sync progress, and waiting for initial sync, see the [Usage Examples](/client-sdks/usage-examples) page.

## Troubleshooting

See [Troubleshooting](/debugging/troubleshooting) for pointers to debug common issues.

## Supported Platforms

See [Supported Platforms -> .NET SDK](/resources/supported-platforms#net-sdk).

## Upgrading the SDK

To upgrade to the latest version of the PowerSync package, run the below command in your project folder:

<Tabs>
  <Tab title="Common">
    ```bash theme={null}
    dotnet add package PowerSync.Common
    ```
  </Tab>

  <Tab title="MAUI">
    ```bash theme={null}
    dotnet add package PowerSync.Common
    dotnet add package PowerSync.Maui
    ```
  </Tab>
</Tabs>