Printing

A service that prints delivery notes or merged letters sends documents to a printer without any user interface. ServerTextControl prints through the PrintDocument class of .NET, with the printer, page range and number of copies you choose, and it prints several documents in one print job. For web applications, a PDF that users print in the browser is often the better way.

Printing in the browser is described in Printing in the Document Viewer section and in Viewing and Printing in the Document Editor section.

Requirements

ServerTextControl.Print takes a System.Drawing.Printing.PrintDocument, which uses the printers installed on Windows. That class comes with System.Drawing.Common, a dependency of the Classic package TXTextControl.TextControl.ASP.SDK and not of the Core package, so the examples use Classic in a .NET console application on Windows, as the blog article Print MS Word DOCX Documents in .NET using C# Without Interop does. Create Your First Application compares the two packages.

Applications that run on Linux or in containers create a PDF instead and let users print it, as described in Let Users Print in the Browser.

Print a Document

The following program loads a DOCX document and prints it to the printer "Microsoft Print to PDF", which writes the output to a file:

using System.Drawing.Printing;
using TXTextControl;

using (ServerTextControl tx = new ServerTextControl())
{
    tx.Create();
    tx.Load("Documents/sample.docx", StreamType.WordprocessingML);

    PrintDocument printDocument = new PrintDocument();
    printDocument.DocumentName = "sample.docx";
    printDocument.PrinterSettings.PrinterName = "Microsoft Print to PDF";
    printDocument.PrinterSettings.PrintToFile = true;
    printDocument.PrinterSettings.PrintFileName = Path.GetFullPath("printed.pdf");

    // Print without a status dialog
    printDocument.PrintController = new StandardPrintController();

    tx.Print(printDocument);
}

The code works as follows:

• Print prints the document with the settings of the PrintDocument. Without PrinterName, the default printer is used.
• PrintToFile and PrintFileName send the output to a file instead of paper. Leave them out to print on the printer.
• By default, .NET shows a status dialog while a document is printed. A StandardPrintController prints without it, which is what a service or console application needs.

Print uses these settings of the PrintDocument: DocumentName, PrintController, DefaultPageSettings.Color and, in PrinterSettings, PrinterName, PrintToFile, FromPage, ToPage, Copies, Collate and PrintRange.

Print Pages, Copies and Collated Sets

To print part of a document, set FromPage and ToPage, and set PrintRange to PrintRange.SomePages so that the page numbers are used. The following program prints two collated copies of pages 2 and 3 on the default printer:

using System.Drawing.Printing;
using TXTextControl;

using (ServerTextControl tx = new ServerTextControl())
{
    tx.Create();
    tx.Load("Documents/sample.docx", StreamType.WordprocessingML);

    PrintDocument printDocument = new PrintDocument();
    printDocument.PrintController = new StandardPrintController();

    // FromPage and ToPage are only used with PrintRange.SomePages
    printDocument.PrinterSettings.PrintRange = PrintRange.SomePages;
    printDocument.PrinterSettings.FromPage = 2;
    printDocument.PrinterSettings.ToPage = 3;
    printDocument.PrinterSettings.Copies = 2;
    printDocument.PrinterSettings.Collate = true;

    Console.WriteLine($"The document has {tx.Pages} pages.");
    tx.Print(printDocument);
}

ServerTextControl.Pages returns the number of pages, which helps you check a page range before printing.

Print Several Documents in One Print Job

A second overload, Print(int page, PrintPageEventArgs e), prints a single page from the PrintPage event of a PrintDocument. With it, several documents go to the printer as one print job. The following program prints a letter and an invoice page by page and loads the next document when all pages of the current one are printed:

using System.Drawing.Printing;
using TXTextControl;

string[] files = { "Documents/letter.docx", "Documents/invoice.docx" };

using (ServerTextControl tx = new ServerTextControl())
{
    tx.Create();

    int fileIndex = 0;
    int pageNumber = 1;
    tx.Load(files[fileIndex], StreamType.WordprocessingML);

    PrintDocument printDocument = new PrintDocument();
    printDocument.DocumentName = "Letter and invoice";
    printDocument.PrintController = new StandardPrintController();

    printDocument.PrintPage += (sender, e) =>
    {
        tx.Print(pageNumber, e);
        pageNumber++;

        // All pages of this document are printed: load the next one
        if (pageNumber > tx.Pages)
        {
            fileIndex++;

            if (fileIndex < files.Length)
            {
                tx.Load(files[fileIndex], StreamType.WordprocessingML);
                pageNumber = 1;
            }
        }

        e.HasMorePages = fileIndex < files.Length;
    };

    printDocument.Print();
}

The code works as follows:

• printDocument.Print() starts the print job, and .NET raises PrintPage for each page.
• tx.Print(pageNumber, e) prints one page of the loaded document into the page that .NET is printing.
• e.HasMorePages tells .NET whether another page follows. It's false after the last page of the last document.

To print documents as one document with continuous page numbers instead, combine them with Append first, as described in Creating Documents.

Print Over a Background

Output that your own PrintPage handler draws, such as a watermark, an image or a form background, stays on the page: the document is printed transparently on top of it. The following handler, used in place of the one above for a single document, draws a gray "COPY" before it prints each page:

printDocument.PrintPage += (sender, e) =>
{
    // Drawn first, so the text of the page is printed on top of it
    using (System.Drawing.Font font = new System.Drawing.Font("Arial", 72))
    using (System.Drawing.Brush brush = new System.Drawing.SolidBrush(System.Drawing.Color.LightGray))
    {
        e.Graphics.DrawString("COPY", font, brush, 150, 400);
    }

    tx.Print(pageNumber, e);
    pageNumber++;
    e.HasMorePages = pageNumber <= tx.Pages;
};

Print a Merged Document

After a mail merge, the merged document is in the ServerTextControl, and tx.Print prints it like any other document. MailMerge.Print prints the merged document directly, either with a PrintDocument or with a document name, a printer name, a number of copies and a collate flag:

mailMerge.MergeJsonData(jsonData);
mailMerge.Print("Invoices", "Microsoft Print to PDF", 1, false);

Simple Mail Merge shows the merge that comes before these lines.

Choose the Formatting Printer

TX Text Control formats text with the measurements of a device: the exact character widths, kerning and spacing. ServerTextControl.FormattingPrinter sets the name of the printer whose measurements are used, so that a document printed on that printer has the same line and page breaks as on screen:

On a server, the formatting printer matters for two reasons:

• Templates look different on another machine when it formats with another printer. Using the same printer, or "Display" on both machines, avoids this, as the blog article WYSIWYG: What You Need to Know! explains.
• Printers slow down initialization. A network printer or a printer in energy-saving mode that responds late delays the creation of an instance, as the blog article Initialize Text Control Without a Printer (Completely) describes.

GetSupportedFonts and GetSupportedPaperSizes return the fonts and paper sizes of the formatting printer.

Let Users Print in the Browser

In a web application, users print on their own printers, not on the server's. Create a PDF on the server and let users print it:

• Save the document as PDF and return it from a controller, as Save as DOCX and PDF shows. Creating the PDF needs no printer driver.
• Show the document in the Document Viewer, whose Print button and printDocument method print it from the browser, as Printing in the Document Viewer section describes.

Next Steps

• Saving and Converting Documents: create the PDF that users print.
• Printing in the Document Viewer: print documents from the browser.
• Overview of Mail Merge and Reporting: create the documents you print from templates and data.