The SpacetimeDB C# client SDK

The SpacetimeDB client for C# contains all the tools you need to build native clients for SpacetimeDB modules using C#.

Project setup

Using the `dotnet` CLI tool

If you would like to create a console application using .NET, you can create a new project using dotnet new console and add the SpacetimeDB SDK to your dependencies:

dotnet add package spacetimedbsdk 
    

(See also the CSharp Quickstart for an in-depth example of such a console application.)

Using Unity

To install the SpacetimeDB SDK into a Unity project, download the SpacetimeDB SDK, packaged as a .unitypackage.

In Unity navigate to the Assets > Import Package > Custom Package menu in the menu bar. Select your SpacetimeDB.Unity.Comprehensive.Tutorial.unitypackage file and leave all folders checked.

(See also the Unity Tutorial)

Generate module bindings

Each SpacetimeDB client depends on some bindings specific to your module. Create a module_bindings directory in your project's directory and generate the C# interface files using the Spacetime CLI. From your project directory, run:

mkdir -p module_bindings
spacetime generate --lang cs --out-dir module_bindings --project-path PATH-TO-MODULE-DIRECTORY 
    

Replace PATH-TO-MODULE-DIRECTORY with the path to your SpacetimeDB module.

Type `DbConnection`

A connection to a remote database is represented by the DbConnection class. This class is generated per module and contains information about the types, tables, and reducers defined by your module.

Connect to a module

class DbConnection
{
    public static DbConnectionBuilder<DbConnection> Builder();
} 
    

Construct a DbConnection by calling DbConnection.Builder(), chaining configuration methods, and finally calling .Build(). At a minimum, you must specify WithUri to provide the URI of the SpacetimeDB instance, and WithModuleName to specify the module's name or identity.

Method `WithUri`

class DbConnectionBuilder<DbConnection>
{
    public DbConnectionBuilder<DbConnection> WithUri(Uri uri);
} 
    

Configure the URI of the SpacetimeDB instance or cluster which hosts the remote module.

Method `WithModuleName`

class DbConnectionBuilder
{
    public DbConnectionBuilder<DbConnection> WithModuleName(string nameOrIdentity);
} 
    

Configure the SpacetimeDB domain name or Identity of the remote module which identifies it within the SpacetimeDB instance or cluster.

Callback `OnConnect`

class DbConnectionBuilder<DbConnection>
{
    public DbConnectionBuilder<DbConnection> OnConnect(Action<DbConnection, Identity, string> callback);
} 
    

Chain a call to .OnConnect(callback) to your builder to register a callback to run when your new DbConnection successfully initiates its connection to the remote module. The callback accepts three arguments: a reference to the DbConnection, the Identity by which SpacetimeDB identifies this connection, and a private access token which can be saved and later passed to WithToken to authenticate the same user in future connections.

Callback `OnConnectError`

class DbConnectionBuilder<DbConnection>
{
    public DbConnectionBuilder<DbConnection> OnConnectError(Action<ErrorContext, SpacetimeDbException> callback);
} 
    

Chain a call to .OnConnectError(callback) to your builder to register a callback to run when your connection fails.

A known bug in the SpacetimeDB Rust client SDK currently causes this callback never to be invoked. OnDisconnect callbacks are invoked instead.

Callback `OnDisconnect`

class DbConnectionBuilder<DbConnection>
{
    public DbConnectionBuilder<DbConnection> OnDisconnect(Action<ErrorContext, SpacetimeDbException> callback);
} 
    

Chain a call to .OnDisconnect(callback) to your builder to register a callback to run when your DbConnection disconnects from the remote module, either as a result of a call to Disconnect or due to an error.

Method `WithToken`

class DbConnectionBuilder<DbConnection>
{
    public DbConnectionBuilder<DbConnection> WithToken(string token = null);
} 
    

Chain a call to .WithToken(token) to your builder to provide an OpenID Connect compliant JSON Web Token to authenticate with, or to explicitly select an anonymous connection. If this method is not called or None is passed, SpacetimeDB will generate a new Identity and sign a new private access token for the connection.

Method `Build`

class DbConnectionBuilder<DbConnection>
{
    public DbConnection Build();
} 
    

After configuring the connection and registering callbacks, attempt to open the connection.

