Skip to content
This repository was archived by the owner on Aug 8, 2025. It is now read-only.

Commit 2968a4e

Browse files
authored
Update C# docs for connect/disconnect (#9)
Update after the change in clockworklabs/SpacetimeDB#309.
1 parent f2e1fbd commit 2968a4e

File tree

2 files changed

+42
-54
lines changed

2 files changed

+42
-54
lines changed

docs/Server Module Languages/C#/ModuleReference.md

Lines changed: 3 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -289,6 +289,9 @@ These are two special kinds of reducers that can be used to respond to module li
289289

290290
- `ReducerKind.Init` - this reducer will be invoked when the module is first published.
291291
- `ReducerKind.Update` - this reducer will be invoked when the module is updated.
292+
- `ReducerKind.Connect` - this reducer will be invoked when a client connects to the database.
293+
- `ReducerKind.Disconnect` - this reducer will be invoked when a client disconnects from the database.
294+
292295

293296
Example:
294297

@@ -299,16 +302,3 @@ public static void Init()
299302
Log("...and we're live!");
300303
}
301304
```
302-
303-
### Connection events
304-
305-
`OnConnect` and `OnDisconnect` `SpacetimeDB.Runtime` events are triggered when a client connects or disconnects from the database. They can be used to initialize per-client state or to clean up after the client disconnects. They get passed an instance of the earlier mentioned `DbEventArgs` which can be used to distinguish clients via its `Sender` field.
306-
307-
```csharp
308-
[SpacetimeDB.Reducer(ReducerKind.Init)]
309-
public static void Init()
310-
{
311-
OnConnect += (e) => Log($"Client {e.Sender} connected!");
312-
OnDisconnect += (e) => Log($"Client {e.Sender} disconnected!");
313-
}
314-
```

docs/Server Module Languages/C#/index.md

Lines changed: 39 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -182,64 +182,62 @@ You could extend the validation in `ValidateMessage` in similar ways to `Validat
182182

183183
## Set users' online status
184184

185-
In C# modules, you can register for OnConnect and OnDisconnect events in a special initializer function that uses the attribute `ModuleInitializer`. We'll use the `OnConnect` event to create a `User` record for the client if it doesn't yet exist, and to set its online status.
185+
In C# modules, you can register for `Connect` and `Disconnect` events by using a special `ReducerKind`. We'll use the `Connect` event to create a `User` record for the client if it doesn't yet exist, and to set its online status.
186186

187187
We'll use `User.FilterByIdentity` to look up a `User` row for `dbEvent.Sender`, if one exists. If we find one, we'll use `User.UpdateByIdentity` to overwrite it with a row that has `Online: true`. If not, we'll use `User.Insert` to insert a new row for our new user. All three of these methods are generated by the `[SpacetimeDB.Table]` attribute, with rows and behavior based on the row attributes. `FilterByIdentity` returns a nullable `User`, because the unique constraint from the `[SpacetimeDB.Column(ColumnAttrs.PrimaryKey)]` attribute means there will be either zero or one matching rows. `Insert` will throw an exception if the insert violates this constraint; if we want to overwrite a `User` row, we need to do so explicitly using `UpdateByIdentity`.
188188

189189
In `server/Lib.cs`, add the definition of the connect reducer to the `Module` class:
190190

191191
```C#
192-
[ModuleInitializer]
193-
public static void Init()
192+
[SpacetimeDB.Reducer(ReducerKind.Connect)]
193+
public static void OnConnect(DbEventArgs dbEventArgs)
194194
{
195-
OnConnect += (dbEventArgs) =>
196-
{
197-
Log($"Connect {dbEventArgs.Sender}");
198-
var user = User.FindByIdentity(dbEventArgs.Sender);
195+
Log($"Connect {dbEventArgs.Sender}");
196+
var user = User.FindByIdentity(dbEventArgs.Sender);
199197

200-
if (user is not null)
201-
{
202-
// If this is a returning user, i.e., we already have a `User` with this `Identity`,
203-
// set `Online: true`, but leave `Name` and `Identity` unchanged.
204-
user.Online = true;
205-
User.UpdateByIdentity(dbEventArgs.Sender, user);
206-
}
207-
else
198+
if (user is not null)
199+
{
200+
// If this is a returning user, i.e., we already have a `User` with this `Identity`,
201+
// set `Online: true`, but leave `Name` and `Identity` unchanged.
202+
user.Online = true;
203+
User.UpdateByIdentity(dbEventArgs.Sender, user);
204+
}
205+
else
206+
{
207+
// If this is a new user, create a `User` object for the `Identity`,
208+
// which is online, but hasn't set a name.
209+
new User
208210
{
209-
// If this is a new user, create a `User` object for the `Identity`,
210-
// which is online, but hasn't set a name.
211-
new User
212-
{
213-
Name = null,
214-
Identity = dbEventArgs.Sender,
215-
Online = true,
216-
}.Insert();
217-
}
218-
};
211+
Name = null,
212+
Identity = dbEventArgs.Sender,
213+
Online = true,
214+
}.Insert();
215+
}
219216
}
220217
```
221218

222-
Similarly, whenever a client disconnects, the module will execute the `OnDisconnect` event if it's registered. We'll use it to un-set the `Online` status of the `User` for the disconnected client.
219+
Similarly, whenever a client disconnects, the module will execute the `OnDisconnect` event if it's registered with `ReducerKind.Disconnect`. We'll use it to un-set the `Online` status of the `User` for the disconnected client.
223220

224221
Add the following code after the `OnConnect` lambda:
225222

226223
```C#
227-
OnDisconnect += (dbEventArgs) =>
228-
{
229-
var user = User.FindByIdentity(dbEventArgs.Sender);
224+
[SpacetimeDB.Reducer(ReducerKind.Disconnect)]
225+
public static void OnDisconnect(DbEventArgs dbEventArgs)
226+
{
227+
var user = User.FindByIdentity(dbEventArgs.Sender);
230228

231-
if (user is not null)
232-
{
233-
// This user should exist, so set `Online: false`.
234-
user.Online = false;
235-
User.UpdateByIdentity(dbEventArgs.Sender, user);
236-
}
237-
else
238-
{
239-
// User does not exist, log warning
240-
Log($"Warning: No user found for disconnected client.");
241-
}
242-
};
229+
if (user is not null)
230+
{
231+
// This user should exist, so set `Online: false`.
232+
user.Online = false;
233+
User.UpdateByIdentity(dbEventArgs.Sender, user);
234+
}
235+
else
236+
{
237+
// User does not exist, log warning
238+
Log($"Warning: No user found for disconnected client.");
239+
}
240+
}
243241
```
244242

245243
## Publish the module

0 commit comments

Comments
 (0)