Jak kontrolować tagowanie UTF-8 ECI dla kodów kreskowych 2D w C#

Ahmad Sohail
Ahmad Sohail
Zaktualizowano: 9 września 2026

Kod kreskowy 2D, który był innego rozmiaru niż oczekiwano, starszy skaner, który odmawia odczytania symbolu, który wcześniej odczytywał, i standard wymagający, aby każdy symbol deklarował swoje kodowanie sprowadzają się do tego samego pytania: czy kod kreskowy posiada nagłówek UTF-8 ECI (Extended Channel Interpretation)?

Ten nagłówek informuje skaner, aby interpretował ładunek jako UTF-8, co jest istotne w przypadku języka chińskiego, arabskiego, tajskiego lub innych treści spoza zwykłego ASCII. To nie jest za darmo. Nagłówek zużywa kody, do tego stopnia, że ładunek już zbliżający się do granicy rozmiaru może przejść do większego symbolu, a skanery zbudowane przed istnieniem ECI odrzucają symbol z jego użyciem. IronBarcode zapisuje więc nagłówek tylko wtedy, gdy dane zawierają znaki spoza ASCII, a ustawienie EciMode nadpisuje tę decyzję w obu kierunkach.

Uwaga: Wymaga IronBarcode 2026.9.2 lub nowszego. API nie istnieje w wersji 2026.8.6 ani wcześniejszych, gdzie wywołanie powoduje błąd kompilacji, a nie awarię w czasie wykonywania.
Szybki start: Ustaw polisy ECI dla każdego kodu kreskowego 2D

Przypisz politykę raz, a następnie generuj kody kreskowe, jak zwykle. Każdy format 2D stosuje się do niej, bez dodatkowych argumentów.

  1. 1Zainstaluj IronBarcode z NuGet Package Manager

    PM > Install-Package BarCode

  2. 2Skopiuj i uruchom ten fragment kodu.

    IronBarCode.BarcodeWriter.DefaultEciMode = IronBarCode.EciMode.ForceUtf8;
    IronBarCode.BarcodeWriter.CreateBarcode("BK005|8389|0001", IronBarCode.BarcodeEncoding.QRCode).SaveAsPng("part-qr.png");
  3. 3Wdrożenie do testowania w środowisku produkcyjnym

    Rozpocznij korzystanie z IronBarcode w swoim projekcie już dziś z darmową wersją próbną
    arrow pointer


Kiedy IronBarcode dodaje nagłówek ECI?

Nic z tego, co już piszesz, się nie zmienia. Wygeneruj DataMatrix z numerem części ASCII, a symbol nie ma nagłówka; przekaż tym samym metodzie ładunek z umlautem, a nagłówek się pojawi, ponieważ wartość tego wymaga. Argument EciMode w wywołaniu nadpisuje tę ocenę.

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

Trzy symbole powyżej różnią się tylko ładunkiem i tym, czy tryb został dostarczony. Obrazy poniżej są narysowane w stałym rozmiarze modułu, więc symbole różnią się ogólnym rozmiarem tak, jak by to było na wydrukowanej etykiecie.

DataMatrix kodujący numer części ASCII w trybie EciMode.Auto, symbol 16 na 16 modułów bez nagłówka ECI

ASCII, Auto – 16 × 16 modułów, bez nagłówka

DataMatrix kodujący numer części zawierający niemiecki umlaut w trybie EciMode.Auto, symbol 22 na 22 moduły z nagłówkiem ECI UTF-8

Non-ASCII, Auto – 22 × 22 modułów, dodany nagłówek

DataMatrix kodujący ten sam numer części ASCII w trybie EciMode.ForceUtf8, symbol 16 na 16 modułów, tej samej wielkości co zwykły symbol ASCII

ASCII, ForceUtf8 – 16 × 16 modułów, wymuszony nagłówek


Ładunek ASCII koduje się do siatki 16 × 16, niezależnie od tego, czy nagłówek jest wymuszony: ta konkretna wartość ma wystarczającą rezerwę, że dodatkowe kody są bez kosztu. Ładunek non-ASCII wymaga pełnego większego poziomu, 22 × 22, ponieważ nagłówek i wielobajtowa treść razem już się nie mieszczą przy 16 × 16. Nagłówek jedynie powiększa symbol, gdy ładunek jest już blisko granicy rozmiaru, i to, czy tak jest dla danej wartości, nie jest widoczne z samego ciągu.