Advance the connection and process messages

In the interest of supporting a wide variety of client applications with different execution strategies, the SpacetimeDB SDK allows you to choose when the DbConnection spends compute time and processes messages. If you do not arrange for the connection to advance by calling one of these methods, the DbConnection will never advance, and no callbacks will ever be invoked.

Method `FrameTick`

class DbConnection {
    public void FrameTick();
} 
    

FrameTick will advance the connection until no work remains or until it is disconnected, then return rather than blocking. Games might arrange for this message to be called every frame.

It is not advised to run FrameTick on a background thread, since it modifies dbConnection.Db. If main thread code is also accessing the Db, it may observe data races when FrameTick runs on another thread.

(Note that the SDK already does most of the work for parsing messages on a background thread. FrameTick() does the minimal amount of work needed to apply updates to the Db.)

Access tables and reducers

Property `Db`

class DbConnection
{
    public RemoteTables Db;
    /* other members */
} 
    

The Db property of the DbConnection provides access to the subscribed view of the remote database's tables. See Access the client cache.

Property `Reducers`

class DbConnection
{
    public RemoteReducers Reducers;
    /* other members */
} 
    

The Reducers field of the DbConnection provides access to reducers exposed by the remote module. See Observe and invoke reducers.

Interface `IDbContext`

interface IDbContext<DbView, RemoteReducers, ..>
{
    /* methods */
} 
    

DbConnection, EventContext, ReducerEventContext, SubscriptionEventContext and ErrorContext all implement IDbContext. IDbContext has methods for inspecting and configuring your connection to the remote database.

The IDbContext interface is implemented by connections and contexts to every module - hence why it takes DbView and RemoteReducers as type parameters.

Interface `IRemoteDbContext`

Each module's module_bindings exports an interface IRemoteDbContext which inherits from IDbContext, with the type parameters DbView and RemoteReducers bound to the types defined for that module. This can be more convenient when creating functions that can be called from any callback for a specific module, but which access the database or invoke reducers, and so must know the type of the DbView or Reducers.

Method `Db`

interface IRemoteDbContext
{
    public DbView Db { get; }
} 
    

Db will have methods to access each table defined by the module.

Example

var conn = ConnectToDB();

// Get a handle to the User table
var tableHandle = conn.Db.User; 
    

Method `Reducers`

interface IRemoteDbContext
{
    public RemoteReducers Reducers { get; }
} 
    

Reducers will have methods to invoke each reducer defined by the module, plus methods for adding and removing callbacks on each of those reducers.

Example

var conn = ConnectToDB();

// Register a callback to be run every time the SendMessage reducer is invoked
conn.Reducers.OnSendMessage += Reducer_OnSendMessageEvent; 
    

Method `Disconnect`

interface IRemoteDbContext
{
    public void Disconnect();
} 
    

Gracefully close the DbConnection. Throws an error if the connection is already closed.

Subscribe to queries

Type `SubscriptionBuilder`

Constructor `ctx.SubscriptionBuilder()`

interface IRemoteDbContext
{
    public SubscriptionBuilder SubscriptionBuilder();
} 
    

Subscribe to queries by calling ctx.SubscriptionBuilder() and chaining configuration methods, then calling .Subscribe(queries).

Callback `OnApplied`

class SubscriptionBuilder
{
    public SubscriptionBuilder OnApplied(Action<SubscriptionEventContext> callback);
} 
    

Register a callback to run when the subscription is applied and the matching rows are inserted into the client cache.

Callback `OnError`

class SubscriptionBuilder
{
    public SubscriptionBuilder OnError(Action<ErrorContext, Exception> callback);
} 
    

Register a callback to run if the subscription is rejected or unexpectedly terminated by the server. This is most frequently caused by passing an invalid query to Subscribe.

Method `Subscribe`

class SubscriptionBuilder
{
    public SubscriptionHandle Subscribe(string[] querySqls);
} 
    

Subscribe to a set of queries. queries should be an array of SQL query strings.

See the SpacetimeDB SQL Reference for information on the queries SpacetimeDB supports as subscriptions.

Method `SubscribeToAllTables`

class SubscriptionBuilder
{
    public void SubscribeToAllTables();
} 
    

