Como controlar a marcação UTF-8 ECI para códigos de barras 2D em C#

Ahmad Sohail
Ahmad Sohail
Atualizado: 9 de setembro de 2026

Um código de barras 2D que saiu de um tamanho diferente do esperado, um scanner legado que rejeita um símbolo que costumava ler, e um padrão exigindo que cada símbolo declare sua codificação, tudo se resume à mesma questão: o código de barras possui um cabeçalho UTF-8 ECI (Interpretação de Canal Estendido)?

Esse cabeçalho informa ao scanner que deve interpretar o conteúdo como UTF-8, o que é importante para conteúdo em chinês, árabe, tailandês ou qualquer outro idioma fora do ASCII comum. Não é gratuito. O cabeçalho consome palavras de código, o suficiente para que um conteúdo já próximo do limite de tamanho possa transbordar para um símbolo maior, e scanners construídos antes da existência do ECI rejeitam um símbolo que o possua. Portanto, o IronBarcode escreve o cabeçalho apenas quando os dados contêm caracteres não-ASCII, e a configuração EciMode anula essa decisão em qualquer direção.

Por favor, note: Requer IronBarcode 2026.9.2 ou posterior. A API não existe em 2026.8.6 ou anterior, onde a chamada produz um erro de compilação em vez de uma falha em tempo de execução.
Início Rápido: Definir a Política ECI para Cada Código de Barras 2D

Atribua a política uma vez, depois gere códigos de barras como faria normalmente. Cada formato 2D a segue, sem argumentos adicionais.

  1. 1Instale o IronBarcode com NuGet Package Manager

    PM > Install-Package BarCode

  2. 2Copie e execute este trecho de código.

    IronBarCode.BarcodeWriter.DefaultEciMode = IronBarCode.EciMode.ForceUtf8;
    IronBarCode.BarcodeWriter.CreateBarcode("BK005|8389|0001", IronBarCode.BarcodeEncoding.QRCode).SaveAsPng("part-qr.png");
  3. 3Implante para testar em seu ambiente de produção.

    Comece a usar o IronBarcode em seu projeto hoje com uma avaliação gratuita
    arrow pointer


Quando o IronBarcode adiciona um cabeçalho ECI?

Nada sobre a chamada que você já escreve muda. Gere um DataMatrix de um número de peça em ASCII e o símbolo não carregará um cabeçalho; passe o mesmo método com um conteúdo com trema e o cabeçalho aparece, porque o valor precisa dele. Um argumento EciMode na chamada anula esse julgamento.

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

Os três símbolos acima diferem apenas no conteúdo e em se um modo foi fornecido. As imagens abaixo são desenhadas em um tamanho de módulo fixo, então os símbolos diferem em tamanho geral da forma como seriam em uma etiqueta impressa.

DataMatrix codificando um número de peça ASCII com EciMode.Auto, um símbolo de 16 por 16 módulos sem cabeçalho ECI

ASCII, Auto - 16 × 16 módulos, sem cabeçalho

DataMatrix codificando um número de peça com um trema alemão com EciMode.Auto, um símbolo de 22 por 22 módulos com cabeçalho ECI UTF-8

Não-ASCII, Auto - 22 × 22 módulos, cabeçalho adicionado

DataMatrix codificando o mesmo número de peça ASCII com EciMode.ForceUtf8, um símbolo de 16 por 16 módulos do mesmo tamanho que o ASCII simples

ASCII, ForceUtf8 - 16 × 16 módulos, cabeçalho forçado


O conteúdo ASCII codifica para uma grade de 16 × 16 seja ou não forçado a ter um cabeçalho: este valor específico tem capacidade extra suficiente para que as palavras de código adicionais não custem nada. O conteúdo não-ASCII precisa de um nível de tamanho completo a mais, 22 × 22, porque o cabeçalho e o conteúdo multibyte juntos não cabem mais em 16 × 16. Um cabeçalho só aumenta o símbolo quando o conteúdo já está próximo de um limite de tamanho, e se isso é verdade para um dado valor não é visível a partir da string em si.

Quais são os três modos ECI?

  • Auto: Escreve o cabeçalho UTF-8 ECI apenas quando os dados contêm caracteres não-ASCII. Este é o padrão, e produz o símbolo menor para um conteúdo ASCII puro.
  • ForceUtf8: Sempre escreve o cabeçalho, incluindo para ASCII puro. Use-o para conformidade estrita com padrões, ou onde cada símbolo deve declarar sua codificação.
  • Off: Nunca escreve o cabeçalho. Use-o somente onde os dados são conhecidos por serem ASCII ou Latin-1 e o decodificador não entende ECI.
Por favor, note: ECI aplica-se apenas a formatos 2D. EciMode não tem efeito em códigos de barras 1D, como Code 128, EAN ou UPC.

Como defino o modo ECI?

Como aplico uma política em toda a aplicação?

BarcodeWriter.DefaultEciMode é um campo estático público em BarcodeWriter, padrão para EciMode.Auto. Atribua uma vez, e cada código de barras 2D gerado pela aplicação o seguirá, não importando o formato e a parte do código que o produziu. Ele espelha o campo existente 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);
}

Como sobrescrevo o modo para um único DataMatrix?

Um EciMode por chamada em uma sobrecarga CreateDataMatrix supera BarcodeWriter.DefaultEciMode, e aplica-se apenas a essa chamada.

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

