如何在C#中控制2D条码的UTF-8 ECI标记

Ahmad Sohail
Ahmad Sohail
更新: 2026年9月9日

一个2D条码的大小与预期不同,一个拒绝曾经可以读取的符号的旧扫描仪,以及每个符号都需要声明其编码的标准,归结为同一个问题:条码是否携带UTF-8 ECI(扩展通道解释)头?

该头告诉扫描仪将负载解释为UTF-8,这对于中文、阿拉伯文、泰文或任何其他非纯ASCII内容都很重要。 这不是免费的。 头会消耗代码字,以至于本已接近尺寸边界的负载可能溢出到更大的符号中,并且在ECI出现之前建造的扫描仪会拒绝携带一个的符号。 因此,IronBarcode仅当数据包含非ASCII字符时才写入头,而EciMode设置可在任何方向覆盖该决策。

请注意: 需要IronBarcode 2026.9.2或更高版本。 API在2026.8.6或更早版本中不存在,在这些版本中调用将产生编译错误而不是运行时错误。
快速入门:为每个2D条码设置ECI策略

只需分配一次策略,然后像平常一样生成条码。 每种2D格式都遵循它,无需进一步参数。

  1. 1使用 IronBarcode 安装 NuGet Package Manager

    PM > Install-Package BarCode

  2. 2复制并运行这段代码。

    IronBarCode.BarcodeWriter.DefaultEciMode = IronBarCode.EciMode.ForceUtf8;
    IronBarCode.BarcodeWriter.CreateBarcode("BK005|8389|0001", IronBarCode.BarcodeEncoding.QRCode).SaveAsPng("part-qr.png");
  3. 3部署到您的生产环境中进行测试

    今天就用免费试用在您的项目中开始使用IronBarcode
    arrow pointer


IronBarcode何时添加ECI头?

您已经写的调用内容没有改变。 从ASCII零件号生成DataMatrix,符号不携带头; 将相同的方法交给含有分音符的负载,头就会出现,因为该值需要它。 调用时的EciMode参数会覆盖该判断。

using IronBarCode;

// Pure ASCII: no ECI header, smallest symbol
var ascii = DataMatrixWriter.CreateDataMatrix("BK005|8389|0001");
ascii.SaveAsPng("part-ascii.png");

// Non-ASCII: header written automatically
var unicode = DataMatrixWriter.CreateDataMatrix("BK005|8389|Bauteil-Größe");
unicode.SaveAsPng("part-unicode.png");

// Same ASCII value, header forced on
var tagged = DataMatrixWriter.CreateDataMatrix("BK005|8389|0001", 500, EciMode.ForceUtf8);
tagged.SaveAsPng("part-tagged.png");

上面的三个符号之间的差异仅在于负载以及是否提供了一个模式。 下面的图像以固定的模块大小绘制,因此符号在整体大小上与印刷标签相同。

在 EciMode.Auto 下编码 ASCII 零件编号的 DataMatrix,16×16 模块的符号,不带 ECI 头

ASCII,Auto - 16 × 16模块,无头

在 EciMode.Auto 下编码包含德语变音字母的零件编号的 DataMatrix,22×22 模块的符号,带有 UTF-8 ECI 头

非ASCII,Auto - 22 × 22模块,添加了头

在 EciMode.ForceUtf8 下编码同一 ASCII 零件编号的 DataMatrix,16×16 模块的符号,与纯 ASCII 版本尺寸相同

ASCII,ForceUtf8 - 16 × 16模块,强制头


无论是否在其上强加了头,ASCII负载都编码为16 × 16格:这个特定的值有足够的备用容量,以至于额外的代码字不需要花费任何代价。 非ASCII负载需要一个完整的更大尺寸等级,22 × 22,因为头和多字节内容一起不再适合16 × 16。当负载已经接近尺寸边界时,头只会增长符号,而且对于给定的值来说这是否成立并不是从字符串本身可以看出的。

三种ECI模式是哪些?

  • Auto:仅当数据包含非ASCII字符时才写UTF-8 ECI头。 这是默认值,并且对于纯ASCII负载生成最小的符号。
  • ForceUtf8:总是写头,包括纯ASCII。 将其用于严格的标准合规性,或者在每个符号都必须声明其编码的情况下。
  • Off:从不写头。 仅在数据已知为ASCII或Latin-1并且解码器不理解ECI的情况下使用它。
请注意: ECI仅适用于2D格式。 EciMode对Code 128,EAN或UPC等1D条码没有影响。

如何设置ECI模式?

如何在整个应用程序中应用一个策略?