Subscribe to all rows from all public tables. This method is provided as a convenience for simple clients. The subscription initiated by SubscribeToAllTables cannot be canceled after it is initiated. You should subscribe to specific queries if you need fine-grained control over the lifecycle of your subscriptions.

Type `SubscriptionHandle`

A SubscriptionHandle represents a subscribed query or a group of subscribed queries.

The SubscriptionHandle does not contain or provide access to the subscribed rows. Subscribed rows of all subscriptions by a connection are contained within that connection's ctx.Db. See Access the client cache.

Property `IsEnded`

class SubscriptionHandle
{
    public bool IsEnded;
} 
    

True if this subscription has been terminated due to an unsubscribe call or an error.

Property `IsActive`

class SubscriptionHandle
{
    public bool IsActive;
} 
    

True if this subscription has been applied and has not yet been unsubscribed.

Method `Unsubscribe`

class SubscriptionHandle
{
    public void Unsubscribe();
} 
    

Terminate this subscription, causing matching rows to be removed from the client cache. Any rows removed from the client cache this way will have OnDelete callbacks run for them.

Unsubscribing is an asynchronous operation. Matching rows are not removed from the client cache immediately. Use UnsubscribeThen to run a callback once the unsubscribe operation is completed.

Returns an error if the subscription has already ended, either due to a previous call to Unsubscribe or UnsubscribeThen, or due to an error.

Method `UnsubscribeThen`

class SubscriptionHandle
{
    public void UnsubscribeThen(Action<SubscriptionEventContext>? onEnded);
} 
    

Terminate this subscription, and run the onEnded callback when the subscription is ended and its matching rows are removed from the client cache. Any rows removed from the client cache this way will have OnDelete callbacks run for them.

Returns an error if the subscription has already ended, either due to a previous call to Unsubscribe or UnsubscribeThen, or due to an error.

Read connection metadata

Property `Identity`

interface IDbContext
{
    public Identity? Identity { get; }
} 
    

Get the Identity with which SpacetimeDB identifies the connection. This method returns null if the connection was initiated anonymously and the newly-generated Identity has not yet been received, i.e. if called before the OnConnect callback is invoked.

Property `ConnectionId`

interface IDbContext
{
    public ConnectionId ConnectionId { get; }
} 
    

Get the ConnectionId with which SpacetimeDB identifies the connection.

Property `IsActive`

interface IDbContext
{
    public bool IsActive { get; }
} 
    

true if the connection has not yet disconnected. Note that a connection IsActive when it is constructed, before its OnConnect callback is invoked.

Type `EventContext`

An EventContext is an IDbContext augmented with an Event property. EventContexts are passed as the first argument to row callbacks OnInsert, OnDelete and OnUpdate.

Property `Event`

class EventContext {
    public readonly Event<Reducer> Event;
    /* other fields */
} 
    

The Event contained in the EventContext describes what happened to cause the current row callback to be invoked.

Property `Db`

class EventContext {
    public RemoteTables Db;
    /* other fields */
} 
    

The Db property of the context provides access to the subscribed view of the remote database's tables. See Access the client cache.

Field `Reducers`

class EventContext {
    public RemoteReducers Reducers;
    /* other fields */
} 
    

The Reducers property of the context provides access to reducers exposed by the remote module. See Observe and invoke reducers.

Record `Event`

Variant `Reducer`

record Event<R>
{
    public record Reducer(ReducerEvent<R> ReducerEvent) : Event<R>;
} 
    

Event when we are notified that a reducer ran in the remote module. The ReducerEvent contains metadata about the reducer run, including its arguments and termination Status.

This event is passed to row callbacks resulting from modifications by the reducer.

Variant `SubscribeApplied`

record Event<R>
{
    public record SubscribeApplied : Event<R>;
} 
    

Event when our subscription is applied and its rows are inserted into the client cache.

This event is passed to row OnInsert callbacks resulting from the new subscription.

Variant `UnsubscribeApplied`

record Event<R>
{
    public record UnsubscribeApplied : Event<R>;
} 
    

Event when our subscription is removed after a call to SubscriptionHandle.Unsubscribe or SubscriptionHandle.UnsubscribeTthen and its matching rows are deleted from the client cache.

This event is passed to row OnDelete callbacks resulting from the subscription ending.

Variant `SubscribeError`

