Wie man UTF-8 ECI-Auszeichnungen für 2D-Barcodes in C# steuert

Ahmad Sohail
Ahmad Sohail
Aktualisiert: 9. September 2026

Ein 2D-Barcode, der in einer unerwarteten Größe herausgekommen ist, ein älterer Scanner, der ein Symbol ablehnt, das er früher gelesen hat, und ein Standard, der fordert, dass jedes Symbol seine Kodierung deklariert, laufen alle auf die gleiche Frage hinaus: Trägt der Barcode einen UTF-8 ECI (Extended Channel Interpretation)-Header?

Dieser Header weist einen Scanner an, die Nutzlast als UTF-8 zu interpretieren, was für Chinesisch, Arabisch, Thai oder jeden anderen Inhalt außerhalb des reinen ASCII wichtig ist. Es ist nicht kostenlos. Der Header verbraucht Codewörter, genug, um eine Nutzlast, die bereits nahe an einer Größenbeschränkung ist, in ein größeres Symbol überlaufen zu lassen, und Scanner, die vor der Existenz von ECI gebaut wurden, lehnen ein Symbol ab, das eines trägt. IronBarcode schreibt daher den Header nur, wenn die Daten Nicht-ASCII-Zeichen enthalten, und die EciMode-Einstellung überschreibt diese Entscheidung in jede Richtung.

Bitte beachten Sie: Erfordert IronBarcode 2026.9.2 oder höher. Die API existiert nicht in 2026.8.6 oder früher, wo der Aufruf zu einem Kompilierungsfehler führt, anstatt zu einem Laufzeitfehler.
Schnellstart: Festlegen der ECI-Richtlinie für jeden 2D-Barcode

Weisen Sie die Richtlinie einmal zu, und dann generieren Sie Barcodes wie gewohnt. Jedes 2D-Format folgt ihr, ohne weitere Argumente.

  1. 1Installieren Sie IronBarcode mit NuGet Package Manager

    PM > Install-Package BarCode

  2. 2Kopieren Sie diesen Codeausschnitt und führen Sie ihn aus.

    IronBarCode.BarcodeWriter.DefaultEciMode = IronBarCode.EciMode.ForceUtf8;
    IronBarCode.BarcodeWriter.CreateBarcode("BK005|8389|0001", IronBarCode.BarcodeEncoding.QRCode).SaveAsPng("part-qr.png");
  3. 3Bereitstellen zum Testen in Ihrer Live-Umgebung

    Beginnen Sie noch heute, IronBarcode in Ihrem Projekt mit einer kostenlosen Testversion zu verwenden
    arrow pointer


Wann fügt IronBarcode einen ECI-Header hinzu?

Nichts an dem Aufruf, den Sie bereits geschrieben haben, ändert sich. Generieren Sie eine DataMatrix aus einer ASCII-Teilenummer und das Symbol enthält keinen Header; geben Sie der gleichen Methode eine Nutzlast mit einem Umlaut und der Header erscheint, weil der Wert ihn benötigt. Ein EciMode-Argument beim Aufruf überschreibt dieses Urteil.

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

Die drei Symbole oben unterscheiden sich nur in ihrer Nutzlast und darin, ob ein Modus angegeben wurde. Die unten gezeigten Bilder werden in fester Modulgröße gezeichnet, sodass die Symbole sich in ihrer Gesamtheit so unterscheiden, wie sie auf einem gedruckten Etikett erscheinen würden.

DataMatrix mit einer ASCII-Teilenummer unter EciMode.Auto, ein Symbol mit 16 × 16 Modulen ohne ECI-Header

ASCII, Auto - 16 × 16 Module, kein Header

DataMatrix mit einer Teilenummer mit deutschem Umlaut unter EciMode.Auto, ein Symbol mit 22 × 22 Modulen und UTF-8-ECI-Header

Nicht-ASCII, Auto - 22 × 22 Module, Header hinzugefügt

DataMatrix mit derselben ASCII-Teilenummer unter EciMode.ForceUtf8, ein Symbol mit 16 × 16 Modulen und damit so groß wie das reine ASCII-Symbol

ASCII, ForceUtf8 - 16 × 16 Module, Header erzwungen


Die ASCII-Nutzlast kodiert in ein 16 × 16 Raster, egal ob ein Header erzwungen wird oder nicht: Dieser bestimmte Wert hat genug freie Kapazität, sodass die zusätzlichen Codewörter nichts kosten. Die Nicht-ASCII-Nutzlast benötigt eine voluminöser Tiersgröße von 22 × 22, weil der Header und der mehrbyteige Inhalt zusammen nicht länger auf 16 × 16 passen. Ein Header vergrößert das Symbol nur, wenn die Nutzlast bereits nahe an einer Größenbegrenzung ist, und ob das für einen bestimmten Wert zutrifft, ist aus der Zeichenkette selbst nicht ersichtlich.

