Migrating From Previous Versions

The way to the current version of TX Text Control .NET Server depends on where an existing application starts. Step-by-step instructions cover typical starting points, each in a self-contained section, so pick the ones that describe your application. Before you start, read the Breaking Changes of the versions you skip.

Choose Your Starting Point

From 33.0 to 34.0 With NuGet Packages

Both versions require .NET 8 or higher, so the target framework of your project can stay as it is.

1. Check your access to 34.0. The private NuGet feed only shows the versions you are licensed for. Run dotnet package search "TXTextControl" --source TextControl and check that 34.x versions are listed. For questions about your subscription, contact the Text Control sales team.

2. Read the 34.0 entries in Breaking Changes.

3. Update the SDK package and the web packages to the newest 34.x versions, for example:

   dotnet add package TXTextControl.TextControl.Core.SDK --version 34.0.5
   dotnet add package TXTextControl.Web --version 34.5.0
   dotnet add package TXTextControl.Web.DocumentViewer --version 34.2.0
   

   See Updating NuGet Packages for the Visual Studio steps and the complete package list.

4. Check the Document Viewer package. If your project uses the Classic engine (TXTextControl.TextControl.ASP.SDK) with the Document Viewer, check whether TXTextControl.Web.DocumentViewer.Classic is the right package for you. Its README lists the Classic assemblies as dependencies, while TXTextControl.Web.DocumentViewer lists the Core assemblies.

5. Switch the Document Editor backend to the backend package if you followed the 33.0 tutorials and copied the TXTextControl.Web.Server.Core files into your project. See "From the Old Document Editor Backend to the Backend Package" below.

6. Update the npm packages of an Angular or React frontend to 34.x. The React Document Editor 34.0.0 requires React ^19.2.0, and the Angular Document Editor 34.0.0 requires Angular 18.2.14 or higher. See Updating npm Packages.

7. Rebuild and test. Pay attention to ribbon and context menu customizations of the Document Editor on the Core engine and to the PDF documents your application creates, because both changed in 34.0.

8. Deploy the application.

From Assembly References to NuGet Packages

The NuGet SDK packages are for .NET 8 and higher. If your project still targets the .NET Framework, migrate it to .NET first, as described in the next section.

1. Upgrade the target framework of the project to .NET 8 or higher if it targets an older .NET version.
2. Remove the references to the TX Text Control assemblies. When you upgrade a .NET Framework project, the TX Text Control references are not converted automatically, and Visual Studio marks them with a yellow warning triangle.
3. Install the NuGet packages. Choose Manage NuGet Packages... from the Project menu, select the TextControl package source and install the SDK package, for example TXTextControl.TextControl.Core.SDK, and the web packages your application uses. See Package Overview.
4. Delete licenses.licx. Select the file in Solution Explorer and delete it. The NuGet packages bring their own license file.
5. Set the entry assembly if TX Text Control is used in a class library that is called from other assemblies. See "License File Changes" below.
6. Rebuild the project and run it.

When you publish the application, the SDK package copies the TX Text Control assemblies and the native, platform-specific files to the output automatically. You no longer copy the redistributable files from the installation folder.

From ASP.NET MVC on the .NET Framework to ASP.NET Core

Text Control describes this migration in the blog post Upgrading an ASP.NET MVC Web Application to an ASP.NET Core Web App. The following steps combine it with the packages and configuration of the current version.

