TXTextControl.Web.Collaboration 34.0.6-alpha

TX Text Control Web Collaboration

Adds server-authoritative, SignalR-based collaboration rooms to the TX Text Control ASP.NET Core Document Editor. The package owns the collaboration master, isolated ServerTextControl worker pool, synchronization coordinator, encrypted room access, presence bar, and invitation UI.

The consuming application chooses where documents are stored. It passes a server file path or byte array containing TX Text Control Internal Unicode Format when it creates a room. The package then loads the room document into every connected editor through the TX Text Control JavaScript API. Conversion from formats such as DOCX belongs to the consuming application so that the collaboration package always operates on TX documents.

Install

Add the collaboration package together with the TX Text Control ASP.NET Core Document Editor packages:

dotnet add package TXTextControl.Web.Collaboration --version 34.0.0-alpha
dotnet add package TXTextControl.Web --version 34.4.0
dotnet add package TXTextControl.Web.DocumentEditor.Backend --version 34.4.0

TXTextControl.TextControl.Core.SDK is a NuGet dependency of the collaboration package. TX Text Control assemblies are not bundled in this package and are restored by NuGet from the official TX Text Control package.

A valid TX Text Control license is required. Installing this package does not grant a license to TX Text Control.

Register collaboration

using TXTextControl.Web;
using TXTextControl.Web.Collaboration;
using TXTextControl.Web.DocumentEditor.Backend;

builder.Services.AddTXTextControlCollaboration(
    builder.Configuration.GetSection(TxTextControlCollaborationOptions.DefaultSectionName));
builder.Services.AddHostedService<DocumentEditorWorkerManager>();

var app = builder.Build();

app.UseStaticFiles();
app.UseRouting();
app.UseWebSockets();
app.UseTXWebSocketMiddleware();

app.MapTxTextControlCollaboration();

The example starts the TX Document Editor backend in the application process. Applications using an external synchronization service should configure UseTXWebSocketMiddleware for that service instead.

Room persistence is optional. When enabled, the built-in file-system provider stores the current TX master and room metadata after every accepted update and restores active rooms when the application starts.

Create a room from a server file

public async Task<IActionResult> Collaborate(
    string documentId,
    ITxTextControlCollaboration collaboration,
    CancellationToken cancellationToken)
{
    var path = documents.GetServerPath(documentId);
    var room = await collaboration.CreateRoomFromFileAsync(
        path,
        User.Identity!.Name!,
        cancellationToken);

    return RedirectToAction("Room", new { room = room.AccessToken });
}

Create a room from bytes

byte[] document = await documents.LoadAsync(documentId, cancellationToken);
CollaborationRoom room = await collaboration.CreateRoomAsync(
    document,
    User.Identity!.Name!,
    cancellationToken);

The returned RoomId identifies the server-side room. AccessToken is an encrypted, authenticated token for the room owner and is suitable for the URL.

Applications that maintain a list of active collaboration rooms can issue access for another authorized user without creating a second room:

CollaborationRoomAccess? access = await collaboration.CreateRoomAccessAsync(
    roomId,
    User.Identity!.Name!,
    cancellationToken);

The consuming application remains responsible for deciding whether that user may access the room.

Connect an editor

Register the package Tag Helper once in the application's _ViewImports.cshtml:

@addTagHelper *, TXTextControl.Web.Collaboration

Render an empty TX Text Control and add the web component. The component joins the room and calls TXTextControl.loadDocument with the authoritative TX document.

<tx-collaboration room-token="@Model.AccessToken" />

<div id="collaborationEditor" data-tx-collaboration-editor>
    @Html.TXTextControl().TextControl().Render()
</div>

The Tag Helper renders the internal tx-document-collaboration web component and automatically adds the package's versioned browser bundle once per rendered page. The bundle contains the SignalR client and collaboration code and loads the collaboration styles automatically. By default, the component finds the element marked with data-tx-collaboration-editor, connects to /tx-collaboration/hub, and uses the current page URL for invitation links. It replaces the room token while preserving other query parameters needed by the application, such as a document or session key. Use editor-frame, hub-url, or invite-url only when an application needs to override those defaults. Each invitation contains its assigned user name, expiration, and a unique nonce.

Applications that render the component outside Razor can load the bundle directly from /_content/TXTextControl.Web.Collaboration/collaboration.min.js. When hosted below a public path, prepend that path explicitly, for example /collaboration/_content/TXTextControl.Web.Collaboration/collaboration.min.js.

When a reverse proxy publishes the application below a path and removes that prefix before forwarding requests, configure the externally visible path once. The Tag Helper then prefixes both the static browser bundle and SignalR hub URL:

{
  "TextControl": {
    "Collaboration": {
      "PublicPathBase": "/collaboration"
    }
  }
}

Leave PublicPathBase empty when the host already sets ASP.NET Core's HttpRequest.PathBase; the Tag Helper uses that value automatically.

Configure sharing