Was sind die drei ECI-Modi?

  • Auto: Schreibt den UTF-8 ECI-Header nur, wenn die Daten Nicht-ASCII-Zeichen enthalten. Dies ist der Standard und produziert das kleinste Symbol für eine reine ASCII-Nutzlast.
  • ForceUtf8: Schreibt immer den Header, auch für reines ASCII. Verwenden Sie es für strikte Standardkonformität oder wenn jedes Symbol seine Kodierung deklarieren muss.
  • Off: Schreibt niemals den Header. Verwenden Sie es nur, wenn die Daten bekannt sind, ASCII oder Latin-1 zu sein, und der Decoder ECI nicht versteht.
Bitte beachten Sie: ECI gilt nur für 2D-Formate. EciMode hat keine Wirkung auf 1D-Barcodes wie Code 128, EAN oder UPC.

Wie setze ich den ECI-Modus?

Wie kann ich eine Richtlinie in der gesamten Anwendung anwenden?

BarcodeWriter.DefaultEciMode ist ein öffentliches statisches Feld auf BarcodeWriter, das standardmäßig auf EciMode.Auto gesetzt ist. Weisen Sie es einmal zu und jeder 2D-Barcode, den die Anwendung generiert, folgt ihm, egal welches Format und welcher Teil des Codebase ihn produziert hat. Es spiegelt das bestehende BarcodeWriter.DefaultCharacterEncoding-Feld wider:

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

Wie überschreibe ich den Modus für eine einzelne DataMatrix?

Ein pro-Aufruf EciMode bei einer CreateDataMatrix Überladung gewinnt über BarcodeWriter.DefaultEciMode und gilt nur für diesen Aufruf.

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

Jede CreateDataMatrix Überladung, die ein EciMode benötigt, folgt demselben Muster. Die Daten gehen zuerst rein, als ein string, ein byte[] oder ein Stream. Die Größenfestlegung kommt als nächstes, entweder als einzelner Pixelgröße oder als ein DataMatrixWriter.DataMatrixShape mit expliziter Breite und Höhe. EciMode ist immer der letzte Parameter. Das obige Beispiel gibt eine Größe an; die Formüberladung nimmt dasselbe EciMode an der gleichen Endposition:

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

Was steuert QR, Aztec und PDF417?

Diese drei Formate haben keinen EciMode-Parameter. Es gibt keinen solchen Parameter bei QRCodeWriter und keinen bei den generischen BarcodeWriter.CreateBarcode Überladungen, also ist BarcodeWriter.DefaultEciMode der einzige Weg, sie zu steuern.

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

Wenn ein QR-Code und eine DataMatrix im selben Lauf unterschiedliches ECI-Verhalten benötigen, nimmt die DataMatrix das pro-Aufruf-Argument an und der QR-Code folgt dem statischen Standard.


Wie verhält sich die Einstellung zur Laufzeit?

Wann wird DefaultEciMode wirksam?

CreateBarcode, CreateDataMatrix und CreateQrCode geben ein Objekt zurück, dessen Modus noch nicht festgelegt ist. DefaultEciMode wird gelesen, wenn der Barcode gespeichert oder anderweitig gerendert wird, sodass die Zuweisung eines neuen Werts mitten im Lauf alle nach diesem Punkt gespeicherten Barcodes beeinflusst, einschließlich derjenigen, die vor der Änderung erstellt wurden.

Dies erfasst die häufige Batchform: Erstellen Sie mehrere Barcodes, während Sie DefaultEciMode zwischen den Aufrufen ändern, und speichern Sie sie dann zusammen am Ende. Alle von ihnen nehmen den zuletzt eingestellten Modus. Speichern Sie jeden Barcode, bevor Sie den Modus für den nächsten ändern, oder übergeben Sie EciMode pro Aufruf an CreateDataMatrix, das den statischen Standard nicht erreicht.

Warnung: DefaultEciMode ist ein veränderlicher, prozessglobaler statischer Wert und nicht threadsicher. Eine Zuordnung wird für jeden Thread sofort sichtbar, sodass sich das Ändern, während ein anderer Thread generiert oder speichert, bedeutet, dass dieser Thread die Änderung mitten im Lauf beobachtet. Behandeln Sie es als Anwendung-Startpolitik, genau wie bei BarcodeWriter.DefaultCharacterEncoding.