1. Convert the project with Microsoft's migration tools. The blog post uses the .NET Upgrade Assistant with a side-by-side incremental project upgrade. Microsoft has since deprecated the .NET Upgrade Assistant and recommends the GitHub Copilot modernization chat agent, which is included with Visual Studio 2026. See the .NET Upgrade Assistant Overview on Microsoft Learn.
2. Don't convert TXWebSocketController. An ASP.NET Core application doesn't need this controller.
3. Install the NuGet packages. The TX Text Control references are not converted, so install the packages from the TextControl package source. Text Control recommends the Core engine for applications that you migrate to .NET 8 or higher. For an application with the Document Editor, install TXTextControl.TextControl.Core.SDK, TXTextControl.Web and TXTextControl.Web.DocumentEditor.Backend. For the Document Viewer, install TXTextControl.Web.DocumentViewer. If the application needs DOC files, read "From Classic to Core" below before you choose the SDK package.
4. Configure Program.cs. Add the hosted backend service and the WebSocket middleware, as step 3 of From the Old Document Editor Backend to the Backend Package shows.
5. Check the views. The HTML helper @Html.TXTextControl().TextControl() from the TXTextControl.Web.MVC namespace is used in ASP.NET Core views the same way as in ASP.NET MVC views.
6. Delete licenses.licx if it is still part of the project, then rebuild and test the application.

The complete setup is shown in Document Editor: ASP.NET Core and Document Viewer: ASP.NET Core. If the old application used the TX TextControl Service for the Document Editor, see "From the Old Document Editor Backend to the Backend Package" below.

From Classic to Core

Text Control recommends the Core engine for new .NET 8 and higher applications and for applications that you migrate to .NET 8 or higher. Linux and Linux containers require it. The Classic engine remains the choice for Windows-only applications that need the legacy Word binary format (DOC).

What Changes

Your code stays the same, because both packages contain the ServerTextControl class in the TXTextControl namespace. What changes is the package, the platforms, the rendering and the fonts: Core renders with its own SVG-based engine and the fonts of its Fonts folder instead of GDI and the system fonts, and it doesn't load or save DOC files. RTF documents and EMF images are available in Core since version 34.0. Core and Classic compares the engines in full.

Steps

1. Check your formats. Search your code for StreamType.MSWord and BinaryStreamType.MSWord. The Core engine can't load or save DOC files. If your application needs RTF documents or EMF images, use version 34.0 or later.

2. Replace the SDK package:

   dotnet remove package TXTextControl.TextControl.ASP.SDK
   dotnet add package TXTextControl.TextControl.Core.SDK
   

3. Replace the Document Viewer package if your project uses TXTextControl.Web.DocumentViewer.Classic: install TXTextControl.Web.DocumentViewer instead.

4. Provide the fonts. The Core engine doesn't use the fonts installed on the system. The package adds a Fonts folder with a standard set of serif and sans-serif fonts. If your documents use other fonts, copy them to the Fonts folder when you deploy the application.

5. Target a supported runtime. The Core package contains native files for win-x64 and linux-x64.

6. Compare the results. Because the rendering engine and the fonts change, compare the documents and PDF files your application creates with the output of the Classic version.

7. Deploy. For Linux, see Linux and Docker.

From the Offline Packages to the Private NuGet Feed

The Text Control Private NuGet Feed delivers the packages with the license already injected, so developer machines and build servers get them without the setup. The package IDs don't change.

1. Get a nuget.config file. The account owner assigns a serial number to your email address in Manage Products. You then receive an email with a download link for your personal nuget.config, which contains the feed URL, your email address and an API token. See Creating an API Token.
2. Copy nuget.config to the root folder of your project. The file contains your credentials, so don't commit it to source control.
3. Install the packages from the feed. In Visual Studio, choose Manage NuGet Packages..., select TextControl as the package source and install or update the TX Text Control packages. With the .NET CLI, list the available packages with dotnet package search "TXTextControl" --source TextControl and install them with dotnet add package.
4. Install the web packages from the feed as well. The private feed provides TXTextControl.Web and TXTextControl.Web.DocumentViewer; their copies on nuget.org require the trial version on the development machine, as Public NuGet Packages explains.
5. Update your build pipelines. Store the email address and the API token as secrets and create nuget.config during the build. See CI/CD Authentication.

From the Old Document Editor Backend to the Backend Package

The Document Editor needs a backend process that synchronizes the documents. In ASP.NET Core applications, its form changed over the versions:

