Cómo controlar el etiquetado UTF-8 ECI para códigos de barras 2D en C#

Ahmad Sohail
Ahmad Sohail
Actualizado: 9 de septiembre de 2026

Un código de barras 2D que salió de un tamaño diferente al esperado, un escáner heredado que rechaza un símbolo que solía leer, y un estándar que exige que cada símbolo declare su codificación todo se reducen a la misma pregunta: ¿el código de barras lleva un encabezado UTF-8 ECI (Interpretación de Canal Extendida)?

Ese encabezado le indica a un escáner que interprete la carga útil como UTF-8, lo cual es importante para contenido en chino, árabe, tailandés o cualquier otro idioma que no sea ASCII simple. No es gratuito. El encabezado consume palabras de código, tanto que una carga útil que ya está cerca de un límite de tamaño puede desbordarse en un símbolo más grande, y los escáneres construidos antes de que existiera ECI rechazan un símbolo que lo lleva. Por lo tanto, IronBarcode escribe el encabezado solo cuando los datos contienen caracteres no ASCII, y el ajuste EciMode anula esa decisión en cualquier dirección.

Por favor, tenga en cuenta: Requiere IronBarcode 2026.9.2 o posterior. La API no existe en 2026.8.6 o versiones anteriores, donde la llamada produce un error de compilación en lugar de una falla en tiempo de ejecución.
Inicio rápido: Establecer la política ECI para cada código de barras 2D

Asigna la política una vez, luego genera códigos de barras como lo harías normalmente. Todos los formatos 2D la siguen, sin argumentos adicionales.

  1. 1Instalar IronBarcode con NuGet Package Manager

    PM > Install-Package BarCode

  2. 2Copie y ejecute este fragmento de código.

    IronBarCode.BarcodeWriter.DefaultEciMode = IronBarCode.EciMode.ForceUtf8;
    IronBarCode.BarcodeWriter.CreateBarcode("BK005|8389|0001", IronBarCode.BarcodeEncoding.QRCode).SaveAsPng("part-qr.png");
  3. 3Despliegue para probar en su entorno real

    Empiece a usar IronBarcode en su proyecto hoy con una prueba gratuita
    arrow pointer


¿Cuándo IronBarcode agrega un encabezado ECI?

Nada sobre la llamada que ya escribes cambia. Genera un DataMatrix a partir de un número de parte ASCII y el símbolo no lleva encabezado; pasa el mismo método una carga útil con una diéresis en ella y aparece el encabezado, porque el valor lo necesita. Un argumento EciMode en la llamada anula ese juicio.

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");

Los tres símbolos anteriores difieren solo en la carga útil y en si se suministró un modo. Las imágenes a continuación están dibujadas a un tamaño de módulo fijo, por lo que los símbolos difieren en tamaño general como lo harían en una etiqueta impresa.

DataMatrix que codifica un número de pieza ASCII con EciMode.Auto, un símbolo de 16 por 16 módulos sin encabezado ECI

ASCII, Auto - 16 × 16 módulos, sin encabezado

DataMatrix que codifica un número de pieza que contiene una diéresis alemana con EciMode.Auto, un símbolo de 22 por 22 módulos con un encabezado ECI UTF-8

No ASCII, Auto - 22 × 22 módulos, encabezado añadido

DataMatrix que codifica el mismo número de pieza ASCII con EciMode.ForceUtf8, un símbolo de 16 por 16 módulos del mismo tamaño que el ASCII simple

ASCII, ForceUtf8 - 16 × 16 módulos, encabezado forzado


La carga útil ASCII se codifica en una cuadrícula de 16 × 16 ya sea que se fuerce o no un encabezado: este valor particular tiene suficiente capacidad sobrante que las palabras de código adicionales no cuestan nada. La carga útil no ASCII necesita una capa de tamaño completa más, 22 × 22, porque el encabezado y el contenido de varios bytes juntos ya no caben en 16 × 16. Un encabezado solo aumenta el símbolo cuando la carga útil ya está cerca de un límite de tamaño, y si eso es cierto para un valor dado no es visible desde la cadena en sí.

¿Cuáles son los tres modos ECI?

  • Auto: Escribe el encabezado ECI UTF-8 solo cuando los datos contienen caracteres no ASCII. Este es el predeterminado, y produce el símbolo más pequeño para una carga útil ASCII pura.
  • ForceUtf8: Siempre escribe el encabezado, incluso para ASCII puro. Úsalo para el cumplimiento estricto de estándares, o cuando cada símbolo debe declarar su codificación.
  • Off: Nunca escribe el encabezado. Úsalo solo cuando se sabe que los datos son ASCII o Latin-1 y el decodificador no entiende ECI.
Por favor, tenga en cuenta: ECI se aplica solo a formatos 2D. EciMode no tiene efecto en códigos de barras 1D como Code 128, EAN o UPC.

¿Cómo configuro el modo ECI?

¿Cómo aplico una política en toda la aplicación?

BarcodeWriter.DefaultEciMode es un campo estático público en BarcodeWriter, predeterminado a EciMode.Auto. Asígnalo una vez y cada código de barras 2D que genere la aplicación lo seguirá, sea cual sea el formato y cualquier parte de la base de código que lo haya producido. Refleja el campo BarcodeWriter.DefaultCharacterEncoding existente:

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);
}

¿Cómo anulo el modo para un solo DataMatrix?

Un EciMode por llamada en una sobrecarga CreateDataMatrix prevalece sobre BarcodeWriter.DefaultEciMode, y solo se aplica a esa llamada.

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");