record Event<R>
{
    public record SubscribeError(Exception Exception) : Event<R>;
} 
    

Event when a subscription ends unexpectedly due to an error.

This event is passed to row OnDelete callbacks resulting from the subscription ending.

Variant `UnknownTransaction`

record Event<R>
{
    public record UnknownTransaction : Event<R>;
} 
    

Event when we are notified of a transaction in the remote module which we cannot associate with a known reducer. This may be an ad-hoc SQL query or a reducer for which we do not have bindings.

This event is passed to row callbacks resulting from modifications by the transaction.

Record `ReducerEvent`

record ReducerEvent<R>(
    Timestamp Timestamp,
    Status Status,
    Identity CallerIdentity,
    ConnectionId? CallerConnectionId,
    U128? EnergyConsumed,
    R Reducer
) 
    

A ReducerEvent contains metadata about a reducer run.

Record `Status`

record Status : TaggedEnum<(
    Unit Committed,
    string Failed,
    Unit OutOfEnergy
)>; 
    

Variant `Committed`

The reducer returned successfully and its changes were committed into the database state. An Event.Reducer passed to a row callback must have this status in its ReducerEvent.

Variant `Failed`

The reducer returned an error, panicked, or threw an exception. The record payload is the stringified error message. Formatting of the error message is unstable and subject to change, so clients should use it only as a human-readable diagnostic, and in particular should not attempt to parse the message.

Variant `OutOfEnergy`

The reducer was aborted due to insufficient energy balance of the module owner.

Record `Reducer`

The module bindings contains an record Reducer with a variant for each reducer defined by the module. Each variant has a payload containing the arguments to the reducer.

Type `ReducerEventContext`

A ReducerEventContext is an IDbContext augmented with an Event property. ReducerEventContexts are passed as the first argument to reducer callbacks.

Property `Event`

class ReducerEventContext {
    public readonly ReducerEvent<Reducer> Event;
    /* other fields */
} 
    

The ReducerEvent contained in the ReducerEventContext has metadata about the reducer which ran.

Property `Db`

class ReducerEventContext {
    public RemoteTables Db;
    /* other fields */
} 
    

The Db property of the context provides access to the subscribed view of the remote database's tables. See Access the client cache.

Property `Reducers`

class ReducerEventContext {
    public RemoteReducers Reducers;
    /* other fields */
} 
    

The Reducers property of the context provides access to reducers exposed by the remote module. See Observe and invoke reducers.

Type `SubscriptionEventContext`

A SubscriptionEventContext is an IDbContext. Unlike the other context types, SubscriptionEventContext doesn't have an Event property. SubscriptionEventContexts are passed to subscription OnApplied and UnsubscribeThen callbacks.

Property `Db`

class SubscriptionEventContext {
    public RemoteTables Db;
    /* other fields */
} 
    

The Db property of the context provides access to the subscribed view of the remote database's tables. See Access the client cache.

Property `Reducers`

class SubscriptionEventContext {
    public RemoteReducers Reducers;
    /* other fields */
} 
    

The Reducers property of the context provides access to reducers exposed by the remote module. See Observe and invoke reducers.

Type `ErrorContext`

An ErrorContext is an IDbContext augmented with an Event property. ErrorContexts are to connections' OnDisconnect and OnConnectError callbacks, and to subscriptions' OnError callbacks.

Property `Event`

class SubscriptionEventContext {
    public readonly Exception Event;
    /* other fields */
} 
    

Property `Db`

class ErrorContext {
    public RemoteTables Db;
    /* other fields */
} 
    

The Db property of the context provides access to the subscribed view of the remote database's tables. See Access the client cache.

Property `Reducers`

class ErrorContext {
    public RemoteReducers Reducers;
    /* other fields */
} 
    

The Reducers property of the context provides access to reducers exposed by the remote module. See Observe and invoke reducers.

Access the client cache

All IDbContext implementors, including DbConnection and EventContext, have .Db properties, which in turn have methods for accessing tables in the client cache.

Each table defined by a module has an accessor method, whose name is the table name converted to snake_case, on this .Db property. The table accessor methods return table handles which inherit from RemoteTableHandle and have methods for searching by index.

Type `RemoteTableHandle`

Implemented by all table handles.

Type `Row`

