Product Architecture

Knowing how the parts of TX Text Control .NET Server run and connect makes it easier to plan a project or a deployment. The parts are the document engine, the components that run inside your application and the browser components with the backends they need. Together, they determine which packages you install, which processes your application starts and which network connections it uses.

Architecture at a Glance

TX Text Control .NET Server has three layers:

• The document engine loads, lays out, renders and saves documents. You choose between the Core and the Classic engine.
• The server-side components ServerTextControl and MailMerge are .NET classes that you use in your own code. They run inside your application's process.
• The browser components, the Document Editor and the Document Viewer, consist of a frontend in the browser and a backend in your ASP.NET Core application. The Document Editor also uses a separate backend process.

The following diagram shows all parts in one ASP.NET Core application:

Browser                            Your ASP.NET Core application      Separate process

Document Editor  ---WebSocket--->  WebSocketMiddleware  -----TCP--->  TXTextControl.Web.Server.Core

Document Viewer  ------HTTP----->  Document Viewer backend
                                   ServerTextControl and MailMerge
                                   TX Text Control engine

The following sections describe each part from the bottom up.

The Document Engine

The engine is the part of TX Text Control that every other component uses. It consists of .NET assemblies and native libraries for each supported platform. TX Text Control .NET Server ships with two engines, each in its own NuGet package.

Core and Classic

Both packages target .NET 8 and support .NET 8, .NET 9 and .NET 10. They provide nearly the same functionality, and both contain the ServerTextControl class in the TXTextControl namespace, so your code looks the same with either engine.

Which engine to choose:

• Core is recommended for new .NET 8 or higher projects and for applications that you migrate to .NET 8 or higher. It is required for Linux and Linux containers.
• Classic is for Windows-only applications, existing Classic integrations, and applications that must load or save DOC or XML files.

The blog article TX Text Control Classic vs Core - When to use which Version explains the differences in more detail. Core and Classic Differences lists all format differences, such as XML, RTF and EMF, and From Classic to Core moves an existing application to the Core engine.

Fonts in the Core Engine

The Classic engine uses the fonts installed on Windows. The Core engine does not depend on GDI or system fonts. Its package adds a Fonts folder with a standard set of serif and sans-serif fonts to your project and copies it to the output directory. To use other fonts, add them to this folder when you deploy your application.

Because the fonts are deployed with the application, documents render the same way in every environment. This matters in Docker containers and Azure App Services, where installing system fonts is difficult.

ServerTextControl and MailMerge

ServerTextControl is the non-visual document processing component. It has no window and no user interface. You create an instance in your code, load or build a document through its properties and methods, and save the result.

MailMerge in the TXTextControl.DocumentServer namespace merges data into templates. It uses a ServerTextControl to hold the template and the merged document: you load the template into a ServerTextControl and connect MailMerge to it through the TextComponent property.

Both classes are part of the engine package, and they run in the process of your application:

• They do not need a separate service, backend process or network connection.
• You can use them in any .NET application that runs on the server or in the background, such as ASP.NET Core applications, Web APIs, console applications and services.
• Document processing uses the CPU and memory of your application's process. Large jobs, such as batch mail merges or PDF generation, therefore compete with everything else that runs in the same instance. Scaling Beyond One Instance describes how to separate them.

The TXTextControl.DocumentServer.ParallelMailMerge package on nuget.org runs MailMerge processing in isolated worker processes.

Document Editor

The Document Editor is not a pure client-side component. The frontend in the browser shows the ribbon, the pages and the text, but the document itself is synchronized with the server. The server calculates the rendering information for the editor, which is how the browser shows a true WYSIWYG view of the document.

The connection chain has three parts:

Document Editor frontend (browser)
        |
        |  WebSocket, for example wss://localhost:7118/api/TXWebSocket
        v
WebSocketMiddleware (your ASP.NET Core application, package TXTextControl.Web)
        |
        |  TCP, port 4283 by default
        v
TXTextControl.Web.Server.Core (backend process, package TXTextControl.Web.DocumentEditor.Backend)

1. The frontend runs in the browser. It opens a WebSocket connection to your ASP.NET Core application and exchanges every change with the server over this connection.
2. The WebSocket middleware runs in your ASP.NET Core application. You enable WebSockets with app.UseWebSockets() and add the middleware with app.UseTXWebSocketMiddleware(). The middleware accepts the WebSocket connections of the editors and forwards them to the backend process over TCP. For plain JavaScript pages, it also serves the editor script tx-document-editor.min.js.
3. The backend process TXTextControl.Web.Server.Core is a .NET application that runs on Windows and Linux. It synchronizes the documents, keeps the live state of every open document and performs layout calculations for the editor. It uses the Core engine, so an application that hosts it also installs TXTextControl.TextControl.Core.SDK.