Cada sobrecarga CreateDataMatrix que toma un EciMode sigue el mismo patrón. Los datos van primero, como un string, un byte[] o un Stream. El tamaño viene a continuación, ya sea como un tamaño de píxel único o como un DataMatrixWriter.DataMatrixShape con un ancho y altura explícitos. EciMode es siempre el parámetro final. El ejemplo anterior pasa un tamaño; la sobrecarga de forma toma el mismo EciMode en la misma posición final:

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");

¿Qué controla QR, Aztec y PDF417?

Estos tres formatos no tienen argumento EciMode. No existe tal parámetro en QRCodeWriter, y ninguno en las sobrecargas genéricas BarcodeWriter.CreateBarcode, así que BarcodeWriter.DefaultEciMode es la única forma de controlarlos.

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");

Donde un código QR y un DataMatrix necesitan un comportamiento ECI diferente en la misma ejecución, el DataMatrix toma el argumento por llamada y el código QR sigue el predeterminado estático.


¿Cómo se comporta la configuración en tiempo de ejecución?

¿Cuándo entra en vigor DefaultEciMode?

CreateBarcode, CreateDataMatrix y CreateQrCode devuelven un objeto cuyo modo aún no está fijo. DefaultEciMode se lee cuando el código de barras se guarda o se representa de otra manera, por lo que asignar un nuevo valor a mitad de ejecución afecta a cada código de barras guardado después de ese punto, incluidos los objetos creados antes del cambio.

Esto detecta la forma común por lotes: crea varios códigos de barras mientras cambia DefaultEciMode entre llamadas, luego guárdalos juntos al final. Todos ellos toman el modo que se estableció por última vez. Guarda cada código de barras antes de cambiar el modo para el siguiente, o pasa EciMode por llamada a CreateDataMatrix, a la cual el predeterminado estático no llega.

Advertencia: DefaultEciMode es un proceso global estático mutable y no es seguro para hilos. Una reasignación es visible para todos los hilos de inmediato, por lo que cambiarlo mientras otro hilo está generando o guardando significa que ese hilo observa el cambio a mitad de ejecución. Trátelo como una política de inicio de aplicación, exactamente como con BarcodeWriter.DefaultCharacterEncoding.

¿Cuándo lanza EciMode.Off una excepción?

Off es una promesa de que los datos son ASCII. Rompe esa promesa y la llamada lanza IronBarCodeEncodingException, bajo cualquier configuración BarcodeWriter.DefaultCharacterEncoding. El predeterminado UTF-8 ofrece el mensaje más útil:

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

Bajo ISO_8859_1 la misma combinación aparece como un error del codificador nativo de nivel inferior.

La carga útil a menudo no está completamente bajo el control de la aplicación: entrada de usuario, un suministro ascendente, un nombre de producto de un catálogo de proveedores. Una envoltura defensiva lo cubre:

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);
    }
}

El reemplazo aquí cambia ese símbolo a Auto, surgiendo de la opinión que un código de barras correcto que llegue a un escáner consciente de ECI supera a no tener ningún código de barras. La recuperación adecuada depende del despliegue: donde los escáneres genuinamente no pueden leer ECI, rechazar el registro para manejo manual es la opción más segura.

El tipo también se enumera en la guía de manejo de errores y depuración, que cubre la familia de excepciones sin esta causa específica.


¿Cómo elijo un modo?

¿Cómo etiqueto cada símbolo de nuevo?

Una línea, al inicio:

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 devuelve cada formato 2D a un comportamiento siempre etiquetado, produciendo una salida byte-idéntica a 2026.8.6 y anteriores para la misma entrada. Esta es la opción correcta para una aplicación cuyos sistemas posteriores fueron construidos contra la salida etiquetada, para un estándar que requiere una declaración de codificación explícita en cada símbolo, o simplemente como una forma de diferir el cambio mientras sus efectos son evaluados.

El caso inverso también vale la pena mencionar. Una aplicación que se actualizó, encontró que sus símbolos se hicieron más pequeños, y está feliz con eso no necesita ninguna acción: Auto ya es el predeterminado.

¿Qué modo se ajusta a qué situación?

Modo ECI recomendado por escenario, y dónde se configura cada uno

EscenarioModo ECIDónde configurarlo
Generación de propósito general, contenido mixtoAutoNada que hacer; es el predeterminado
Flota de escáneres antiguos que fallan en ECIOffDefaultEciMode al inicio
El estándar requiere codificación explícita en cada símboloForceUtf8DefaultEciMode al inicio
Un símbolo de cumplimiento entre salidas normalesForceUtf8Por llamada, solo DataMatrix
Contenidos de carga útil no garantizados como ASCIIAuto, o Off con una capturaCualquiera, con manejo de excepciones

¿A dónde ir a continuación?

El comportamiento descrito aquí es una configuración con tres valores, y la mayoría de las aplicaciones lo establecerán una vez y no lo revisarán. Las dos decisiones que vale la pena tomar deliberadamente son si la flota de escáneres entiende ECI, y si algún estándar descendente requiere una declaración en cada símbolo.

Para saber qué formatos de código de barras soportan contenido Unicode en primer lugar, consulta el cómo escribir códigos de barras UTF-8 y Unicode, que cubre el soporte Unicode a nivel de formato y enlaza aquí para el detalle ECI. Para generar los propios formatos 2D, el cómo crear códigos de barras 2D cubre la generación de DataMatrix, QR, Aztec y PDF417. La documentación completa de la clase está en la referencia API de IronBarcode.

Ahmad es un desarrollador full-stack con una sólida base en C#, Python y tecnologías web. Tiene un profundo interés en construir soluciones de software escalables y disfruta explorando cómo el diseño y la funcionalidad se encuentran en aplicaciones del mundo real.

Leer más

¿Listo para empezar?

Descargas de NuGet 2,564,559Versión:2026.11recién lanzado