.NET Backend

Backend covers the wire contract this implements. Here's the actual server, a single ASP.NET Core middleware class handling both XHR and WebSocket traffic for a route. Requires .NET 8.0 or later.

Wiring it up

Map a path to your DataServer class as middleware and enable WebSockets separately. Restricting AllowedOrigins is standard ASP.NET Core, not Bindary specific, but worth doing for any route that accepts WebSocket connections:

app.UseSession();

app.Map("/dataserver", b =>
{
    b.UseMiddleware<DataServer>();
});

var originsSetting = Configuration["AllowedOrigins"];

if (!string.IsNullOrEmpty(originsSetting))
{
    var webSocketOptions = new WebSocketOptions();

    foreach (var origin in originsSetting.Split(','))
        webSocketOptions.AllowedOrigins.Add(origin);

    app.UseWebSockets(webSocketOptions);
}
else
    app.UseWebSockets();

On the client, this is the URL a route's dataServerLoad/dataServerUnload points at or wherever dataConnect is left at its default.

Browsers don't apply the same-origin policy to WebSocket connections, they open one to any address a page asks for. The Origin header is the only reliable indication of which page did the asking, which is what AllowedOrigins checks. A session or authentication check alone doesn't replace it: pages on another subdomain still send the session cookie with their handshake.

app.UseSession() (and services.AddSession() during registration) needs to run before the DataServer mapping and only matters if UseSessionIdForClients is left at its default of true. Without it, context.Session is never populated, which is exactly what throws "Session is null while UseSessionIdForClients is set to true".

The DataServer class

Inherit Componyx.UI.Bindary.Server, an abstract middleware base class and implement seven methods. Every request, WebSocket or XHR, flows through them in this order:

public class DataServer : Componyx.UI.Bindary.Server
{
    public DataServer(RequestDelegate next) : base(next) 
    { 
        // default namespace, so client-side calls can be shortened
        DefaultNamespace = "Componyx.Site.Services";
    }

    protected override bool AcceptWebSocketRequest(
        HttpContext context) { return true; } // optional, virtual

    protected override void Open(HttpContext context) { }

    protected override void ClientLoaded(
        string message, 
        DataRequest request, 
        Client client) { }

    protected override void Message(string message) { }

    protected override void Message(byte[] message) { }

    protected override void Message(DataRequest request) { }

    protected override async Task Close(
        WebSocket socket, 
        WebSocketCloseStatus status = WebSocketCloseStatus.NormalClosure, 
        string statusDescription = null) { } // optional, virtual

    protected override void Error(
        Exception ex, 
        DataRequest request, 
        Client client) { }

    protected override void ServerError(Exception ex) { }
}

AcceptWebSocketRequest fires before the WebSocket connection is accepted. This is a virtual method and its default implementation is to return true, returning false denies the connection with a 403. When an App requires users to be authenticated this would be the moment to deny the WebSocket connection for unauthenticated users through:
```
return context.User?.Identity?.IsAuthenticated ?? false;
```
Open fires on every request, WebSocket or XHR, before anything else.
ClientLoaded fires once the client has been identified or created, for both connection types. Session state lives on client.Session from here on.
Message(string) fires when an incoming WebSocket text message fails to deserialize into a DataRequest. Everything that parses successfully, WebSocket or XHR, goes through Message(DataRequest) instead.
Message(byte[]) fires for raw WebSocket binary messages.
Close fires when the WebSocket connection is being closed. This is a virtual method and usually does not require an implementation. Its default implementation is:
```
await socket.CloseOutputAsync(
status, 
statusDescription, 
CancellationToken.None);
```

Error fires for exceptions raised while handling a request. A response can still go back to the client here, the usual place to build and send an error DataResponse.

protected override void Error(Exception ex, DataRequest request, Client client)
{
    var response = new DataResponse<AppSkinError>(request.CallbackId) 
    { 
        IsError = true 
    };
    response.Data.AppData = new AppSkinError(ex);
    response.Data.AppData.StackTrace = null; // don't expose server internals
    Server.Send(client, response, request.XhrRequestId);
}

ServerError fires for exceptions outside that, connection-level failures. A response can no longer be sent, this is for logging.

