Comment contrôler le balisage UTF-8 ECI pour les codes-barres 2D en C#

Ahmad Sohail
Ahmad Sohail
Mis à jour : 9 septembre 2026

Un code-barres 2D qui sort à une taille différente de celle attendue, un scanner ancien qui refuse un symbole qu'il lisait auparavant, et une norme exigeant que chaque symbole déclare son encodage se résument à la même question : le code-barres contient-il un en-tête UTF-8 ECI (Extended Channel Interpretation) ?

Cet en-tête indique à un scanner d'interpréter la charge utile comme UTF-8, ce qui est important pour le chinois, l'arabe, le thaï ou tout autre contenu en dehors de l'ASCII simple. Ce n'est pas gratuit. L'en-tête consomme des mots de code, suffisamment pour qu'une charge utile déjà proche d'une limite de taille puisse déborder dans un plus grand symbole, et les scanners construits avant l'existence de l'ECI rejettent un symbole qui en contient un. IronBarcode écrit donc l'en-tête uniquement lorsque les données contiennent des caractères non ASCII, et le paramètre EciMode remplace cette décision dans les deux sens.

Veuillez noter: Nécessite IronBarcode 2026.9.2 ou une version ultérieure. L'API n'existe pas dans 2026.8.6 ou une version antérieure, où l'appel produit une erreur de compilation plutôt qu'un échec à l'exécution.
Démarrage rapide : Définir la politique ECI pour chaque code-barres 2D

Attribuez la politique une fois, puis générez des codes-barres comme vous le feriez normalement. Chaque format 2D la suit, sans autre argument.

  1. 1Installez IronBarcode avec NuGet Package Manager

    PM > Install-Package BarCode

  2. 2Copiez et exécutez cet extrait de code.

    IronBarCode.BarcodeWriter.DefaultEciMode = IronBarCode.EciMode.ForceUtf8;
    IronBarCode.BarcodeWriter.CreateBarcode("BK005|8389|0001", IronBarCode.BarcodeEncoding.QRCode).SaveAsPng("part-qr.png");
  3. 3Déployez pour tester sur votre environnement de production.

    Commencez à utiliser IronBarcode dans votre projet dès aujourd'hui avec un essai gratuit
    arrow pointer


Quand IronBarcode ajoute-t-il un en-tête ECI ?

Rien ne change dans l'appel que vous écrivez déjà. Générez un DataMatrix à partir d'un numéro de pièce ASCII et le symbole ne porte pas d'en-tête ; remettez la même méthode une charge avec un umlaut et l'en-tête apparaît, car la valeur en a besoin. Un argument EciMode sur l'appel remplace ce jugement.

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

Les trois symboles ci-dessus ne diffèrent que par leur charge utile et par le fait qu'un mode ait été fourni. Les images ci-dessous sont dessinées à une taille de module fixe, de sorte que les symboles diffèrent en taille globale comme ils le seraient sur une étiquette imprimée.

DataMatrix encodant une référence de pièce ASCII avec EciMode.Auto, un symbole de 16 × 16 modules sans en-tête ECI

ASCII, Auto - 16 × 16 modules, pas d'en-tête

DataMatrix encodant une référence de pièce contenant un tréma allemand avec EciMode.Auto, un symbole de 22 × 22 modules portant un en-tête ECI UTF-8

Non-ASCII, Auto - 22 × 22 modules, en-tête ajouté

DataMatrix encodant la même référence de pièce ASCII avec EciMode.ForceUtf8, un symbole de 16 × 16 modules de même taille que le symbole ASCII simple

ASCII, ForceUtf8 - 16 × 16 modules, en-tête forcé


