With the introduction of TXTextControl Web Server Core, TX Text Control now offers a fully cross-platform backend service for the Document Editor. The service runs independently from your ASP.NET Core web application and communicates through a dedicated TCP connection.

Learn more

This article demonstrates how to create a Document Editor ASP.NET Core application using the Text Control Private NuGet Feed. We will build a basic web application that enables users to edit documents directly in their web browser with the Document Editor component from Text Control. The backend is powered by the Private NuGet Feed, which provides seamless licensing and eliminates the need for setup.

ASP.NET Core Document Editor with Backend via the Text Control Private NuGet Feed

This separation is intentional. It enables scalable architectures, containerized deployments, and clean separation between UI and document processing services.

In this article, we will walk through how to configure the Web Server Core, explain how networking works, and demonstrate how your ASP.NET Core application connects to it through middleware.

Architecture Overview

The Web Server Core runs as a standalone process that is responsible for document processing and editor communication. Your ASP.NET Core application hosts the front end and connects to the back end via TCP socket and WebSocket middleware. This allows for flexible deployment scenarios, including running the Web Server Core on a different machine or in a containerized environment.

The communication flow looks like this:

1. The Web Server Core listens on a TCP port.
2. The TX Text Control WebSocket Middleware in your ASP.NET Core application connects to that port.
3. WebSocket middleware bridges browser clients to the backend worker process.

This design allows for true cross-platform deployment across Windows, Linux, and container environments. It provides clear process isolation, allowing system components to run independently and securely. Front-end and back-end services can be scaled separately based on workload, which improves performance and resource efficiency. Additionally, the architecture supports flexible networking configurations, making it easier to adapt to different infrastructures and deployment scenarios.

Configuring the Web Server Core

The Web Server Core reads its configuration from a JSON file located next to the executable (TXTextControl.Web.Server.Core.config.json). This file controls logging, networking, and IP support. By default, the Web Server Core listens on port 4282 and supports both IPv4 and IPv6. You can customize these settings to fit your deployment needs.

A typical configuration looks like this:

{
  "Logging": {
    "LogLevel": "Information",
    "FolderPath": "./logs",
    "FileName": "TXTextControl.Web.Server.Core.{date}.log"
  },
  "TcpPort": 5664,
  "SupportedIPVersions": "IPv4"
}

Logging Configuration

The logging section allows you to specify the log level and log file location. By default, logs are written to a file named TXTextControl.Web.Server.Core.{date}.log in ./logs subfolder. You can adjust the log level to control the verbosity of the logs (e.g., Debug, Information, Warning, Error).

The logging section defines how runtime activity is recorded.

TCP Port Configuration

The TcpPort setting specifies the port through which the Web Server Core receives incoming connections from the ASP.NET Core middleware. It is set to 4282 by default. You can change it to any available port that suits your network configuration.

"TcpPort": 5664

Important considerations:

• The port must be reachable from the web application.
• It must not conflict with other services.
• It must match the port configured in the middleware.
• In container environments, it must be exposed and mapped correctly.

Supported IP Versions

The SupportedIpVersions setting controls which IP versions the Web Server Core listens on. By default, it supports IPv4, IPv6 or Both. You can restrict it to only one version if needed.

"SupportedIPVersions": "IPv4"

Restricting to IPv4 is common in container or internal network deployments where IPv6 is not required. Supporting both allows for maximum compatibility across different network environments.

Connecting the Middleware to the Web Server Core

To connect to the Web Server Core, you need to configure the TX Text Control WebSocket Middleware in your ASP.NET Core application. This is done in the Program.cs file. Specify the same TCP port that the Web Server Core is listening on.

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

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllersWithViews();
builder.Services.AddHostedService<DocumentEditorWorkerManager>();

var app = builder.Build();

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();

// enable Web Sockets
app.UseWebSockets();

// attach the Text Control WebSocketHandler middleware
app.UseTXWebSocketMiddleware("127.0.0.1", 5664);

app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

Understanding the Middleware Connection

The key line is:

app.UseTXWebSocketMiddleware("127.0.0.1", 5664);

This tells the web application:

• connect to host 127.0.0.1 (localhost), replace with your server's IP if different
• connect to TCP port 5664

These values must match the Web Server Core configuration. If they do not, the editor will be unable to communicate with the backend, resulting in failed document processing.

Configuring the Worker with appsettings.json

The DocumentEditorWorkerManager starts the backend worker process using its internal default settings by default. This is often sufficient, especially during local development. However, production environments often require more explicit configuration.

When defining a custom IP address and port for the worker process, the WebSocket middleware must be configured with the same values. This ensures that the Document Editor can connect to the correct backend endpoint.

Example appsettings.json Configuration

The worker endpoint can be defined in the application configuration file:

{
  "DocumentEditorWorker": {
    "Port": 4567,
    "ListenAddress": "192.168.3.19"
  }
}

This configuration instructs the worker process to bind to a specific network interface and port.

Register the configuration in Program.cs

Then, register the configuration in your ASP.NET Core application. The following example shows how to load the configuration, start the worker service, and configure the WebSocket middleware.

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

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<DocumentEditorWorkerOptions>(builder.Configuration.GetSection("DocumentEditorWorker"));
builder.Services.AddHostedService<DocumentEditorWorkerManager>();

var app = builder.Build();
app.UseRouting();
app.UseWebSockets();

// IMPORTANT: Must match the configured ListenAddress and Port
app.UseTXWebSocketMiddleware("192.168.3.19", 4567);

app.MapRazorPages();
app.Run();

Why Matching the Endpoint is Important

When a custom listen address and port are configured, the worker process binds to that specific network endpoint. The WebSocket middleware must then connect to that same address so browser clients can communicate with the backend worker.

When a custom ListenAddress and Port are configured:

• The worker process binds to that specific IP address and port.
• The UseTXWebSocketMiddleware must point to the same endpoint.
• If the values do not match, the Document Editor will not be able to connect to the backend worker.

When Explicit Configuration is Recommended

Although the default configuration is effective for simple deployments, it is recommended that you explicitly configure endpoints in more advanced environments.

• Running the worker on a dedicated machine
• Binding to a specific network interface
• Hosting multiple worker instances
• Avoiding port conflicts
• Deploying in containerized environments
• Running behind load balancers or reverse proxies

Using the Default Configuration

If no custom worker configuration is provided, the system automatically reverts to its internal defaults. In this case, you can register the WebSocket middleware using the parameterless overload.

app.UseTXWebSocketMiddleware();

When the ASP.NET Core application starts, the Document Editor backend worker launches automatically. Any page that includes the HTML5 Document Editor then loads the editor interface and establishes a WebSocket connection to the worker process.