The TXTextControl.Web.DocumentEditor.Backend package contains the files of the backend process and copies them to the build and publish output. Its hosted service DocumentEditorWorkerManager starts the process when your application starts, forwards its output to the ASP.NET Core logging, and stops it when your application shuts down. You register it with builder.Services.AddHostedService<DocumentEditorWorkerManager>().

Running the backend in its own process isolates the editing sessions from your web application, and both can be scaled separately. In version 32.0 and earlier, this backend was a Windows service, which older articles call the TCP synchronization service. In ASP.NET Core applications, version 33.0 replaced it with the cross-platform TXTextControl.Web.Server.Core application; ASP.NET applications on the .NET Framework deploy the Windows service, also in 34.0. Some articles written for version 33.0 copy its files from the setup folder and start the process with their own code. The backend package replaces these manual steps.

Where the Backend Process Runs

By default, DocumentEditorWorkerManager starts the backend process on the same machine, and app.UseTXWebSocketMiddleware() without parameters connects to it. The backend can also listen on another address and port, or run on its own machine or in its own container; the middleware then needs the same address and port. Configure the Backend Process in the Document Editor section describes both configuration files and the separate setup.

Document Viewer

The Document Viewer uses HTTP requests instead of a WebSocket connection, and it does not need the Document Editor backend process. Your ASP.NET Core application loads the document and renders its pages with the TX Text Control engine.

Document Viewer frontend (browser)
        |
        |  HTTP requests to the TextControl controller
        v
Document Viewer backend (your ASP.NET Core application, package TXTextControl.Web.DocumentViewer)
        |
        |  in the same process
        v
TX Text Control engine (Core or Classic package)

• The frontend is a web component with the element name tx-document-viewer. It requests the pages from the backend and displays them. The backend sends pages as soon as they are rendered, so users can start reading a large document before all pages are ready.
• The backend is a controller named TextControl that the TXTextControl.Web.DocumentViewer package adds to your ASP.NET Core application. In an ASP.NET Core MVC application, the template's controller routing is enough. Applications without MVC views, such as Web API backends, add the viewer with app.UseTXDocumentViewer().
• The engine renders the pages as bitmaps, as vector graphics (SVG) or with the actual fonts. By default, the viewer chooses the mode automatically.

The viewer package depends on the engine you use: TXTextControl.Web.DocumentViewer works with the Core package, TXTextControl.Web.DocumentViewer.Classic with the Classic package, as the table in The Document Engine shows.

When a user signs a document in the viewer, your backend receives the signed document and can digitally sign it with a certificate.

Frontends and the ASP.NET Core Backend

Every Document Editor and Document Viewer frontend needs an ASP.NET Core backend with TX Text Control .NET Server. The frontend either lives in the same application as the backend or is a separate client application.

The Blazor components are installed from nuget.org. In the same application, the frontend needs no connection settings. A separate client application needs the address of the backend:

• Document Editor: the webSocketURL setting contains the backend address with the wss protocol and the path /api/TXWebSocket, for example wss://localhost:7118/api/TXWebSocket. Use ws when the backend runs on HTTP. The Document Editor needs no CORS policy.
• Document Viewer: the basePath setting contains the URL of the backend, for example https://localhost:7275. Because the client application and the backend run on different origins, the backend must allow cross-origin requests (CORS).

All Document Editor frontends use the same JavaScript API, the TXTextControl object. The ASP.NET Core, Angular, React and JavaScript frontends of the Document Viewer share the TXDocumentViewer object. What you learn in one frontend applies to the others.

Scaling Beyond One Instance

In development and in smaller deployments, all parts run in one instance: the WebSocket middleware, the Document Editor backend process, the Document Viewer and your document processing code with ServerTextControl and MailMerge. When the number of concurrent users grows, Text Control recommends three services that scale on their own: application instances with the WebSocket middleware, the TXTextControl.Web.Server.Core backend, and a separate document processing application. Because a Document Editor session is tied to the backend instance that holds its live document, a load balancer needs sticky sessions. Container Scaling describes the three workloads and their sizing.

Next Steps

• Components: what each component does, with its packages and key classes.
• Supported Platforms: operating systems, .NET versions, containers and cloud platforms for Core and Classic.
• Document Editor in Getting Started: set up the connection chain in your first application.
• Deployment Guide: run the application and the backend process on Windows, Linux, Docker and in the cloud.