Jakie są trzy tryby ECI?

  • Auto: Zapisuje nagłówek UTF-8 ECI tylko wtedy, gdy dane zawierają znaki spoza ASCII. To jest domyślne ustawienie i produkuje najmniejszy symbol dla czystego ładunku ASCII.
  • ForceUtf8: Zawsze zapisuje nagłówek, również dla czystego ASCII. Użyj tego dla ścisłego przestrzegania standardów lub gdy każdy symbol musi deklarować swoje kodowanie.
  • Off: Nigdy nie zapisuje nagłówka. Używaj tylko wtedy, gdy dane są znane jako ASCII lub Latin-1, a dekoder nie rozumie ECI.
Uwaga: ECI dotyczy tylko formatów 2D. EciMode nie ma wpływu na kody kreskowe 1D, takie jak Code 128, EAN lub UPC.

Jak ustawić tryb ECI?

Jak zastosować jedną politykę w całej aplikacji?

BarcodeWriter.DefaultEciMode to publiczne pole statyczne na BarcodeWriter, domyślnie ustawione na EciMode.Auto. Przypisz je raz, a każdy kod kreskowy 2D generowany przez aplikację się do niego stosuje, niezależnie od formatu czy części bazy kodu, która go wyprodukowała. Odwzorowuje istniejące pole 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);
}

Jak nadpisać tryb dla pojedynczego DataMatrix?

EciMode na przeciążeniu CreateDataMatrix wygrywa nad BarcodeWriter.DefaultEciMode i stosuje się tylko do tego wywołania.

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

Każde przeciążenie CreateDataMatrix, które przyjmuje EciMode, stosuje ten sam wzorzec. Dane są wprowadzane najpierw, jako string, byte[] lub Stream. Rozmiarowanie jest następne, albo jako pojedynczy rozmiar pikselowy, albo jako DataMatrixWriter.DataMatrixShape z wyraźną szerokością i wysokością. EciMode zawsze jest ostatnim parametrem. Powyższy przykład przekazuje rozmiar; przeciążenie kształtu przyjmuje to samo EciMode w tej samej ostatniej pozycji:

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

Co kontroluje QR, Aztec i PDF417?

Te trzy formaty nie mają argumentu EciMode. Nie ma takiego parametru na QRCodeWriter, a żadnego na ogólnych przeciążeniach BarcodeWriter.CreateBarcode, więc BarcodeWriter.DefaultEciMode to jedyny sposób ich kontrolowania.

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

Gdzie kod QR i DataMatrix wymagają różnego zachowania ECI w tym samym uruchomieniu, DataMatrix przyjmuje argument per-call, a kod QR podąża za domyślnym statycznym.


Jak ustawienie zachowuje się w czasie wykonania?

Kiedy DefaultEciMode wchodzi w życie?

CreateBarcode, CreateDataMatrix i CreateQrCode zwracają obiekt, którego tryb nie jest jeszcze ustalony. DefaultEciMode jest odczytywany, gdy kod kreskowy jest zapisywany lub w inny sposób renderowany, więc przypisanie nowej wartości w trakcie uruchamiania wpływa na każdy kod kreskowy zapisany po tym punkcie, w tym obiekty stworzone przed zmianą.

To wyłapuje powszechny kształt batchowy: utwórz kilka kodów kreskowych, zmieniając DefaultEciMode między wywołaniami, a następnie zapisz je razem na końcu. Wszystkie przyjmują ostatnio ustawiony tryb. Zapisz każdy kod kreskowy przed zmianą trybu na kolejny lub przekaż EciMode na wywołanie CreateDataMatrix, którego domyślny statyczny nie osiąga.

Ostrzeżenie: DefaultEciMode jest zmiennym procesem globalnym i nie jest bezpieczny dla watkow. Przypisanie jest widoczne dla każdego wątku natychmiast, więc zmiana w trakcie generowania lub zapisywania przez inny wątek oznacza, że ten wątek widzi zmianę w czasie wykonywania. Traktuj to jako polisę inicjacji aplikacji, dokładnie tak jak w przypadku BarcodeWriter.DefaultCharacterEncoding.

