TX Text Control .NET Server

ASP.NET MVC Mail Merge

Topic

ServerTextControl and MailMerge run in the controllers of an ASP.NET MVC 5 application on the .NET Framework as they do in ASP.NET Core: the controller creates a document, merges data into it and returns the result. What follows builds that application in Visual Studio 2022 with .NET Framework 4.8. The controller writes a bold heading and a merge field, fills the field from JSON data and shows the merged document as HTML in the view.

Legacy technology. The .NET Framework version of TX Text Control .NET Server runs on Windows only and uses the Classic engine. For a new application, start with Create Your First Application and Simple Mail Merge, which use the NuGet packages.

Prerequisites

  • Visual Studio 2022 and .NET Framework 4.8.
  • The Windows setup of TX Text Control .NET Server 34.0, trial or full version. It installs the assemblies to C:\Program Files\Text Control GmbH\TX Text Control 34.0.NET Server for ASP.NET\.

The setup installs this tutorial as a sample project in %USERPROFILE%\Documents\TX Text Control 34.0.NET Server for ASP.NET\CSharp\MVC\mailmerge\.

The project uses no NuGet package of TX Text Control. It references the assemblies of the setup and needs neither the TX TextControl Service nor a WebSocket connection, because no editor runs in the browser.

Create the Project

  1. In Visual Studio 2022, choose Create a new project.

  2. Select ASP.NET Web Application (.NET Framework) as the project template and confirm with Next.

  3. Enter a project name, select .NET Framework 4.8 as the Framework and confirm with Create.

  4. In the next dialog, choose MVC as the project template and confirm with Create.

    The Create a new ASP.NET Web Application dialog of Visual Studio with the MVC template selected and only MVC checked under Add folders & core references.

Add the TX Text Control References

  1. With the project selected in Solution Explorer, choose Project > Add Project Reference... and click Browse... in the Reference Manager.
  2. From the Assembly folder of the installation, select TXDocumentServer.dll, TXTextControl.dll and TXTextControl.Server.dll.
  3. From the Assembly\bin64 folder, select tx34.dll, tx34_ic.dll and tx34_tls.dll.
  4. Close the Reference Manager with OK.

TXTextControl.Server.dll contains ServerTextControl, and TXDocumentServer.dll contains MailMerge. The three files from bin64 are the 64-bit native files of the engine; a 32-bit application uses the files of the same names from Assembly\bin.

Add the License File

  1. Choose Project > Add New Item..., select Text File, name it licenses.licx and click Add.

    The Add New Item dialog of Visual Studio with the Text File template selected and licenses.licx entered as the name.

  2. Paste this line into the file and save it:

    TXTextControl.ServerTextControl, TXTextControl.Server, Version=34.0.1900.500, Culture=neutral, PublicKeyToken=6b83fe9a75cfb638

The build compiles the license of ServerTextControl into your application from this line. The line must contain the full version of the referenced TXTextControl.Server.dll; after an upgrade, change it to the new version. See License File Changes.

Write the Controller

Open HomeController.cs in the Controllers folder and replace its Index() method with the following method. The other actions of the template stay as they are.

public ActionResult Index()
{
    using (TXTextControl.ServerTextControl tx = new TXTextControl.ServerTextControl())
    {
        // Initialize the new instance before using it
        tx.Create();

        // Add static text in bold
        TXTextControl.Selection sel = new TXTextControl.Selection();
        sel.Text = "Welcome to Text Control\r\n";
        sel.Bold = true;

        tx.Selection = sel;

        // Add a merge field
        TXTextControl.DocumentServer.Fields.MergeField mergeField =
            new TXTextControl.DocumentServer.Fields.MergeField()
            {
                Text = "{{company}}",
                Name = "company",
                TextBefore = "Company name: "
            };

        tx.ApplicationFields.Add(mergeField.ApplicationField);

        // Merge the data into the merge field
        using (TXTextControl.DocumentServer.MailMerge mailMerge =
            new TXTextControl.DocumentServer.MailMerge())
        {
            mailMerge.TextComponent = tx;
            mailMerge.MergeJsonData("[{\"company\": \"Text Control, LLC\" }]");
        }

        // Save the result as HTML for the view
        string result = "";
        tx.Save(out result, TXTextControl.StringStreamType.HTMLFormat);

        ViewBag.Document = result;
    }

    return View();
}

An action of an ASP.NET MVC 5 controller returns ActionResult. The IActionResult interface of ASP.NET Core doesn't exist in MVC 5, and a method declared with it doesn't compile there.

What the Code Does

Show the Result in the View

Open Index.cshtml in the Views/Home folder and replace its complete content with:

@{
    ViewData["Title"] = "Home Page";
}

@Html.Raw(ViewBag.Document)

Html.Raw writes the HTML string into the page without encoding it.

Run the Application

Press F5 to build and start the application. The home page shows the bold line "Welcome to Text Control" and below it "Company name: Text Control, LLC".

Return a PDF Instead

To send the merged document as a PDF file, save it with BinaryStreamType.AdobePDF and return it with the File method of the MVC 5 controller. Replace the lines from // Save the result as HTML for the view to the end of the using block with:

        // Save the result as PDF and send it to the browser
        byte[] baPdf;
        tx.Save(out baPdf, TXTextControl.BinaryStreamType.AdobePDF);

        return File(baPdf, "application/pdf", "result.pdf");
    }
}

The final return View(); of the method is then no longer reached and can be removed.

Merge a Template From a File

Instead of creating the document in code, load a Word template that contains merge fields. Copy template.docx to the App_Data folder of the project and replace the lines that create the selection and the merge field with:

        // Load a DOCX template with MS Word merge fields
        TXTextControl.LoadSettings ls = new TXTextControl.LoadSettings()
        {
            ApplicationFieldFormat = TXTextControl.ApplicationFieldFormat.MSWord
        };

        tx.Load(Server.MapPath("~/App_Data/template.docx"),
            TXTextControl.StreamType.WordprocessingML, ls);

ApplicationFieldFormat set to MSWord imports the Word fields of the template as application fields; without it, the template has no fields to merge. Merge Fields explains fields and templates in detail.

Next Steps