Wann wirft EciMode.Off eine Ausnahme?

Off ist ein Versprechen, dass die Daten ASCII sind. Brechen Sie dieses Versprechen und der Aufruf wirft IronBarCodeEncodingException, unter jedem BarcodeWriter.DefaultCharacterEncoding-Einstellung. Der UTF-8-Standard gibt die nützlichere Nachricht:

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

Unter ISO_8859_1 taucht dieselbe Kombination als niederstufiger nativer Kodierungsfehler auf.

Die Nutzlast ist oft nicht vollständig unter der Kontrolle der Anwendung: Benutzereingaben, ein upstream-Feed, ein Produktname aus einem Lieferantenkatalog. Ein defensiver Wrapper deckt es ab:

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

Das hier gezeigte Fallback schaltet dieses Symbol auf Auto um, mit der Ansicht, dass ein korrekter Barcode, der einen ECI-awaren Scanner erreicht, keinen Barcode schlägt. Die richtige Wiederherstellung hängt von der Bereitstellung ab: Dort, wo die Scanner wirklich kein ECI lesen können, ist es die sicherere Wahl, den Datensatz für die manuelle Bearbeitung abzulehnen.

Der Typ ist auch im Fehlerbehandlungs- und Debugging-Leitfaden aufgelistet, der die Ausnahmegruppe ohne diese spezifische Ursache abdeckt.


Wie wähle ich einen Modus?

Wie tagge ich jedes Symbol wieder?

Eine Zeile, beim Start:

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 gibt jedes 2D-Format auf das immer-getaggte Verhalten zurück, und produziert byte-identischen Output zu 2026.8.6 und früher für dasselbe Eingabedaten. Dies ist die richtige Wahl für eine Anwendung, deren nachgelagerte Systeme gegen den getaggten Output gebaut wurden, für einen Standard, der eine explizite Kodierungsdeklaration auf jedem Symbol erfordert, oder einfach als eine Möglichkeit, die Änderung zu verzögern, während ihre Effekte bewertet werden.

Der umgekehrte Fall ist auch erwähnenswert. Eine Anwendung, die ein Upgrade durchgeführt hat und festgestellt hat, dass ihre Symbole kleiner wurden und darüber freut sich, benötigt überhaupt keine Maßnahmen: Auto ist bereits der Standard.

Welcher Modus passt zu welcher Situation?

Empfohlener ECI-Modus nach Szenario und wo jeder konfiguriert wird

SzenarioECI-ModusWo einzustellen
Allgemeine Generation, gemischter InhaltAutoNichts zu tun; es ist der Standard
Flotte älterer Scanner, die bei ECI ausfallenOffDefaultEciMode beim Start
Standard erfordert explizite Kodierung auf jedem SymbolForceUtf8DefaultEciMode beim Start
Ein Kompliancesymbol unter ansonsten normalem OutputForceUtf8Pro-Aufruf, nur DataMatrix
Nutzlastinhalte nicht garantiert ASCIIAuto, oder Off mit einem CatchEntweder, mit Ausnahmebehandlung

Wo als nächstes hingehen

Das hier beschriebene Verhalten ist eine Einstellung mit drei Werten und die meisten Anwendungen werden es einmal einstellen und nie wieder darauf zurückkommen. Die beiden Entscheidungen, die es wert sind, absichtlich getroffen zu werden, sind, ob die Scannerflotte ECI versteht und ob ein nachgelagerter Standard eine Deklaration auf jedem Symbol erfordert.

Welche Barcode-Formate Unicode-Inhalte überhaupt unterstützen, finden Sie im Schreiben von UTF-8 und Unicode Barcodes-Anleitung, die die Unicode-Unterstützung auf Formatebene abdeckt und hier für die ECI-Details verlinkt. Für die Erzeugung der 2D-Formate selbst deckt die Erzeugung von 2D-Barcodes-Anleitung die Erzeugung von DataMatrix, QR, Aztec und PDF417 ab. Die vollständige Klassendokumentation befindet sich in der IronBarcode API-Referenz.

Ahmad ist ein Full-Stack-Entwickler mit einer soliden Grundlage in C#, Python und Webtechnologien. Er hat ein großes Interesse am Aufbau skalierbarer Softwarelösungen und genießt es, zu erkunden, wie Design und Funktionalität in realen Anwendungen aufeinandertreffen.

Mehr lesen

Bereit loszulegen?

NuGet-Downloads 2,564,559Version:2026.11gerade veröffentlicht