IIS Hosting Troubleshooting — TX Text Control .NET Server

Under IIS, the worker process of the application pool starts the Document Editor backend as a child process: it comes up with the application, runs under the identity of the pool and ends when the worker process ends. Most problems on IIS therefore come from a setting of the server or of the application pool, and the fix is a change of that setting. IIS in the Deployment Guide describes the complete setup.

Read the Log of the Application

Errors during startup don't reach the browser. Turn on the log of the ASP.NET Core Module to see them:

In web.config, set stdoutLogEnabled="true" and stdoutLogFile=".\logs\stdout".
Create the logs folder and give the application pool write access to it.
Reproduce the problem and read the newest file in logs. The messages of the Document Editor backend have the prefix [TXTextControl.Web.Server.Core].
Switch the log off again after troubleshooting.

A backend that has started logs Starting TCP listener on port 4283 for IPv4 and IPv6. Microsoft's article Troubleshoot ASP.NET Core on Azure App Service and IIS explains the other sources of errors, such as the Windows event log.

The Site Answers With Error 500.30

The site answers with error 500.30: the application ended during startup. The log shows one of these messages:

The TX Text Control Web Server Core process requires a 64 bit environment. Please ensure that the application is running in a 64 bit environment.
The 64 bit .NET runtime was not found. Please ensure that the 64 bit .NET runtime is installed on this machine.

The first message means that the application pool runs 32-bit processes: set Enable 32-Bit Applications of the pool back to False, as Create the Site and the Application Pool describes, and publish for win-x64. The second means that the 64-bit .NET runtime isn't installed: install the .NET Hosting Bundle without the option OPT_NO_RUNTIME=1, as in Prepare the Server. Native Library / Runtime Errors describes both messages in detail.

The Site Doesn't Start After the Server Was Set Up

The site answers with an HTTP error in the 500 range, although the application runs on your development machine.

The .NET Hosting Bundle was probably installed before IIS, so the ASP.NET Core Module isn't registered, or IIS wasn't restarted afterward. Repair the bundle and restart IIS, as Prepare the Server describes. Microsoft's Common error troubleshooting for Azure App Service and IIS with ASP.NET Core lists the error codes of the ASP.NET Core Module and their causes.

The Editor Doesn't Connect

The page loads, but the editor shows that it can't connect to the server, and the browser console shows a failed WebSocket connection to /api/TXWebSocket.

IIS passes WebSocket requests on only when the Windows feature WebSocket Protocol is installed. Add it as Prepare the Server describes; Host the Connection names the feature on desktop versions of Windows. If the editor still doesn't connect, the cause isn't specific to IIS; see WebSockets.

Editors Lose Their Sessions After a While

Users who leave the editor open see Connection lost. Reconnecting…, and the reconnection fails, for example with Could not reconnect. Connection ID is unknown to the synchronization service. Unsaved changes are lost.

The backend ends with the worker process that started it, and by default IIS ends a worker process after 20 minutes without requests and recycles it at regular intervals. Set Idle Time-out (minutes) of the pool to 0 and Start Mode to AlwaysRunning, as Keep the Document Editor Backend Running describes.

Editors Can't Connect After a Recycle or on a Shared Server

After IIS recycles the application pool, or after a second application with the Document Editor was installed on the server, editors fail and the browser console shows a message such as:

WebSocketHandler.DoTalkingAsync(): Could not connect to TextControl TCP server at 127.0.0.1:4283

Two backends try to use the same port: an overlapping worker process during a recycle, or another application with the default port 4283. Set disallowOverlappingRotation of the pool to true and give each application its own port, as "Avoid Overlapping Worker Processes" and "Run Several Applications on One Server" in Keep the Document Editor Backend Running describe.

The Editor Doesn't Load in a Sub-Application

The application runs in a folder below the root site, and the editor doesn't load or connects to the wrong address.

In a sub-application, the address of the WebSocket handler includes the folder of the application, and IIS virtual directories aren't supported for ASP.NET Core applications at all. Host the application as a sub-application with its own pool and set TextControlSettings.APIRoute to the folder followed by /api, as Host the Application as a Sub-Application describes.

The Application Pool Has No Access to the Folder

The application can't read the files in its folder, or the log of the ASP.NET Core Module isn't written.

The application pool, and with it the backend and its worker processes, runs as IIS AppPool\<name of the pool>. Grant it read and execute permissions on the application folder, as Create the Site and the Application Pool shows, and write permissions on the logs folder while the log is turned on. Run With Least Privileges explains which rights the accounts need.

Documents Look Different With the Classic Engine

An application with the Classic engine, from the package TXTextControl.TextControl.ASP.SDK, creates documents with other fonts on the server than on the development machine. The Classic engine uses the fonts installed on Windows; install the fonts your documents use on the server, as Fonts With the Classic Engine describes, or move the application to the Core engine.

IIS