The backend package includes the worker files in the build output and in the output of dotnet publish, starts the worker process when your application starts, and stops it when the application shuts down. It requires the Core engine. An ASP.NET application on the .NET Framework keeps the TX TextControl Service, which Text Control still documents for 34.0.

Steps

1. Install the packages TXTextControl.TextControl.Core.SDK, TXTextControl.Web and TXTextControl.Web.DocumentEditor.Backend in the 34.x versions.

2. Remove the 33.0 workaround if your project has one: delete the class TXWebServerProcess, its registration builder.Services.AddHostedService<TXWebServerProcess>() and the TXTextControl.Web.Server.Core files you added to the project manually.

3. Register the backend and the middleware in Program.cs. If your project still uses app.UseMiddleware<TXTextControl.Web.WebSocketMiddleware>(), replace it:

   using TXTextControl.Web;
   using TXTextControl.Web.DocumentEditor.Backend;
   
   var builder = WebApplication.CreateBuilder(args);
   
   builder.Services.AddControllersWithViews();
   builder.Services.AddHostedService<DocumentEditorWorkerManager>();
   
   var app = builder.Build();
   
   app.UseRouting();
   
   // after UseRouting and before the endpoint mappings
   app.UseWebSockets();
   app.UseTXWebSocketMiddleware();
   
   // other middleware and endpoint mappings of your application
   
   app.Run();
   

4. Configure the port, if needed. Without configuration, the worker uses its defaults (TCP port 4283) and the parameterless UseTXWebSocketMiddleware() connects to it. To use another address and port, add them to appsettings.json:

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

   Then bind the options and pass the same values to the middleware. If the values don't match, the Document Editor can't connect to the backend.

   builder.Services.Configure<DocumentEditorWorkerOptions>(builder.Configuration.GetSection("DocumentEditorWorker"));
   builder.Services.AddHostedService<DocumentEditorWorkerManager>();
   
   var app = builder.Build();
   app.UseRouting();
   app.UseWebSockets();
   app.UseTXWebSocketMiddleware("192.168.3.19", 4567);
   

5. Deploy the application. The worker runs as a separate dotnet process, so the .NET runtime must be installed on the server.

6. Remove the old Windows service once no application uses it anymore. On the server, open a command prompt as an administrator in the folder of the service and run txregwebsvr.exe /u /d to uninstall the TX TextControl Service.

License File Changes

How the development license gets into your application depends on the project type and the version. Older versions compiled the license from licenses.licx with the .NET license compiler (lc.exe), which is not available in .NET 6 and later, so TX Text Control 32.0 Service Pack 2 introduced a license file for .NET projects:

Class Libraries

Since 32.0 Service Pack 2, a class library that contains the license can be called from assemblies without a TX Text Control license once it sets the static EntryAssembly property to itself. Class Libraries and Unit Tests shows the code.

Projects That Stay on the .NET Framework

.NET Framework applications continue to use licenses.licx. The easiest way to move such a project to a newer version is to uninstall the previous TX Text Control version before you install the new one. Visual Studio then adapts the project automatically. If more than one version is installed:

1. Open your project in Visual Studio.
2. Choose Add Reference... from the Project menu. In the dialog, remove the references to the previous TX Text Control version, add the references to the same assemblies of the new version from the Assembly folder of its installation and close the dialog.
3. Open licenses.licx and change the version number of the referenced TX Text Control assemblies to the version number of the new version.
4. Close and reopen Visual Studio.
5. Rebuild the project with Rebuild Solution.

When you deploy the updated application, replace the TX Text Control files on the server with those of the new version, and deploy the TX TextControl Service of the new version if the application uses the Document Editor. See .NET Framework Applications.

Next Steps

• Breaking Changes: all changes per version.
• Updating NuGet Packages: update, rebuild, redeploy and verify.
• Development Licenses: how licenses reach your project.
• Deployment Guide: deploy the migrated application.