Kiedy EciMode.Off wyrzuca wyjątek?

Off to obietnica, że dane są ASCII. Złam tę obietnicę, a wywołanie wyrzuci IronBarCodeEncodingException, pod każdą opcją ustawienia BarcodeWriter.DefaultCharacterEncoding. Domyślny UTF-8 daje bardziej przydatną wiadomość:

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

Pod ISO_8859_1 ta sama kombinacja pojawia się jako błąd natywnego kodera niższego poziomu.

Ładunek często nie jest w pełni pod kontrolą aplikacji: dane wejściowe od użytkownika, strumień zasilający, nazwa produktu z katalogu dostawcy. Jednorazowy kod obronny to pokrywa:

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

Tutaj fallback przełącza ten symbol na Auto, ponieważ poprawny kod kreskowy dotarcie do skanera rozumiejącego ECI przewyższa brak kodu kreskowego. Poprawna odpowiedź zależy od wdrożenia: gdzie skanery rzeczywiście nie mogą odczytać ECI, odrzucenie rekordu do ręcznego przetwarzania jest bezpieczniejszym wyborem.

Typ jest również wymieniony w przewodniku obsługi błędów i debugowania, który obejmuje rodzinę wyjątków bez tej konkretnej przyczyny.


Jak wybrać tryb?

Jak ponownie otagować każdy symbol?

Jedna linia na starcie:

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 przywraca każdy format 2D do zawsze otagowanego trybu, produkując bajtowo identyczne wyjście jak w 2026.8.6 i wcześniejszych dla tych samych danych wejściowych. To jest właściwy wybór dla aplikacji, których systemy downstream były budowane pod kątem otagowanego wyjścia, dla standardu, który wymaga wyraźnego deklarowania kodowania na każdym symbolu, lub po prostu jako sposób odroczenia zmiany, podczas gdy jej efekty są oceniane.

Warto również nazwaniem odwrotnej sytuacji. Aplikacja, która została zaktualizowana, odkryła, że jej symbole stały się mniejsze i jest z tego zadowolona, nie wymaga żadnej akcji: Auto to już domyślne.

Który tryb pasuje do której sytuacji?

Zalecany tryb ECI w zależności od scenariusza i gdzie każdy z nich jest konfigurowany

ScenariuszTryb ECIGdzie ustawić
Ogólne generowanie, mieszana treśćAutoNie ma nic do zrobienia; to jest domyślne
Flota starszych skanerów, które zawodzą na ECIOffDefaultEciMode przy starcie
Standard wymaga wyraźnego kodowania na każdym symboluForceUtf8DefaultEciMode przy starcie
Jeden symbol zgodności wśród innych normalnych wyjśćForceUtf8Per-call, tylko DataMatrix
Zawartość ładunku nie gwarantuje ASCIIAuto albo Off z przechwyceniemDowolny, z obsługą wyjątków

Dokąd się udać dalej

Zachowanie opisane tutaj to jedno ustawienie z trzema wartościami i większość aplikacji ustawi je raz i nigdy więcej nie będzie się tym wybierała. Dwie decyzje, które warto podjąć celowo, to czy flota skanerów rozumie ECI i czy jakiś standard downstream wymaga deklaracji na każdym symbolu.

Aby dowiedzieć się, które formaty kodów kreskowych w pierwszej kolejności wspierają zawartość Unicode, zobacz Jak pisać kody kreskowe UTF-8 i Unicode, który obejmuje wsparcie Unicode na poziomie formatu i linkuje tutaj dla szczegółów ECI. Aby wygenerować same formaty 2D, Jak stworzyć kody kreskowe 2D obejmuje generowanie DataMatrix, QR, Aztec i PDF417. Pełna dokumentacja klasy znajduje się w dokumnetacji API IronBarcode.

Ahmad to full-stack developer z solidnym fundamentem w C#, Pythonie i technologiach webowych. Ma głębokie zainteresowanie tworzeniem skalowalnych rozwiązań oprogramowania i cieszy się badaniem, jak projektowanie i funkcjonalność spotykają się w rzeczywistych aplikacjach.

Czytaj więcej

Gotowy, aby rozpocząć?

Pobrania z NuGet 2,564,559Wersja:2026.11właśnie wydane