class RemoteTableHandle<EventContext, Row>
{
    /* members */
} 
    

The type of rows in the table.

Property `Count`

class RemoteTableHandle
{
    public int Count;
} 
    

The number of rows of this table resident in the client cache, i.e. the total number which match any subscribed query.

Method `Iter`

class RemoteTableHandle
{
    public IEnumerable<Row> Iter();
} 
    

An iterator over all the subscribed rows in the client cache, i.e. those which match any subscribed query.

Callback `OnInsert`

class RemoteTableHandle
{
    public delegate void RowEventHandler(EventContext context, Row row);
    public event RowEventHandler? OnInsert;
} 
    

The OnInsert callback runs whenever a new row is inserted into the client cache, either when applying a subscription or being notified of a transaction. The passed EventContext contains an Event which can identify the change which caused the insertion, and also allows the callback to interact with the connection, inspect the client cache and invoke reducers. Newly registered or canceled callbacks do not take effect until the following event.

See the quickstart for examples of regstering and unregistering row callbacks.

Callback `OnDelete`

class RemoteTableHandle
{
    public delegate void RowEventHandler(EventContext context, Row row);
    public event RowEventHandler? OnDelete;
} 
    

The OnDelete callback runs whenever a previously-resident row is deleted from the client cache. Newly registered or canceled callbacks do not take effect until the following event.

See the quickstart for examples of regstering and unregistering row callbacks.

Callback `OnUpdate`

class RemoteTableHandle
{
    public delegate void RowEventHandler(EventContext context, Row row);
    public event RowEventHandler? OnUpdate;
} 
    

The OnUpdate callback runs whenever an already-resident row in the client cache is updated, i.e. replaced with a new row that has the same primary key. The table must have a primary key for callbacks to be triggered. Newly registered or canceled callbacks do not take effect until the following event.

See the quickstart for examples of regstering and unregistering row callbacks.

Unique constraint index access

For each unique constraint on a table, its table handle has a property which is a unique index handle and whose name is the unique column name. This unique index handle has a method .Find(Column value). If a Row with value in the unique column is resident in the client cache, .Find returns it. Otherwise it returns null.

Example

Given the following module-side User definition:

[Table(Name = "User", Public = true)]
public partial class User
{
    [Unique] // Or [PrimaryKey]
    public Identity Identity;
    ..
} 
    

a client would lookup a user as follows:

User? FindUser(RemoteTables tables, Identity id) => tables.User.Identity.Find(id); 
    

BTree index access

For each btree index defined on a remote table, its corresponding table handle has a property which is a btree index handle and whose name is the name of the index. This index handle has a method IEnumerable<Row> Filter(Column value) which will return Rows with value in the indexed Column, if there are any in the cache.

Example

Given the following module-side Player definition:

[Table(Name = "Player", Public = true)]
public partial class Player
{
    [PrimaryKey]
    public Identity id;

    [Index.BTree(Name = "Level")]
    public uint level;
    ..
} 
    

a client would count the number of Players at a certain level as follows:

int CountPlayersAtLevel(RemoteTables tables, uint level) => tables.Player.Level.Filter(level).Count(); 
    

Observe and invoke reducers

All IDbContext implementors, including DbConnection and EventContext, have a .Reducers property, which in turn has methods for invoking reducers defined by the module and registering callbacks on it.

Each reducer defined by the module has three methods on the .Reducers:

• An invoke method, whose name is the reducer's name converted to snake case, like set_name. This requests that the module run the reducer.
• A callback registation method, whose name is prefixed with on_, like on_set_name. This registers a callback to run whenever we are notified that the reducer ran, including successfully committed runs and runs we requested which failed. This method returns a callback id, which can be passed to the callback remove method.
• A callback remove method, whose name is prefixed with remove_on_, like remove_on_set_name. This cancels a callback previously registered via the callback registration method.

Identify a client

Type `Identity`

A unique public identifier for a client connected to a database. See the module docs for more details.

Type `ConnectionId`

An opaque identifier for a client connection to a database, intended to differentiate between connections from the same Identity. See the module docs for more details.

Type `Timestamp`

A point in time, measured in microseconds since the Unix epoch. See the module docs for more details.

Type `TaggedEnum`

A tagged union type. See the module docs for more details.