{
  "TextControl": {
    "Collaboration": {
      "PublicPathBase": "",
      "HubPath": "/tx-collaboration/hub",
      "Sharing": {
        "Users": [
          "Ada Lovelace",
          "Grace Hopper"
        ],
        "AllowFreeTextUsers": true,
        "InvitationLifetimeHours": 168
      },
      "Workers": {
        "WorkerCount": 2,
        "QueueCapacityPerWorker": 128,
        "StartupTimeoutSeconds": 30,
        "RequestTimeoutSeconds": 90,
        "RestartAttempts": 1,
        "MaxMessageSizeMegabytes": 512
      },
      "Synchronization": {
        "DocumentAccessMode": "ServerSide",
        "DirectEditorAccessEnabled": true,
        "FragmentUploadsEnabled": true,
        "CommitIdleMilliseconds": 400,
        "ReconciliationIntervalSeconds": 120,
        "MaximumReconciliationIntervalSeconds": 300,
        "MaximumFragmentKilobytes": 4096,
        "MaximumVersionSnapshots": 16,
        "MaximumVersionSnapshotMegabytes": 64
      },
      "Persistence": {
        "Enabled": true,
        "DirectoryPath": "App_Data/CollaborationRooms",
        "RoomRetentionHours": 168,
        "CleanupIntervalMinutes": 30,
        "FlushDelayMilliseconds": 1000
      }
    }
  }
}

DocumentAccessMode selects the TX document access path:

• ServerSide is optimized for the current server-hosted Document Editor. After the collaboration participant proves ownership of its TXTextControl.connectionID, the package reads the live editor selection through WebSocketHandler, resolves paragraph and complete-table ranges from the authoritative master version, and transfers only TX fragments between the editor process and the TX worker. Complete document content does not travel through the browser for normal synchronization.
• ClientSide keeps the asynchronous JavaScript document-model path. The browser resolves and uploads TX selections and uses complete-document uploads for defensive fallbacks. Use this mode for editor runtimes where the document model lives in the browser, including a WebAssembly-based editor.

DirectEditorAccessEnabled is a kill switch for ServerSide access. When it is disabled or the editor cannot be registered, the client-side transport remains the recovery path. Server-side access requires the collaboration hub and the TX Document Editor WebSocketHandler to run in the same application process. Multiple application instances must use sticky routing for both connections.

When free-text users are disabled, the hub accepts invitations only for configured users. User names and presence colors are taken from the protected invitation rather than query-string values.

FragmentUploadsEnabled sends or captures the changed TX selection instead of serializing the complete document for ordinary main-text edits. The server reconstructs a candidate against the transaction's master-version snapshot and then runs the same authoritative patch, table, rebase, and broadcast pipeline used by complete TX commits. Formatting-only changes are included because fragments are saved in TX Text Control Internal Unicode Format. Ambiguous ranges, unsupported document parts, oversized fragments, and structural edits automatically fall back to a complete TX document using the selected access mode.

The browser keeps an unacknowledged transaction and its id until the server accepts or rejects it, so transient SignalR failures retry idempotently. After ReconciliationIntervalSeconds of idle time, it also saves and verifies the complete TX document against the server-normalized master. Consecutive successful checks back off adaptively up to MaximumReconciliationIntervalSeconds; new edits, reconnects, and mismatches reset the base interval. A semantic mismatch after a fragment or a change that was not covered by an editor event is recovered through a complete TX commit. CommitIdleMilliseconds controls the quiet period before an edit is sent, and MaximumFragmentKilobytes bounds fragment payloads before the complete-document fallback is used.

MaximumVersionSnapshots and MaximumVersionSnapshotMegabytes bound the in-memory TX history used to merge stale edits. The newest version is always retained. When either limit is reached, the oldest snapshots are discarded and clients based on those versions receive the normal full-refresh recovery instead of forcing the server to retain or reload an unbounded document history.

DirectoryPath can be absolute or relative to the application content root. Accepted versions are published to connected clients before room persistence; writes during FlushDelayMilliseconds are coalesced to the newest version and all pending rooms are flushed during application shutdown. Inactive rooms are removed after RoomRetentionHours; connected rooms are never removed by the cleanup loop. Use a custom durable provider when room data belongs in a database or object store:

builder.Services
    .AddTXTextControlCollaboration(
        builder.Configuration.GetSection(TxTextControlCollaborationOptions.DefaultSectionName))
    .UseRoomStore<DatabaseCollaborationRoomStore>();

The custom store implements ICollaborationRoomStore and is registered as a singleton, so it must be thread-safe.

Publish the current master

The collaboration master and the application's source document are intentionally separate. Room persistence protects the live TX master and restores the session after a restart; it does not overwrite the source file or application record. The application decides when to publish the authoritative room document back to that source.

Before starting the server request from an editor page, flush pending client edits through the web component:

await document.querySelector("tx-document-collaboration").flush();

byte[]? document = await collaboration.ExportDocumentAsync(roomId, cancellationToken);
if (document is not null)
{
    await documents.SaveAsync(documentId, document, cancellationToken);
}

Close a completed room and remove its persisted master with CloseRoomAsync. ASP.NET Core Data Protection encrypts room links. Applications running on multiple web servers must configure a shared Data Protection key ring and use an ICollaborationRoomStore implementation accessible to every server. The current in-process room coordinator still requires sticky routing or a single application instance for connected editors.