Toda sobrecarga CreateDataMatrix que aceita um EciMode segue o mesmo padrão. Os dados entram primeiro, como um string, uma byte[] ou uma Stream. A definição de tamanho vem em seguida, seja como um tamanho de pixel único ou como um DataMatrixWriter.DataMatrixShape com largura e altura explícitas. EciMode é sempre o parâmetro final. O exemplo acima passa um tamanho; a sobrecarga de forma aceita o mesmo EciMode na mesma posição 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");

O que controla QR, Aztec e PDF417?

Esses três formatos não têm nenhum argumento EciMode. Não há tal parâmetro em QRCodeWriter, e nenhum nas sobrecargas genéricas BarcodeWriter.CreateBarcode, então BarcodeWriter.DefaultEciMode é a única maneira de controlá-los.

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

Quando um código QR e um DataMatrix precisam de um comportamento ECI diferente na mesma execução, o DataMatrix aceita o argumento por chamada e o código QR segue o padrão estático.


Como a configuração se comporta em tempo de execução?

Quando o DefaultEciMode entra em vigor?

CreateBarcode, CreateDataMatrix e CreateQrCode retornam um objeto cujo modo ainda não está fixado. DefaultEciMode é lido quando o código de barras é salvo ou renderizado de outra forma, então atribuir um novo valor no meio da execução afeta todo código de barras salvo após esse ponto, inclusive objetos criados antes da mudança.

Isso pega de surpresa o formato comum de lote: criar vários códigos de barras enquanto altera DefaultEciMode entre as chamadas, depois salvá-los juntos no final. Todos eles adotam o modo que foi definido por último. Salve cada código de barras antes de alterar o modo para o próximo, ou passe EciMode por chamada a CreateDataMatrix, que o padrão estático não atinge.

Aviso: DefaultEciMode é um processo global estático mutável e não é seguro para threads. Uma reatribuição é visível para todos os threads imediatamente, então alterá-la enquanto outro thread está gerando ou salvando significa que esse thread observa a mudança no meio da execução. Trate-o como política de inicialização de aplicativo, exatamente como BarcodeWriter.DefaultCharacterEncoding.

Quando EciMode.Off lança uma exceção?

Off é uma promessa de que os dados são ASCII. Quebre essa promessa e a chamada lança IronBarCodeEncodingException, sob qualquer configuração BarcodeWriter.DefaultCharacterEncoding. O padrão UTF-8 dá a mensagem mais ú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

Sob ISO_8859_1 a mesma combinação aparece como um erro de codificador nativo de nível mais baixo.

O conteúdo muitas vezes não está totalmente sob o controle da aplicação: entrada do usuário, um feed a montante, um nome de produto de um catálogo de fornecedores. Um wrapper defensivo o cobre:

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

O fallback aqui alterna esse símbolo para Auto, na visão de que um código de barras correto atingindo um scanner ciente de ECI é melhor do que nenhum código de barras. A recuperação correta depende da implementação: onde os scanners genuinamente não conseguem ler ECI, rejeitar o registro para tratamento manual é a escolha mais segura.

O tipo também está listado no guia de tratamento de erros e depuração, que cobre a família de exceções sem esta causa específica.


Como escolho um modo?

Como etiqueto cada símbolo novamente?

Uma linha, na inicialização:

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 retorna todo formato 2D ao comportamento sempre etiquetado, produzindo saída byte-idêntica à de 2026.8.6 e anteriores para o mesmo entrada. Esta é a escolha certa para uma aplicação cujos sistemas a jusante foram construídos contra a saída etiquetada, para um padrão que exige uma declaração de codificação explícita em cada símbolo, ou simplesmente como uma forma de adiar a mudança enquanto seus efeitos são avaliados.

O caso inverso também merece ser mencionado. Uma aplicação que foi atualizada, verificou que seus símbolos ficaram menores, e está contente com isso, não precisa de ação alguma: Auto já é o padrão.

Qual modo se encaixa em cada situação?

Modo ECI recomendado por cenário, e onde cada um é configurado

CenárioModo ECIOnde Configurar
Geração de uso geral, conteúdo mistoAutoNada a fazer; é o padrão
Frota de scanners antigos que falham no ECIOffDefaultEciMode na inicialização
Padrão exige codificação explícita em cada símboloForceUtf8DefaultEciMode na inicialização
Um símbolo de conformidade entre saídas normaisForceUtf8Por chamada, apenas DataMatrix
Conteúdo do payload não garantido como ASCIIAuto, ou Off com exceçãoQualquer um, com tratamento de exceção

Para onde ir agora

O comportamento descrito aqui é uma configuração com três valores, e a maioria das aplicações definirá uma vez e nunca mais revisitará. As duas decisões que valem a pena tomar deliberadamente são se a frota de scanners entende ECI, e se algum padrão a jusante exige uma declaração em cada símbolo.

Para saber quais formatos de código de barras suportam conteúdo Unicode em primeiro lugar, veja o como escrever códigos de barras UTF-8 e Unicode, que cobre o suporte a Unicode a nível de formato e vincula aqui para o detalhe do ECI. Para gerar os próprios formatos 2D, o como criar códigos de barras 2D cobre a geração de DataMatrix, QR, Aztec e PDF417. A documentação completa da classe está na referência de API do IronBarcode.

Ahmad é um desenvolvedor full-stack com uma sólida base em C#, Python e tecnologias web. Ele tem um grande interesse em construir soluções de software escaláveis e gosta de explorar como design e funcionalidade se encontram em aplicações do mundo real.

Leia Mais

Pronto para começar?

Downloads no NuGet 2,564,559Versão:2026.11recém-lançado