BarcodeWriter.DefaultEciMode 是 BarcodeWriter 上的一个公共静态字段,默认值为 EciMode.Auto。 只需赋值一次,应用程序生成的每个2D条码都将遵循它,无论是哪个格式以及代码库的哪个部分生成了它。 它反映了现有的BarcodeWriter.DefaultCharacterEncoding字段:

using IronBarCode;

// Set once at startup
BarcodeWriter.DefaultEciMode = EciMode.Off;

// No mode argument passed anywhere below
GeneratedBarcode label = CreatePartLabel("BK005|8389|0001");
label.SaveAsPng("part-label.png");

GeneratedBarcode ticket = BarcodeWriter.CreateBarcode("TKT-77120", BarcodeEncoding.Aztec);
ticket.SaveAsPng("gate-ticket.png");

static GeneratedBarcode CreatePartLabel(string partNumber)
{
    // Follows DefaultEciMode
    return DataMatrixWriter.CreateDataMatrix(partNumber, 300);
}

如何为单个DataMatrix覆盖模式?

每次调用 EciMode 时的 CreateDataMatrix 重载胜过 BarcodeWriter.DefaultEciMode,并仅适用于该调用。

using IronBarCode;

// Application-wide policy
BarcodeWriter.DefaultEciMode = EciMode.Auto;

// Per-call override wins
var compliance = DataMatrixWriter.CreateDataMatrix("LOT-4471-A", 200, EciMode.ForceUtf8);
compliance.SaveAsPng("compliance-label.png");

// No override; follows DefaultEciMode
var standard = DataMatrixWriter.CreateDataMatrix("LOT-4471-B", 200);
standard.SaveAsPng("standard-label.png");

每个接收 EciMode 的 CreateDataMatrix 重载都遵循相同的模式。 数据首先以 string 、 byte[] 或 Stream 的形式进入。 接下来是尺寸,或者作为单个像素大小,或者作为一个明确的宽度和高度的DataMatrixWriter.DataMatrixShape。 EciMode始终是最后一个参数。 上面的示例传递了尺寸;形状重载在相同的最终位置取相同的EciMode:

using IronBarCode;

// Rectangular symbol, ECI forced on
var wide = DataMatrixWriter.CreateDataMatrix(
    "BK005|8389|0001",
    DataMatrixWriter.DataMatrixShape.Rectangular,
    400,
    100,
    EciMode.ForceUtf8);

wide.SaveAsPng("part-wide.png");

什么控制QR、Aztec和PDF417?

这三种格式没有EciMode参数。 在 QRCodeWriter 上没有这样的参数,并且在通用的 BarcodeWriter.CreateBarcode 重载上也没有,所以 BarcodeWriter.DefaultEciMode 是控制它们的唯一方式。

using IronBarCode;

// QR, Aztec, PDF417: no per-call EciMode
BarcodeWriter.DefaultEciMode = EciMode.ForceUtf8;

var qr = BarcodeWriter.CreateBarcode("ORDER-88213", BarcodeEncoding.QRCode);
qr.SaveAsPng("order-qr.png");

var aztec = BarcodeWriter.CreateBarcode("ORDER-88213", BarcodeEncoding.Aztec);
aztec.SaveAsPng("order-aztec.png");

// New value applies to later calls
BarcodeWriter.DefaultEciMode = EciMode.Auto;

var qrAuto = BarcodeWriter.CreateBarcode("ORDER-88214", BarcodeEncoding.QRCode);
qrAuto.SaveAsPng("order-qr-auto.png");

在同一次运行中需要不同ECI行为的QR码和DataMatrix中,DataMatrix采用每次调用参数而QR码遵循静态默认值。


设置在运行时如何表现?

默认EciMode何时生效?

CreateBarcode、 CreateDataMatrix 和 CreateQrCode 返回一个模式尚未固定的对象。 在条码被保存或以其他方式呈现时读取DefaultEciMode,因此在运行过程中分配新值会影响每个在此之后保存的条码,包括在更改之前创建的对象。

这会导致常见的批处理形态问题:在调用之间更改DefaultEciMode,然后一起保存它们。 所有这些都采用最后设置的模式。在改变下一个条码的模式之前保存每个条码,或者每次调用 CreateDataMatrix 时传递 EciMode,这是静态默认值无法到达的。

警告: DefaultEciMode 是一个可变的全局静态变量,并且不是线程安全的。 重新分配会立即对每个线程可见,因此当另一个线程正在生成或保存时更改它意味着该线程会在运行中观察到变化。 将其视为应用程序启动策略,正如使用BarcodeWriter.DefaultCharacterEncoding的情况一样。

何时因EciMode.Off抛出异常?

