# Loading Documents

> Load DOCX, RTF, HTML and PDF with ServerTextControl: Load, Append or Selection.Load, LoadSettings, ASP.NET Core uploads, PDF passwords and FilterException.

- **Product:** TX Text Control .NET Server
- **Section:** Documentation
- **Kind:** Topic
- **Path:** TX Text Control .NET Server > Document Processing > Loading Documents
- **5153 words**
- **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/loading/
- **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/loading/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/loading/llms-full.txt

---

Documents arrive from files, databases, uploads and other applications, each in its own format. Beyond a single `Load` call, you decide whether a document replaces, extends or goes into the current content, control the import with `LoadSettings`, read information about the loaded document and handle uploads, passwords and errors.

The overloads of `Load` and the format enumeration for each source are in [Load a Document](https://docs.textcontrol.com/tx-text-control-dotnet-server/getting-started/document-processing/load/llms-full.txt), and PDF documents in [Load and Modify a PDF](https://docs.textcontrol.com/tx-text-control-dotnet-server/getting-started/pdf/load-modify/llms-full.txt). The examples below read their files from a *Documents* folder that is copied to the output directory.

### Load, Append or Insert

Three methods load a document into a `ServerTextControl`. They take the same sources and formats and an optional [LoadSettings](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsettings/llms-full.txt) object:

| Method | What happens to the existing content |
|---|---|
| [ServerTextControl.Load](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/servertextcontrol/load-method/llms-full.txt) | It's replaced completely |
| [ServerTextControl.Append](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/servertextcontrol/append-method/llms-full.txt) | It stays; the document is added at the end, as set by an `AppendSettings` value |
| [Selection.Load](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/selection/load-method/llms-full.txt) | The selected text is replaced; with nothing selected, the document is inserted at the input position |

The following program loads a letter, appends a signature and inserts an attachment in place of a placeholder:

```csharp
using TXTextControl;

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

    // Load replaces the complete contents
    tx.Load("Documents/letter.docx", StreamType.WordprocessingML);

    // Append adds a document at the end, here in a new paragraph
    tx.Append("Documents/signature.rtf", StreamType.RichTextFormat,
        AppendSettings.StartWithNewParagraph);

    // Selection.Load replaces the selected text, here a placeholder
    const string placeholder = "[ATTACHMENT]";
    int position = tx.Find(placeholder);

    if (position >= 0)
    {
        tx.Select(position, placeholder.Length);

        LoadSettings loadSettings = new LoadSettings()
        {
            // Create a new paragraph before the document is loaded
            AddParagraph = true
        };

        tx.Selection.Load("Documents/attachment.docx", StreamType.WordprocessingML, loadSettings);
    }

    tx.Save("result.docx", StreamType.WordprocessingML);
}
```

[LoadSettings.AddParagraph](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsettings/addparagraph-property/llms-full.txt) has an effect only with `Selection.Load`. With `false`, the default, the document is loaded into the existing paragraph, and the attributes of that paragraph and of the last loaded paragraph are merged; with `true`, a new paragraph is created first and takes the attributes of the last loaded paragraph. [Creating Documents](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/creating/#build-a-document-from-pieces) lists the `AppendSettings` values.

### Control the Import With LoadSettings

Properties of `LoadSettings` that you set before loading decide what is imported and how:

| Property | Sets | Default |
|---|---|---|
| [ApplicationFieldFormat](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsettings/applicationfieldformat-property/llms-full.txt) | Whether fields of MS Word documents, or the fields of Heiler HighEdit in RTF, are imported as application fields, for DOCX, DOC and RTF | `None` |
| [ApplicationFieldTypeNames](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsettings/applicationfieldtypenames-property/llms-full.txt) | The field types to import, such as `MERGEFIELD`, when `ApplicationFieldFormat` is `MSWord` | `null`, all types |
| [LoadSubTextParts](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsettings/loadsubtextparts-property/llms-full.txt) | Whether bookmarks that extend over several characters become subtext parts, for DOCX, DOC and RTF | `false` |
| [LoadImages](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsettings/loadimages-property/llms-full.txt) | Whether images are loaded; otherwise a rectangle with the image's name is shown | `true` |
| [LoadHypertextLinks](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsettings/loadhypertextlinks-property/llms-full.txt) | Whether hypertext links are loaded | `true` |
| [LoadDocumentBackColor](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsettings/loaddocumentbackcolor-property/llms-full.txt) | Whether the background color of the document is loaded | `true` |
| [ImageSearchPath](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsettings/imagesearchpath-property/llms-full.txt) | A folder that replaces the absolute file paths of linked images and other resources | — |
| [DocumentBasePath](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsavesettingsbase/documentbasepath-property/llms-full.txt) | A base path that resolves the relative file paths of the document | — |
| [PDFImportSettings](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsettings/pdfimportsettings-property/llms-full.txt) | How the structure of a PDF document is rebuilt | `GenerateTextFrames` |
| [DocumentPartName](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsettings/documentpartname-property/llms-full.txt) | The worksheet of an XLSX document to load | `null`, the first worksheet |
| [UserPassword](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsavesettingsbase/userpassword-property/llms-full.txt), [MasterPassword](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsavesettingsbase/masterpassword-property/llms-full.txt) | The passwords of an encrypted PDF document | — |

`LoadSettings` and [SaveSettings](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/savesettings/llms-full.txt) share a base class, [LoadSaveSettingsBase](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsavesettingsbase/llms-full.txt). It defines `DocumentBasePath`, the passwords, [EmbeddedFiles](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsavesettingsbase/embeddedfiles-property/llms-full.txt), [ReportingMergeBlockFormat](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsavesettingsbase/reportingmergeblockformat-property/llms-full.txt) and [DefaultStreamType](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsavesettingsbase/defaultstreamtype-property/llms-full.txt), so both classes have these properties. `DefaultStreamType` preselects a format in the **Open** and **Save As** dialog boxes of the desktop products and matters only where such a dialog box is shown; a server application passes the `StreamType` to `Load` and `Save` itself.

The following program loads a Word template with only its merge fields and its merge blocks, and without its hypertext links and background color:

```csharp
using TXTextControl;

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

    LoadSettings loadSettings = new LoadSettings()
    {
        ApplicationFieldFormat = ApplicationFieldFormat.MSWord,
        ApplicationFieldTypeNames = new string[] { "MERGEFIELD" }, // only merge fields
        LoadSubTextParts = true,        // bookmarks over several characters become subtext parts
        LoadHypertextLinks = false,
        LoadDocumentBackColor = false
    };

    tx.Load("Documents/template.docx", StreamType.WordprocessingML, loadSettings);

    Console.WriteLine($"Merge fields: {tx.ApplicationFields.Count}");
    Console.WriteLine($"Subtext parts: {tx.SubTextParts.Count}");
}
```

Merge blocks of a mail merge template are stored as subtext parts, which is why [Simple Mail Merge](https://docs.textcontrol.com/tx-text-control-dotnet-server/getting-started/mail-merge/simple/llms-full.txt) loads DOCX templates with `LoadSubTextParts` set to `true`. [Subtext Parts](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/subtext-parts/llms-full.txt) describes how to work with them.

### Read Information About the Loaded Document

After loading, the same `LoadSettings` object contains information about the document. These properties are read only:

| Property | Contains |
|---|---|
| `DocumentTitle`, `Author`, `CreationDate`, `UserDefinedDocumentProperties` and the other metadata | The metadata of the document and its values when the document has none, as [Where Metadata Lives](https://docs.textcontrol.com/tx-text-control-dotnet-server/pdf/metadata/#where-metadata-lives) lists |
| [LoadedStreamType](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsettings/loadedstreamtype-property/llms-full.txt), [BytesRead](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsettings/bytesread-property/llms-full.txt) | The format that was loaded and the number of bytes read |
| [PageSize](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsettings/pagesize-property/llms-full.txt), [PageMargins](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsettings/pagemargins-property/llms-full.txt) | The page size, 0 if the document has none, and the page margins, -1 if the document has none |
| [DocumentAccessPermissions](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/loadsettings/documentaccesspermissions-property/llms-full.txt) | The access permissions of a PDF document |

```csharp
using TXTextControl;

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

    LoadSettings loadSettings = new LoadSettings();
    tx.Load("Documents/sample.docx", StreamType.WordprocessingML, loadSettings);

    Console.WriteLine($"Format: {loadSettings.LoadedStreamType}, {loadSettings.BytesRead} bytes");
    Console.WriteLine($"Title: {loadSettings.DocumentTitle}");
    Console.WriteLine($"Author: {loadSettings.Author}");
    Console.WriteLine($"Last modified: {loadSettings.LastModificationDate}");

    if (loadSettings.UserDefinedDocumentProperties != null)
    {
        foreach (string name in loadSettings.UserDefinedDocumentProperties.Names)
        {
            Console.WriteLine($"{name}: {loadSettings.UserDefinedDocumentProperties[name]}");
        }
    }

    Console.WriteLine($"Pages: {tx.Pages}");
}
```

[ServerTextControl.DocumentSettings](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/servertextcontrol/documentsettings-property/llms-full.txt) is filled with the same metadata and keeps it for the next save. User-defined properties and their values are described in [Store Custom Properties](https://docs.textcontrol.com/tx-text-control-dotnet-server/pdf/metadata/#store-custom-properties).

### Load Uploaded Documents in ASP.NET Core

An uploaded file reaches an ASP.NET Core controller as a stream. `Load` has no overload for such streams, so copy the stream into a byte array first. The following action converts an uploaded DOCX document to PDF:

```csharp
using Microsoft.AspNetCore.Mvc;
using TXTextControl;

public class UploadController : Controller
{
    [HttpPost]
    public IActionResult ConvertToPdf(IFormFile document)
    {
        // Copy the upload into a byte array
        byte[] data;

        using (MemoryStream memoryStream = new MemoryStream())
        {
            document.CopyTo(memoryStream);
            data = memoryStream.ToArray();
        }

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

            try
            {
                tx.Load(data, BinaryStreamType.WordprocessingML);
            }
            catch (FilterException exception)
            {
                return BadRequest($"The document could not be loaded: {exception.Reason}");
            }

            byte[] pdf;
            tx.Save(out pdf, BinaryStreamType.AdobePDF);

            return File(pdf, "application/pdf",
                Path.GetFileNameWithoutExtension(document.FileName) + ".pdf");
        }
    }
}
```

[BinaryStreamType](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/binarystreamtype/enumeration/llms-full.txt) has values for DOCX, DOC, PDF, XLSX and the TX Text Control formats, but not for HTML and RTF. Load those formats from a string with `StringStreamType` or from a file with `StreamType`.

### Load Password-Protected PDF Documents

A PDF document that is protected with a user password can only be opened with that password. Without it, `Load` throws a [FilterException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/filterexception/llms-full.txt) whose [Reason](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/filterexception/reason-property/llms-full.txt) is `InvalidPassword`:

```csharp
using TXTextControl;

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

    try
    {
        tx.Load("Documents/protected.pdf", StreamType.AdobePDF);
    }
    catch (FilterException exception) when (exception.Reason == FilterException.FilterError.InvalidPassword)
    {
        // The PDF requires a user password: load it again with the password
        LoadSettings loadSettings = new LoadSettings()
        {
            UserPassword = "user1234"
        };

        tx.Load("Documents/protected.pdf", StreamType.AdobePDF, loadSettings);

        Console.WriteLine($"Permissions: {loadSettings.DocumentAccessPermissions}");
    }
    catch (FilterException exception) when (exception.Reason == FilterException.FilterError.Encrypted)
    {
        Console.WriteLine("The encryption scheme of this PDF is not supported.");
    }
}
```

Your application asks for the password and decides which operations it allows according to `DocumentAccessPermissions`; with a valid `MasterPassword`, the document has no restrictions. The PDF import supports RC4 encryption with 40 and 128 bits and AES encryption with 128 bits. For documents encrypted with 256-bit AES or with certificates, the reason is `Encrypted`.

### Load HTML

HTML is loaded from a string with `StringStreamType.HTMLFormat` or from a file with `StreamType.HTMLFormat`. CSS in a `style` element is applied, and TX Text Control creates paragraph styles from the HTML. After loading, the result is a regular document to which you can add headers, footers and page settings. The following program loads an HTML page and changes the font of its root style `BODY`, which the other styles inherit:

```csharp
using TXTextControl;

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

    string html = "<html><head><style>h1 { color: #1a4d80; }</style></head>" +
                  "<body><h1>Newsletter</h1><p>The newsletter of this month.</p></body></html>";

    tx.Load(html, StringStreamType.HTMLFormat);

    // Change the root style of the styles created from the HTML
    ParagraphStyle bodyStyle = tx.ParagraphStyles.GetItem("BODY");

    if (bodyStyle != null)
    {
        bodyStyle.FontName = "Times New Roman";
        bodyStyle.Apply();
    }

    tx.Save("newsletter.pdf", StreamType.AdobePDF);
}
```

The blog article [Convert HTML to PDF in ASP.NET Core C#](https://www.textcontrol.com/blog/2023/10/23/convert-html-to-pdf-in-aspnet-core-csharp/) converts complete HTML pages, including images, this way.

### Handle Errors

When a document can't be imported, `Load` throws a `FilterException`. Its `Reason` property names the cause, such as `WrongFileType`, `InvalidPassword` or `Encrypted`. The reasons and an example that handles them are listed in [FilterException](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/dotnet-api/exceptions/#filterexception).

The DOC format can't be loaded with the Core engine, and `AdobePDFA` and `CascadingStylesheet` are formats for saving only. [ServerTextControl.DocumentLoaded](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/servertextcontrol/documentloaded-event/llms-full.txt) occurs when a document has been loaded.

Linked images are a common problem when documents move between servers: an image that was inserted from a file stores its path, and when that file doesn't exist on the new server, a rectangle with the file name is shown instead of the image. The blog article [Check TX Text Control Template Dependencies Before Deployment](https://www.textcontrol.com/blog/2026/07/28/check-tx-text-control-template-dependencies-before-deployment/) finds such images and missing fonts before a template is used.

### Next Steps

- [Saving and Converting Documents](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/saving-converting/llms-full.txt): save loaded documents in another format.
- [Creating Documents](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/creating/llms-full.txt): assemble documents from several sources.
- [Fields](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/fields/llms-full.txt): work with the fields imported from Word documents.
- [Supported File Formats](https://docs.textcontrol.com/tx-text-control-dotnet-server/overview/file-formats/llms-full.txt): the formats you can load with each engine.

---

## Nearby

- **Previous:** [Creating Documents](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/creating/llms-full.txt)
- **Next:** [Saving and Converting Documents](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/saving-converting/llms-full.txt)