> ## Documentation Index > Fetch the complete documentation index at: https://powersync-sync-streams-nav.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # .NET SDK (beta) > Use PowerSync in .NET apps (beta). ```text Build with AI icon="sparkles" wrap theme={null} Install the PowerSync Agent Skills with: npx skills add powersync-ja/agent-skills. Then follow the skills to onboard this project to PowerSync using the .NET SDK. ``` This SDK is distributed via NuGet Refer to the `powersync-dotnet` repo on GitHub Full API reference for the SDK Gallery of example projects/demo apps built with .NET PowerSync Changelog for the SDK This SDK is currently in a [**beta** release](/resources/feature-status). It is production-ready for tested use cases. APIs are stable, and we communicate breaking changes clearly. ## 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, which 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, see 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 handle schema changes without explicit migrations on the client side. ## Quickstart 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 ``` 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 ``` To install a specific version, use `--version` instead: `dotnet add package PowerSync.Common --version ` **Prerequisites:** Before you start, connect your source database to the PowerSync Service and deploy Sync Streams. These are steps 1-4 in the [Setup Guide](/intro/setup-guide). ### 1. Define the Client-Side Schema The client-side schema defines the tables and columns of the SQLite database that the PowerSync client SDK manages and that your app reads from and writes to. It is usually derived from your backend database schema and your [Sync Streams](/sync/streams/overview), and it can also include [local-only tables](/client-sdks/advanced/local-only-usage). You apply the schema when you instantiate the database in the next step. Schema migrations are not required. The SDK syncs schemaless data and applies the schema to that data with SQLite views. The exception is [raw tables](/client-sdks/advanced/raw-tables), which you create and migrate yourself. **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 is generated from your Sync Streams. The [CLI](/tools/cli) offers the same function. The generated schema does not include an `id` column. The client SDK creates an `id` column of type `text` automatically, so you do not need to declare it. See [Client ID](/sync/advanced/client-id) for details. 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 available column types are `text`, `integer`, and `real`. These should match the values produced by your Sync Streams. If a value does not match, it is cast automatically. For details on how source database types map to 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]`](https://powersync-ja.github.io/powersync-dotnet/api/PowerSync.Common.DB.Schema.Attributes.TableAttribute.html), [`[Column]`](https://powersync-ja.github.io/powersync-dotnet/api/PowerSync.Common.DB.Schema.Attributes.ColumnAttribute.html), and [`[Index]`](https://powersync-ja.github.io/powersync-dotnet/api/PowerSync.Common.DB.Schema.Attributes.IndexAttribute.html) 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("SELECT * FROM todos"); ``` 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. 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); } ``` ### 2. Instantiate the PowerSync Database Next, instantiate the PowerSync database. PowerSync streams changes from your backend source database into the client-side SQLite database, based on your Sync Streams. Your app reads from and writes to this local database whether the user is online or offline. **Example:** The initialization syntax differs slightly between the Common and MAUI SDKs: ```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(); } } ``` ```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(); } } ``` ### 3. Integrate with Your Backend The backend connector connects the PowerSync client SDK to your application backend. The SDK uses it to: 1. Get an auth token to connect to the PowerSync instance. 2. Upload client-side writes to your backend API. The SDK places every write to the SQLite database in an upload queue and uploads the queue to your backend when the user is connected. Your backend then applies the changes to the source database. The connector must implement two methods: 1. [IPowerSyncBackendConnector.FetchCredentials](https://powersync-ja.github.io/powersync-dotnet/api/PowerSync.Common.Client.Connection.IPowerSyncBackendConnector.FetchCredentials.html) - The SDK calls this method to get authentication credentials. It caches the credentials and calls the method again only when needed, for example on the first 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 how to generate credentials. 2. [IPowerSyncBackendConnector.UploadData](https://powersync-ja.github.io/powersync-dotnet/api/PowerSync.Common.Client.Connection.IPowerSyncBackendConnector.UploadData.html) - The SDK calls this method whenever it has client-side writes to upload to your backend API. Implement how those writes are processed and uploaded. See [When `uploadData()` is Called](/configuration/app-backend/client-side-integration#when-uploaddata-is-called) for triggers, throttling, and retry behavior, and [Writing Client Changes](/handling-writes/writing-client-changes) for 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 = "[Your backend API URL]"; _powerSyncUrl = "https://your-powersync-instance.powersync.journeyapps.com"; } public async Task 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(); 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`](https://powersync-ja.github.io/powersync-dotnet/api/PowerSync.Common.Client.PowerSyncDatabase.Connect.html) 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 ``` This section assumes that you use PowerSync to sync your backend source database with SQLite in your app. To manage a local SQLite database without sync, instantiate the PowerSync database without calling `connect()` and see the [Local-Only](/client-sdks/advanced/local-only-usage) guide. ### 4. Subscribe to Sync Streams Streams defined with `auto_subscribe: true` start syncing as soon as the client connects. For all other streams, your app must subscribe before their data downloads. The basic pattern is: subscribe to a stream, wait for its data to sync, then unsubscribe when the data is no longer needed. ```csharp theme={null} // Subscribe to a stream with parameters var sub = await db.SyncStream("list_todos", new() { ["list_id"] = "abc123" }).Subscribe(); // Wait for the initial data to sync await sub.WaitForFirstSync(); // The stream's rows are now in the local SQLite database. // TODO: Read the todos for this list with a local query. // When the data is no longer needed sub.Unsubscribe(); ``` After you unsubscribe, the synced data stays in the local database for the stream's time-to-live (TTL), which is 24 hours by default. If the app subscribes again within that time, the data is already available. See [Client-Side Usage](/sync/streams/client-usage) for framework hooks, per-subscription sync status, custom TTLs, priority overrides, and connection parameters. ## Using PowerSync: CRUD Functions Once the PowerSync database is connected and your streams have synced, the data is in the local SQLite database. The most commonly used CRUD functions to interact with your SQLite data are: * [`PowerSyncDatabase.Get`](https://powersync-ja.github.io/powersync-dotnet/api/PowerSync.Common.Client.PowerSyncDatabase.Get.html) - get (`SELECT`) a single row from a table. * [`PowerSyncDatabase.GetAll`](https://powersync-ja.github.io/powersync-dotnet/api/PowerSync.Common.Client.PowerSyncDatabase.GetAll.html) - get (`SELECT`) a set of rows from a table. * [`PowerSyncDatabase.Watch`](https://powersync-ja.github.io/powersync-dotnet/api/PowerSync.Common.Client.PowerSyncDatabase.Watch.html) - execute a read query every time a dependent table changes. * [`PowerSyncDatabase.Execute`](https://powersync-ja.github.io/powersync-dotnet/api/PowerSync.Common.Client.PowerSyncDatabase.Execute.html) - 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("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("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( "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 list', ?, datetime())", [connector.UserId] ); ``` ## Configure Logging By default, the SDK uses a no-op logger that outputs nothing. To enable logging, configure a logger with .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). ## Upgrading the SDK To upgrade the PowerSync package, run the following command in your project folder: ```bash theme={null} dotnet add package PowerSync.Common ``` ```bash theme={null} dotnet add package PowerSync.Common dotnet add package PowerSync.Maui ```