Off是对数据为ASCII的承诺。 如果违反这个承诺,调用将在任意 BarcodeWriter.DefaultCharacterEncoding 设置下抛出 IronBarCodeEncodingException。 UTF-8默认值提供了更有用的信息:

IronBarCode Encoding Error for Barcode Format DataMatrix : EciMode.Off cannot be used with non-ASCII data while BarcodeWriter.DefaultCharacterEncoding is UTF-8, because the UTF-8 bytes require the ECI header to be decoded correctly and would otherwise be read as ISO-8859-1. Use EciMode.Auto or EciMode.ForceUtf8, or set BarcodeWriter.DefaultCharacterEncoding to a matching single-byte encoding.
Text

在ISO_8859_1下,同样的组合表现为低级别的本地编码器错误。

负载通常不完全在应用程序的控制之下:用户输入、上游供源、供应商目录中的产品名称。 一个防御性包装器覆盖了它:

using IronBarCode;
using IronBarCode.Exceptions;
using System;

public class LabelGenerator
{
    // Payload not guaranteed ASCII
    public bool TryCreateLabel(string payload, string outputPath)
    {
        try
        {
            var barcode = DataMatrixWriter.CreateDataMatrix(payload, 200, EciMode.Off);
            barcode.SaveAsPng(outputPath);
            return true;
        }
        catch (IronBarCodeEncodingException ex)
        {
            // Non-ASCII cannot round-trip without ECI
            Console.WriteLine("Payload is not ASCII, cannot generate with ECI disabled: {0}", ex.Message);
            return false;
        }
    }

    // Fall back to Auto
    public void CreateLabelWithFallback(string payload, string outputPath)
    {
        if (TryCreateLabel(payload, outputPath))
        {
            return;
        }

        var barcode = DataMatrixWriter.CreateDataMatrix(payload, 200, EciMode.Auto);
        barcode.SaveAsPng(outputPath);
    }
}

此处的回退将符号切换为Auto,认为到达ECI感知扫描仪的正确条码比没有条码要好。 正确的恢复取决于部署:当扫描仪确实无法读取ECI时,拒绝记录进行手动处理是更安全的选择。

该类型也列在错误处理和调试指南中,该指南涵盖了没有这个具体原因的异常家族。


如何选择一种模式?

如何再次标记每个符号?

在启动时,一行代码:

using IronBarCode;

// Restore pre-2026.9.2 always-tagged output
BarcodeWriter.DefaultEciMode = EciMode.ForceUtf8;

// Both symbols carry the header
var dataMatrix = DataMatrixWriter.CreateDataMatrix("SKU-10045", 200);
dataMatrix.SaveAsPng("sku-datamatrix.png");

var qr = BarcodeWriter.CreateBarcode("SKU-10045", BarcodeEncoding.QRCode);
qr.SaveAsPng("sku-qr.png");

ForceUtf8将每种2D格式恢复为始终标记的行为,为相同输入生成与2026.8.6及更早版本完全相同的输出。 这是一个应用设计为输出标记结果的正确选择,用于一个要求在每个符号上声明显式编码的标准,或只是为了延迟变更同时评估其影响的方式。

反相情况也值得命名。 升级后发现其符号变小并对此感到满意的应用程序不需要执行任何操作:Auto已经是默认值。

哪种模式适应哪种情况?

按场景推荐的ECI模式,以及每种模式的配置位置

情景ECI模式配置位置
通用生成,混合内容Auto无需操作; 这是默认的
无法读取ECI的旧款扫描仪Off启动时的DefaultEciMode
标准要求在每个符号上显式编码ForceUtf8启动时的DefaultEciMode
普通输出中要求的合规符号ForceUtf8每次调用,仅限于DataMatrix
负载内容不能保证为ASCIIAuto,或携带捕获的 Off任选,其附带异常处理

接下来去哪里

这里描述的行为是一个有三个值的设置,大多数应用程序会设置一次然后不再重新访问它。 值得有意做出的两个决定是扫描仪队列是否理解ECI,以及是否有任何下游标准要求每个符号都声明。

有关哪些条码格式首先支持Unicode内容的信息,请参阅编写UTF-8和Unicode条码的做法,这涵盖了格式级的Unicode支持,并在此链接了ECI的详细内容。 有关生成2D格式本身的详细信息,创建2D条码的做法涵盖了DataMatrix、QR、Aztec和PDF417生成。 完整的类文档在IronBarcode API参考中。

Ahmad 是一名全栈开发人员,拥有扎实的 C#、Python 和 Web 技术基础。他对构建可扩展的软件解决方案深感兴趣,并喜欢探索设计和功能在实际应用中如何结合。

阅读更多

准备开始了吗?

NuGet 下载量 2,564,559版本:2026.11刚刚发布