# Barcodes

> Merge data into barcodes: named barcode placeholders, QR codes and 1D and 2D types, TXBarcodeCore, UpperTextLength, BarcodeMerged and value validation.

- **Product:** TX Text Control .NET Server
- **Section:** Documentation
- **Kind:** Topic
- **Path:** TX Text Control .NET Server > Mail Merge and Reporting > Barcodes
- **2587 words**
- **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/barcodes/
- **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/barcodes/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/barcodes/llms-full.txt

---

A QR code with a payment link or a barcode with a serial number changes with every document, so it's merged from the data like a field. The template contains a barcode with a name, its type, size and position; the data supplies only the value to encode. Barcode placeholders are created in code or in the Document Editor, and values can be checked before they reach a barcode.

Barcodes that your code creates and changes without a merge are covered in [Charts and Barcodes](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/charts-barcodes/llms-full.txt) of Document Processing. The JavaScript API for barcodes in the editor is described in [Charts and Barcodes](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-editor/charts-barcodes/llms-full.txt), and image placeholders, which work the same way, in [Images](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/images/llms-full.txt). The examples encode the invoice number of the invoice data from [Simple Mail Merge](https://docs.textcontrol.com/tx-text-control-dotnet-server/getting-started/mail-merge/simple/llms-full.txt).

### How Barcode Placeholders Work

A barcode in a document is a [BarcodeFrame](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-datavisualization/barcodeframe/llms-full.txt). `MailMerge` processes barcodes like merge fields: when the name of a barcode frame is the name of a field in the data, the value is merged into the barcode.

- **The template defines the look.** The barcode type, size, alignment and position stay as designed; only the encoded text changes.
- **Barcodes in merge blocks** are merged for each record, for example a serial number in each row of an order.
- **Templates are saved in the TX Text Control format or as RTF.** Only these formats save barcodes as barcodes; other formats save an image of the barcode.
- **[BarcodeMerged](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver/mailmerge/barcodemerged-event/llms-full.txt)** occurs after a barcode has been merged.

### Barcode Types

[BarcodeType](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-barcode/barcodetype/enumeration/llms-full.txt) has 14 one-dimensional and 6 two-dimensional types:

| Kind | Types |
|---|---|
| One-dimensional | `Code128`, `Code39`, `Code93`, `Code11`, `Codabar`, `Interleaved2of5`, `EAN13`, `EAN8`, `UPCA`, `IntelligentMail`, `Postnet`, `PLANET`, `RoyalMail`, `FourState` |
| Two-dimensional | `QRCode`, `Datamatrix`, `PDF417`, `MicroPDF`, `AztecCode`, `Maxicode` |

The enumeration lists the characters and lengths that each type accepts: `EAN13` encodes 13 digits, for example, and `QRCode` up to 1270 ASCII characters.

### Create a Template With a QR Code Placeholder

The Core engine creates barcodes with the [TXBarcodeCore](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-barcode/txbarcodecore/llms-full.txt) class. The following program inserts a QR code named `InvoiceNumber` and saves the template:

```csharp
using System.Drawing;
using TXTextControl;
using TXTextControl.Barcode;
using TXTextControl.DataVisualization;

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

    tx.Selection = new Selection { Text = "Scan to view the invoice:\r\n" };

    TXBarcodeCore qrCode = new TXBarcodeCore();
    qrCode.Create();

    qrCode.BarcodeType = BarcodeType.QRCode;

    // The size of the code is calculated for 12 characters
    qrCode.UpperTextLength = 12;
    qrCode.Text = "INV-0000-000";

    // The name connects the barcode with the data
    BarcodeFrame barcodeFrame = new BarcodeFrame(qrCode)
    {
        Name = "InvoiceNumber",
        Size = new Size(1440, 1440) // 1 inch in twips
    };

    tx.Barcodes.Add(barcodeFrame, -1);

    tx.Save("barcode-template.tx", StreamType.InternalUnicodeFormat);
}
```

The code works as follows:

- [Create](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-barcode/txbarcodecore/create-method/llms-full.txt) initializes the `TXBarcodeCore` before it's used.
- [BarcodeType](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-barcode/txbarcodecore/barcodetype-property/llms-full.txt) selects the type, and [Text](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-barcode/txbarcodecore/text-property/llms-full.txt) is the value the placeholder shows until it's merged.
- The [BarcodeFrame constructor](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-datavisualization/barcodeframe/constructor/llms-full.txt) wraps the barcode. Its `Name` is matched with the data, and its `Size` in twips is the space the barcode takes in the document.
- [ServerTextControl.Barcodes](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/servertextcontrol/barcodes-property/llms-full.txt) returns the [BarcodeCollection](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-datavisualization/barcodecollection/llms-full.txt), whose `Add` method inserts the barcode inline at the input position. Other overloads anchor it to a paragraph or place it at a fixed position, as for images.

[UpperTextLength](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-barcode/txbarcodecore/uppertextlength-property/llms-full.txt) matters for merged barcodes. A barcode must not push other text away, so its frame keeps its size and the code inside adapts: with the maximum number of characters, the code fills the frame, and a shorter text gives a smaller code. Set `UpperTextLength` to the longest value your data contains, and set it before `Text`.

### Merge the Data

Merge the template with the invoice data. The value of `InvoiceNumber` is encoded in the QR code:

```csharp
using TXTextControl;
using TXTextControl.DocumentServer;

using (ServerTextControl tx = new ServerTextControl())
{
    tx.Create();
    tx.Load("barcode-template.tx", StreamType.InternalUnicodeFormat);

    using (MailMerge mailMerge = new MailMerge { TextComponent = tx })
    {
        mailMerge.BarcodeMerged += (sender, e) =>
            Console.WriteLine($"Barcode merged: {e.BarcodeFrame.Name}, block: {e.MergeBlockName}");

        mailMerge.MergeJsonData(File.ReadAllText("data.json"));
    }

    tx.Save("invoice-with-qr-code.pdf", StreamType.AdobePDF);
}
```

[BarcodeMergedEventArgs](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver/mailmerge-barcodemergedeventargs/llms-full.txt) contains the merged [BarcodeFrame](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver/mailmerge-barcodemergedeventargs/barcodeframe-property/llms-full.txt) and, inherited from [FrameMergedEventArgs](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver/mailmerge-framemergedeventargs/llms-full.txt), the data record and the merge block of the barcode. The online demo [Merging barcodes](https://demos.textcontrol.com/demos/server-side-mail-merge/reporting-structures/barcodes) merges serial numbers into barcodes of a repeating block.

### Check Values Before Merging

Because each barcode type accepts only certain characters and lengths, a value from the data can be invalid for a barcode. Static methods of `TXBarcodeCore` check a value before it's merged:

```csharp
using TXTextControl.Barcode;

string invoiceNumber = "INV-2025-001";

if (!TXBarcodeCore.IsTextValid(BarcodeType.QRCode, invoiceNumber, out string errorMessage))
{
    Console.WriteLine($"Invalid value: {errorMessage}");
}

Console.WriteLine($"EAN13 accepts {TXBarcodeCore.GetMinimumTextLength(BarcodeType.EAN13)} to {TXBarcodeCore.GetMaximumTextLength(BarcodeType.EAN13)} characters");
```

[IsTextValid](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-barcode/txbarcodecore/istextvalid-method/llms-full.txt) returns `false` and an error message for an invalid value. [GetMinimumTextLength](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-barcode/txbarcodecore/getminimumtextlength-method/llms-full.txt) and [GetMaximumTextLength](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-barcode/txbarcodecore/getmaximumtextlength-method/llms-full.txt) return the lengths a type accepts.

### Barcode Placeholders in the Document Editor

In the Document Editor, your JavaScript code inserts barcodes with `TXTextControl.barcodes.addInline` and names them with `setName`:

```javascript
TXTextControl.barcodes.addInline(function (barcodeFrame) {
    // The name connects the barcode with the data
    barcodeFrame.setName("InvoiceNumber");
}, function (error) {
    console.log(error.msg);
}, TXTextControl.BarcodeType.QRCode, "INV-0000-000", -1);
```

Save the template in the TX Text Control format and merge it on the server as above. [Charts and Barcodes](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-editor/charts-barcodes/#barcodes) in the Document Editor section describes the other barcode settings.

### Next Steps

- [Images](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/images/llms-full.txt): merge image data into named placeholders.
- [Merge Blocks](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/blocks/llms-full.txt): repeat barcodes for each record.
- [Template Design](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/template-design/llms-full.txt): choose the format your templates are stored in.

---

## Nearby

- **Previous:** [Images](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/images/llms-full.txt)
- **Next:** [Conditional Content](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/conditional-content/llms-full.txt)