# Migrating From Previous Versions

> Migrate to TX Text Control .NET Server 34.0 from 33.0, assembly references, ASP.NET MVC, Classic, the Offline Packages or the old Document Editor service.

- **Product:** TX Text Control .NET Server
- **Section:** Documentation
- **Kind:** Topic
- **Path:** TX Text Control .NET Server > Installation Guide > Upgrade Guide > Migrating From Previous Versions
- **4223 words**
- **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/installation/upgrading/previous-versions/
- **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/installation/upgrading/previous-versions/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/installation/upgrading/previous-versions/llms-full.txt

---

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](https://docs.textcontrol.com/tx-text-control-dotnet-server/installation/upgrading/breaking-changes/llms-full.txt) of the versions you skip.

### Choose Your Starting Point

| Your application today | Section on this page |
|---|---|
| Uses the 33.0 NuGet packages | From 33.0 to 34.0 with NuGet Packages |
| A .NET project that references TX Text Control assemblies from the installation folder | From Assembly References to NuGet Packages |
| An ASP.NET MVC application on the .NET Framework | From ASP.NET MVC on the .NET Framework to ASP.NET Core |
| Uses `TXTextControl.TextControl.ASP.SDK` and should run on Linux or in Linux containers | From Classic to Core |
| Installs the packages from the Text Control Offline Packages source | From the Offline Packages to the Private NuGet Feed |
| Runs the Document Editor with the TX TextControl Service or with manually copied backend files | From the Old Document Editor Backend to the Backend Package |
| Uses *licenses.licx* | License File Changes |

### 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](https://www.textcontrol.com/contact/).
2. **Read the 34.0 entries** in [Breaking Changes](https://docs.textcontrol.com/tx-text-control-dotnet-server/installation/upgrading/breaking-changes/llms-full.txt).
3. **Update the SDK package and the web packages** to the newest 34.x versions, for example:

    ```bash
    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](https://docs.textcontrol.com/tx-text-control-dotnet-server/installation/upgrading/nuget/llms-full.txt) 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](https://docs.textcontrol.com/tx-text-control-dotnet-server/installation/upgrading/npm/llms-full.txt).
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](https://docs.textcontrol.com/tx-text-control-dotnet-server/installation/nuget/packages/llms-full.txt).
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](https://www.textcontrol.com/blog/2023/07/13/upgrading-an-aspnet-mvc-web-application-to-an-aspnet-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](https://learn.microsoft.com/en-us/dotnet/core/porting/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](#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](https://docs.textcontrol.com/tx-text-control-dotnet-server/getting-started/document-editor/aspnet-core/llms-full.txt) and [Document Viewer: ASP.NET Core](https://docs.textcontrol.com/tx-text-control-dotnet-server/getting-started/document-viewer/aspnet-core/llms-full.txt). 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](https://docs.textcontrol.com/tx-text-control-dotnet-server/overview/architecture/#the-document-engine) 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:**

    ```bash
    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](https://docs.textcontrol.com/tx-text-control-dotnet-server/deployment/linux/llms-full.txt) and [Docker](https://docs.textcontrol.com/tx-text-control-dotnet-server/deployment/docker/llms-full.txt).

### From the Offline Packages to the Private NuGet Feed

The [Text Control Private NuGet Feed](https://docs.textcontrol.com/tx-text-control-dotnet-server/installation/nuget/private-feed/llms-full.txt) 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](https://docs.textcontrol.com/tx-text-control-dotnet-server/installation/nuget/private-feed/api-token/llms-full.txt).
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](https://docs.textcontrol.com/tx-text-control-dotnet-server/installation/nuget/public-packages/#web-packages-on-nuget-org-and-on-the-private-feed) 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](https://docs.textcontrol.com/tx-text-control-dotnet-server/installation/nuget/private-feed/ci-cd/llms-full.txt).

### 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:

| Version | Backend |
|---|---|
| 32.0 and earlier | TX TextControl Service, a Windows service installed with *txregwebsvr.exe* |
| 33.0 | `TXTextControl.Web.Server.Core`, a .NET 8 application. The tutorials copy its files into the project and start it with their own hosted service class `TXWebServerProcess`. |
| 34.x | The `TXTextControl.Web.DocumentEditor.Backend` package with the hosted service `DocumentEditorWorkerManager` |

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:

```csharp
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();
```

1. **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*:

    <pre>{
  "DocumentEditorWorker": {
    "Port": 4567,
    "ListenAddress": "192.168.3.19"
  }
}</pre>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.

```csharp
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);
```

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

2. **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 <code>txregwebsvr.exe /u /d</code> 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:

| Project | License mechanism | What to do when you upgrade |
|---|---|---|
| .NET Framework with assembly references from the setup | *licenses.licx*, compiled by the .NET license compiler (lc.exe) | Change the version numbers in *licenses.licx* to the new version. Since 30.0, every entry must contain the full version number. |
| .NET (not .NET Framework) with NuGet packages before 32.0 Service Pack 2 | *licenses.licx* | Update the packages. The update removes *licenses.licx* and adds the new license file. Existing licenses continue to work. If *licenses.licx* is still in the project, delete it. |
| .NET with NuGet packages of 32.0 Service Pack 2 or later | The license file *txtextcontrol.server.license*, compiled into the assembly as an embedded resource | Nothing. Keep the file private: it contains encrypted serial number information and must not be given to others or distributed. |
| Packages from the private NuGet feed (34.0) | The license is injected into the package on the server before the download | Nothing. There is no license file to manage and no activation dialog. |

#### 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](https://docs.textcontrol.com/tx-text-control-dotnet-server/installation/licensing/development/#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](https://docs.textcontrol.com/tx-text-control-dotnet-server/deployment/windows/dotnet-framework/llms-full.txt).

### Next Steps

- [Breaking Changes](https://docs.textcontrol.com/tx-text-control-dotnet-server/installation/upgrading/breaking-changes/llms-full.txt): all changes per version.
- [Updating NuGet Packages](https://docs.textcontrol.com/tx-text-control-dotnet-server/installation/upgrading/nuget/llms-full.txt): update, rebuild, redeploy and verify.
- [Development Licenses](https://docs.textcontrol.com/tx-text-control-dotnet-server/installation/licensing/development/llms-full.txt): how licenses reach your project.
- [Deployment Guide](https://docs.textcontrol.com/tx-text-control-dotnet-server/deployment/llms-full.txt): deploy the migrated application.

---

## Nearby

- **Previous:** [Breaking Changes](https://docs.textcontrol.com/tx-text-control-dotnet-server/installation/upgrading/breaking-changes/llms-full.txt)
- **Next:** [Getting Started](https://docs.textcontrol.com/tx-text-control-dotnet-server/getting-started/llms-full.txt)