The browser-based document editor requires 3 components:

  1. Client-side package (ASP.NET NuGet, Angular npm)
  2. Server-side WebSocketHandler (Node.js or ASP.NET on Linux or Windows)
  3. Document Synchronization TCP Service (Windows)

To synchronize the document and to provide the unique true WYSIWYG rendering, the client-side component opens a WebSocket connection to a WebSocketHandler. This can be an ASP.NET (Core) Web Application or a Node.js package that is hosted on Windows or Linux.

The third required component is the synchronization service that must be hosted on a Windows machine. Thanks to the flexible setup, these 3 components can be deployed independently.

Learn More

TX Text Control Document Editor Deployment Strategies

If this connection is somehow failing under rare conditions, users will get a trappable error.

Error

This article explains potential reasons and solutions for each case.

Potential Reasons

The following list contains potential reasons why a connection cannot be established or is disconnected.

No Internet Connection

TX Text Control requires an active Internet connection. Make sure that the client-machine has full Internet connectivity. The client-side component opens a constant WebSocket connection to the WebSocketHandler running within the WebSocketServer. When the connection is lost, TX Text Control is trying to reconnect to the same instance for a specific period of time. If the connection is successfully re-established, unsaved changes are not lost and the complete document state is still available.

The default time the editor is trying to reconnect is 30 seconds. After that, the connection is lost and the service instance is closed. This ReconnectTime can be adjusted in seconds in the settings as shown here for the MVC Html Helper:

@Html.TXTextControl().TextControl(settings => {
settings.ReconnectTimeout = 20;
}).Render()
view raw test.cshtml hosted with ❤ by GitHub

In case it is not possible to re-establish the connection, TX Text Control provides an event that can be used to handle such situations.

Mixed Versions - Wrong Deployment

A common problem is the deployment of mixed file versions of TX Text Control assemblies and required dependencies. It is very important that all files are based on the same service pack release. A mix of versions (for example 29.0 server-side and 30.0 client-side) might cause connectivity issues.

When deploying the required files, make sure that all distributed files are up-to-date and match the release and service pack version.

Pro Tip

When deploying the editor, deploy the latest version of TX Text Control (Service) and update the client-side packages (npm or NuGet).

In case, you are using TX Text Control in your ASP.NET Web Application (ServerTextControl and MailMerge), you might want to check the distributed files in 3 locations:

  • Client-side package version (NuGet or npm)
  • Web application folder (or bin for ASP.NET applications)
  • Service folder that contains the registered TCP Windows Service.

Wrong Web API Endpoint Location and Static Resources

The ASP.NET DocumentEditor NuGet package is adding static resources such as images, icons and JavaScript sources to an application that are required by the editor. By default, these static files are expected in the TXTextControl.Web folder location in the root of your web application. Additionally, the Web API calls to the WebSocketHandler are expected to be handled in the root of the application.

When deploying the application to a server, the default settings will work out-of-the-box when the application runs on the application's root such as:

https://demos.textcontrol.com

To define the static resource folder, the StaticFilesPath ╰ TX Text Control .NET Server for ASP.NET
╰ Web.MVC Namespace
╰ TextControlSettings Class
╰ StaticFilesPath Property
Specifies or returns the path for static files. property can be used. In this sample, we set the relative path to the static resource folder in the WebApplication120 sub-folder:

@using TXTextControl.Web.MVC
@Html.TXTextControl().TextControl(settings => {
settings.StaticFilesPath = "/WebApplication120/TXTextControl.Web";
}).Render()
view raw test.cshtml hosted with ❤ by GitHub

Read More

Learn more about how to set the static files path in ASP.NET Core applications.

ASP.NET DocumentEditor: Set Static Files Path

In order to define the Web API endpoint location, the APIRoute ╰ TX Text Control .NET Server for ASP.NET
╰ Web.MVC Namespace
╰ TextControlSettings Class
╰ APIRoute Property
Determines the API directory in the MVC project in which to find the WebSocket and print handlers. property can be used:

@using TXTextControl.Web.MVC
@Html.TXTextControl().TextControl(settings => {
settings.StaticFilesPath = "/WebApplication120/TXTextControl.Web";
settings.APIRoute = "WebApplication120/api";
}).Render()
view raw test.cshtml hosted with ❤ by GitHub

Client-Side Firewalls: Deep Packet Inspection

WebSockets use port 80, the same port like usual HTTP traffic. Port 80 is usually open on networks and is not blocked. Some older firewalls block WebSockets by checking the packets of port 80. In this case, adding SSL support (port 443) solves this problem.

In case WebSockets are generally blocked by the firewall security, the TX Text Control document editor cannot be used. WebSockets must be enabled and allowed in the network security policy.

Server-Side Firewalls

In case, the TCP Service is deployed to a separate server, it is important to open specific TCP ports on the servers that run the TCP service. The ASP.NET Core Web Application communicates with the installed service using pure TCP on a fixed port number. TCP traffic must be allowed on this specific port.

The port numbers are consecutive:

  • Version 32.0: 4281
  • Version 31.0: 4280
  • Version 30.0: 4279

Learn More

Deploying the TX Text Control Document Editor to Linux -> Adjusting Firewalls

Load Balancing and Gateways

Whether you are deploying the TCP service separately or run the service on the same machine like the WebSocketHandler, when integrating load balancers or gateways, it is important to pick a session persistance algorithm such as sticky sessions.

Learn More

Using an Azure Load Balancer with Web.TextControl

Unhandled Text Control Error

In case, an unhandled Text Control error creates a situation where the service process instance in unstable or not usable anymore, the connection is getting disconnected automatically. In these cases, you will find a log entry in the Windows Event Viewer.

Debugging and Solutions

Event Handling

In case, the connection is lost or cannot be established, the webSocketClosed event is fired and informs about the reason. This event can be used to trigger an action like an UI update to inform users about the disconnection.

TXTextControl.addEventListener("webSocketClosed", function(e) { console.log(e) });
view raw test.js hosted with ❤ by GitHub

Learn More

Automatically Reconnect to the Server and Recover the Document

Event Viewer Logs

To find the log entries, open the Event Viewer, find the TX Text Control Service node in the Applications and Services Logs and filter for Level to list all Error entries.

Event Viewer TX Text Control

F12 Developer Tools Console

Many errors are shown in the client-side browser console. In order to see the console entries, open the F12 developer tools in your browser by pressing F12:

Event Viewer TX Text Control