La charge ASCII se code en une grille 16 × 16 que l'en-tête soit forcé ou non : cette valeur particulière a suffisamment de capacité restante pour que les mots de code supplémentaires ne coûtent rien. La charge non-ASCII a besoin d'un niveau de taille complet de plus, 22 × 22, car l'en-tête et le contenu multi-octets ne tiennent plus ensemble en 16 × 16. Un en-tête ne fait croître le symbole que lorsque la charge est déjà proche d'une limite de taille, et si c'est le cas pour une valeur donnée n'est pas visible à partir de la chaîne elle-même.

Quels sont les trois modes ECI ?

  • Auto: Écrit l'en-tête UTF-8 ECI uniquement lorsque les données contiennent des caractères non-ASCII. C'est le mode par défaut, et il produit le plus petit symbole pour une charge en ASCII pur.
  • ForceUtf8: Écrit toujours l'en-tête, y compris pour l'ASCII pur. Utilisez-le pour un respect strict des normes, ou lorsque chaque symbole doit déclarer son encodage.
  • Off: N'écrit jamais l'en-tête. Utilisez-le uniquement lorsque les données sont connues pour être en ASCII ou Latin-1 et que le décodeur ne comprend pas l'ECI.
Veuillez noter: ECI s'applique uniquement aux formats 2D. EciMode n'a aucun effet sur les codes-barres 1D tels que Code 128, EAN ou UPC.

Comment définir le mode ECI ?

Comment appliquer une politique dans toute l'application ?

BarcodeWriter.DefaultEciMode est un champ statique public sur BarcodeWriter, par défaut sur EciMode.Auto. Attribuez-le une fois et chaque code-barres 2D généré par l'application le suit, quel que soit le format et quelle que soit la partie du code qui l'a produit. Il reflète le champ BarcodeWriter.DefaultCharacterEncoding existant :

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

Comment remplacer le mode pour un seul DataMatrix ?

Un EciMode par appel sur une surcharge CreateDataMatrix l'emporte sur BarcodeWriter.DefaultEciMode, et s'applique uniquement à cet appel.

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

Chaque surcharge CreateDataMatrix qui prend un EciMode suit le même schéma. Les données entrent d'abord, comme un string, un byte[] ou un Stream. Le dimensionnement vient ensuite, soit comme une taille de pixel unique, soit comme un DataMatrixWriter.DataMatrixShape avec une largeur et une hauteur explicites. EciMode est toujours le dernier paramètre. L'exemple ci-dessus passe une taille ; la surcharge de forme prend le même EciMode à la même position finale :

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'est-ce qui contrôle QR, Aztec et PDF417 ?

Ces trois formats n'ont pas d'argument EciMode. Il n'y a pas un tel paramètre sur QRCodeWriter, et aucun sur les surcharges BarcodeWriter.CreateBarcode génériques, donc BarcodeWriter.DefaultEciMode est le seul moyen de les contrôler.

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

Lorsqu'un code QR et un DataMatrix ont besoin d'un comportement ECI différent dans la même exécution, le DataMatrix prend l'argument par appel et le code QR suit le défaut statique.


Comment le paramètre se comporte-t-il à l'exécution ?

Quand DefaultEciMode prend-il effet ?

CreateBarcode, CreateDataMatrix et CreateQrCode renvoient un objet dont le mode n'est pas encore fixé. DefaultEciMode est lu lorsque le code-barres est enregistré ou autrement rendu, donc attribuer une nouvelle valeur en cours d'exécution affecte chaque code-barres enregistré après ce point, y compris les objets créés avant le changement.

Cela attrape la forme de lot courante : créez plusieurs codes-barres tout en changeant DefaultEciMode entre les appels, puis enregistrez-les ensemble à la fin. Tous prennent le mode qui a été défini en dernier. Enregistrez chaque code-barres avant de changer le mode pour le suivant, ou passez EciMode par appel à CreateDataMatrix, que le défaut statique n'atteint pas.