A handful of instance properties configure behaviour, all optional: UseSessionIdForClients (default true, uses the ASP.NET Core session id as the client id; a WebSocket connection closes with code 1011 if the session is null), ClientDataRequestToDictionary (default true, auto-deserializes the request's raw Data string into DataDictionary), DataRequestJsonSerializerSettings, WebSocketBufferSize (default 8KB) and WebSocketMaxMessageSize (default 4MB).

Full reference: Server.

Client

Every client carries a clientId, this is its .NET-side representation: Id, IPv4Address/IPv6Address, Socket (the WebSocket, if connected that way), Session, IsWebSocket, IsNew (this is the client's first request) and LastActivity.

Server.Clients is the full connected-client dictionary, keyed by client id.

Full reference: Client.

Sending responses

Server.Send(client, response) sends a DataResponse. For an XHR request, this either answers the current request directly or, if called outside the request that's currently open for that client, queues the message for their next one, whichever applies is handled automatically. Server.BroadCast(...) sends to every connected client.

DataResponse carries generic type parameters matching the client's data containers, add only the ones you're actually sending:

// AppData only
new DataResponse<AppDataType>(callbackId);

// + ViewData
new DataResponse<AppDataType, ViewDataType>(callbackId);

// + RouteData
new DataResponse<AppDataType, RouteDataType, ViewDataType>(callbackId);

See the response, on Backend, for how this lines up with what the client actually receives.

Rules

DataRules tells the client how to merge incoming data into what it already has, rather than replacing it outright. Attached per data-key, on AppDataRules, RouteDataRules or ViewDataRules.

Path: the hierarchical path on the target object being added or updated.
UpdateKey / RemoveByKeyValues: match array items by a key's value rather than by index, update the ones that match, remove the ones named for removal.
AddIndex / RemoveIndex / RemoveCount: position-based insertion and removal. Leave AddIndex unset to append.
Update: true merges onto existing data, false overwrites it outright.
EqualityCheck: compare incoming data against what's already there first, skip the update entirely if nothing actually changed.
Recreate: rebuild the element for an updated index/key instead of updating it in place.
IgnoreNullValues / OmitKeys: skip null fields in the response or specific keys entirely, when merging.
RouteIndex / RoutePath: target a different route than the one currently active, rather than the client's own.

This is a different shape from the arrayUpdateRules covered on Data changes. That one is for the client telling itself about a change it just made locally. This one is for the server telling the client how to apply data that's arriving from outside. Related purpose, different fields, don't assume they're interchangeable. It's also not identical to the client-side rules shape covered on Backend, close, but this C# class adds UpdateKey/RemoveByKeyValues and EqualityCheck beyond what the client-side version documents.

See the demo below for UpdateKey and Path both used for real, against a live server, or the full DataRules reference for every property.

ClientActivityMonitor

A background thread that periodically removes inactive clients, WebSocket clients whose connection has been closed for too long and XHR clients that haven't made a request in a while. It isn't started automatically, call it once, typically in Startup.cs:

ClientActivityMonitor.Start(
    removeInactiveClientsInterval: 60,    // how often to check, in seconds
    inactiveClientXhrTimeout: 1200,       // 20 minutes of no XHR activity
    disconnectedWebSocketTimeout: 120,    // 2 minutes disconnected
    callback: client =>
    {
        // return false to keep this specific client despite the timeout
        return true;
    });

DataUpdateManager

A subscription layer for pushing data to specific clients outside the normal request/response cycle. A client subscribes to an update id and any code, anywhere, can later trigger that id and reach every subscriber. AddUpdateAction registers what happens when an id fires, Subscribe adds a client to it, Update triggers it for everyone currently subscribed.

This is entirely optional. Plenty of routes never need it, request/response through Message(DataRequest) or a server-side method is enough on its own. Reach for it specifically when something happening on the server, unrelated to any one client's own request, needs to reach a client that's just sitting there, connected, waiting. See the demo below for all three methods used together.

Full reference: DataUpdateManager.

Server-side methods

A route's serverMethod (or a request's ServerMethod) names a method to invoke directly, dot-separated type and method name, resolved through reflection rather than routed through Message(DataRequest) yourself:

public class OrderMethods
{
    public async Task GetOrder(Client client, DataRequest request)
    {
        var response = new DataResponse<Order>(request.CallbackId);
        response.Data.AppData = await LoadOrder(request.DataDictionary["orderId"]);
        await Server.Send(client, response);
    }
}

The method must be public, return a Task and take exactly (Client, DataRequest). It can be static or instance, called as Namespace.OrderMethods.GetOrder from the client.

Static is the simplest case, no instantiation, no state, called directly. Instance methods get a fresh instance constructed per call by default, Activator.CreateInstance, which needs a parameterless constructor. Mark the class [Reusable] to have the first constructed instance cached and reused for every subsequent call instead, only appropriate when the class holds no per-call or per-client state.

Server.ClassInstantiator overrides how instances get constructed, set it once to resolve from ASP.NET Core's DI container instead of Activator.CreateInstance:

Server.ClassInstantiator = type => app.ApplicationServices.GetRequiredService(type);

[Reusable] caches whatever instance was constructed, permanently, regardless of how it was constructed. If a DI-resolved instance is meant to be scoped, holding a per-request DbContext, for example and that class is also marked [Reusable], that one scoped instance gets frozen and reused for every future call, not just the request it was built for. Don't combine [Reusable] with a class that expects scoped dependencies.

Putting it together

A shared notes list. Click the button, the server picks the text and everyone currently viewing this page sees it appear, live, without refreshing. Open this page in a second tab to check it: add a note in one, watch it appear in the other, even though only one tab clicked anything.

Server

// Services/Notes/AppData.cs
public class AppData
{
    public List<Note> Notes { get; set; }
}

public class Note
{
    public int Id { get; set; }
    public string Text { get; set; }
}

// Services/Notes/Controller.cs
public static class Controller
{
    public static string UpdateNotesId { get; } = "notes";

    private static readonly string[] SampleNotes =
    {
        "Bindary is neat",
        "Hello from the docs",
        "This is a shared note",
        "Testing the live update",
        "Notes stay short",
        "Pushed, not polled",
        "Nice to see you here",
        "Works across tabs",
        "Straight from the server",
        "No refresh needed"
    };

    private static List<Note> _notes = new List<Note>();
    private static int _nextId = 1;

    public static void RegisterActions()
    {
        DataUpdateManager.AddUpdateAction(UpdateNotesId, SendNotes);
    }

    // called once, when the demo section first renders
    public static async Task Subscribe(Client client, DataRequest request)
    {
        DataUpdateManager.Subscribe(UpdateNotesId, client);
        await SendNotes(client);
    }

    // called from the "Add note" button. The client never supplies the text,
    // the server always picks it, so there's nothing here for a request built
    // by hand, dev console or otherwise, to actually control.
    public static async Task AddNote(Client client, DataRequest request)
    {
        var random = new Random();
        var text = SampleNotes[random.Next(SampleNotes.Length)];

        lock (_notes)
        {
            _notes.Add(new Note { Id = _nextId++, Text = text });

            // cap growth
            if (_notes.Count > 10)
                _notes.RemoveAt(0);
        }

        // ack, so dataSendAsync resolves
        var ack = new DataResponse(request.CallbackId);
        await Server.Send(client, ack, request.XhrRequestId);

        // push to every subscribed client, including this one
        await DataUpdateManager.Update(updateId: UpdateNotesId);
    }

    private static async Task SendNotes(
        Client client,
        object subscriptionArgs = null,
        object updateArgs = null)
    {
        var response = new DataResponse<AppData>();
        var rule = new DataRules 
        {   Update = true, 
            UpdateKey = "id", 
            Path = "demo.backendDemo.notes" 
        };

        response.Data.AppData = new AppData { Notes = _notes };
        response.Data.AppDataRules = new CaseInsensitiveDictionary<DataRules>();
        response.Data.AppDataRules["Notes"] = rule;

        await Server.Send(client, response);
    }
}

The server picks the text, not the client. Nothing sent in the request is ever read for this, so there's no way, dev console included, to make this list say anything the server didn't already approve.

RegisterActions() needs one call in Startup.cs, alongside your other startup wiring: Notes.Controller.RegisterActions();.

DataUpdateManager.Update(UpdateNotesId) won't compile as written, a single string argument matches two different overloads equally well, updateId on one, groupId on the other. Name the argument, Update(updateId: UpdateNotesId), to resolve it to the one you actually mean.

Client

ctrl.subscribeNotes = async () =>
{
    await $bindary.dataSendAsync(null, 'Notes.Controller.Subscribe');
};

ctrl.addNote = async () =>
{
    await $bindary.dataSendAsync(null, 'Notes.Controller.AddNote');
};

<div b-post-render="subscribeNotes">
    <ul>
        <li b-repeat="demo.backendDemo.notes" b-value="text"></li>
    </ul>
    <a ui-type="Button" ui-text="Add note"
       ui-command="$bindary.controller.addNote"></a>
</div>

demo.backendDemo.notes has to already exist client-side before this renders. b-repeat resolves its data-key the moment this markup renders, before subscribeNotes even runs, let alone before its response comes back, so there's nothing that would create it in time on its own. It's seeded once in the shared load hook, the same place every other reference page's demo data on this site comes from.

Result

Every push here sends the whole list, all ten notes, not just the new one. UpdateKey = "id" is what makes that safe: a matching id gets updated in place, a new id gets appended, so resending the full list on every push doesn't duplicate anything already there. Path is why this lands at demo.backendDemo.notes specifically, rather than merging directly onto AppData's own root.

Sending everything every time is a deliberate simplification for this demo, not the only way to use this. Sending only what's genuinely new, tracking per-subscriber what a client has already seen, the args object on a subscription is where that would live, means less to send as a list grows, with UpdateKey then acting as a safety net against an accidental duplicate rather than doing the main work. Worth reaching for once "resend everything" stops being cheap enough.

UpdateKey is matched against the property name as it arrives client-side, not the C# property name. With camelCase serialization, that's "id", not "Id". Get this wrong and every comparison quietly reads undefined on both sides, which counts as a match, so the merge always updates whichever item happens to be first, no error, nothing obviously broken, just the wrong item overwritten every time.