Avertissement: DefaultEciMode est un global statique mutable au niveau du processus et n'est pas sécurisé pour les threads. Une réaffectation est visible pour chaque thread immédiatement, donc la changer pendant qu'un autre thread génère ou enregistre signifie que ce fil observe le changement en cours d'exécution. Traitez-le comme une politique de démarrage d'application, exactement comme avec BarcodeWriter.DefaultCharacterEncoding.

Quand EciMode.Off provoque-t-il une exception ?

Off est une promesse que les données sont en ASCII. Brisez cette promesse et l'appel provoque IronBarCodeEncodingException, sous n'importe quel paramètre BarcodeWriter.DefaultCharacterEncoding. Le défaut UTF-8 donne le message le plus utile :

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

Sous ISO_8859_1, la même combinaison apparaît comme une erreur de codeur natif de bas niveau.

La charge utile n'est souvent pas entièrement sous le contrôle de l'application : entrée utilisateur, flux amont, nom de produit provenant d'un catalogue fournisseur. Un emballage défensif le couvre :

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

Le repli ici passe ce symbole à Auto, dans l'idée qu'un code-barres correct atteignant un scanner compatible ECI est préférable à aucun code-barres. La bonne récupération dépend du déploiement : où les scanners ne peuvent réellement pas lire l'ECI, rejeter l'enregistrement pour un traitement manuel est le choix le plus sûr.

Le type est également listé dans le guide de gestion des erreurs et de débogage, qui couvre la famille des exceptions sans cette cause spécifique.


Comment choisir un mode ?

Comment baliser chaque symbole à nouveau ?

Une ligne, au démarrage :

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 ramène chaque format 2D à un comportement toujours balisé, produisant une sortie identique en octets aux versions 2026.8.6 et antérieures pour la même entrée. C'est le bon choix pour une application dont les systèmes en aval ont été construits contre la sortie balisée, pour une norme qui nécessite une déclaration explicite de codage sur chaque symbole, ou simplement comme un moyen de retarder le changement pendant que ses effets sont évalués.

Le cas inverse vaut également la peine d'être nommé. Une application qui a été mise à jour, trouvé que ses symboles sont devenus plus petits, et en est satisfaite n'a besoin d'aucune action : Auto est déjà la valeur par défaut.

Quel mode convient à quelle situation ?

Mode ECI recommandé par scénario, et où chacun est configuré

ScénarioMode ECIOù définir
Génération généraliste, contenu mixteAutoRien à faire ; c'est le défaut
Flotte de scanners anciens qui échouent sur ECIOffDefaultEciMode au démarrage
La norme exige un encodage explicite sur chaque symboleForceUtf8DefaultEciMode au démarrage
Un symbole de conformité parmi une sortie autrement normaleForceUtf8Par appel, uniquement DataMatrix
Contenu de la charge utile non garanti en ASCIIAuto, ou Off avec une captureL'un ou l'autre, avec gestion des exceptions

Où aller ensuite

Le comportement décrit ici est un paramètre avec trois valeurs, et la plupart des applications le définiront une fois et ne le revisiteront jamais. Les deux décisions qui méritent d'être prises délibérément sont de savoir si la flotte de scanners comprend l'ECI, et si une norme en aval exige une déclaration sur chaque symbole.

Pour quels formats de code-barres prennent en charge le contenu Unicode, consultez le Comment écrire des codes-barres UTF-8 et Unicode, qui couvre le support Unicode au niveau du format et renvoie ici pour le détail ECI. Pour générer les formats 2D eux-mêmes, le Comment créer des codes-barres 2D couvre la génération de DataMatrix, QR, Aztec et PDF417. La documentation complète de la classe se trouve dans la référence de l'API IronBarcode.

Ahmad est un développeur full-stack avec une solide fondation en C#, Python et technologies web. Il a un profond intérêt pour la construction de solutions logicielles évolutives et aime explorer comment le design et la fonctionnalité se rencontrent dans des applications du monde réel.

Lire la suite

Prêt à commencer ?

Téléchargements NuGet 2,564,559Version :2026.11tout juste publié