C# ile 2D Barkodlar için UTF-8 ECI Etiketlemesini Nasıl Kontrol Edebilirim

Ahmad Sohail
Ahmad Sohail
Güncellendi: 9 Eylül 2026

Beklenenden farklı boyutta çıkan bir 2D barkod, okumayı reddeden eski bir tarayıcı ve her sembolün kodlamasını belirtmesini zorunlu kılan bir standart aynı soruya gelir: barkod bir UTF-8 ECI (Extended Channel Interpretation) başlığı taşıyor mu?

Bu başlık, tarayıcıya yükü UTF-8 olarak yorumlamasını söyler ve bu, Çince, Arapça, Tayca veya sıradan ASCII'nin dışındaki herhangi bir içerik için önemlidir. Bu ücretsiz değildir. Başlık, kod kelimelerini tüketir, öyle ki boyut sınırına yakın bir yük zaten daha büyük bir sembole sığabilir ve ECI'nin varlığından önce üretilmiş tarayıcılar, ECI taşıyan bir sembolü reddederler. Bu nedenle IronBarcode, yalnızca veriler ASCII olmayan karakterler içerdiğinde başlığı yazar ve EciMode ayarı bu kararı her iki yönde geçersiz kılar.

Lütfen dikkat: IronBarcode 2026.9.2 veya sonraki sürümlerini gerektirir. API, 2026.8.6 veya önceki sürümlerde mevcut değildir; burada çağrı, çalışma zamanı hatası yerine derleme hatası üretir.
Hızlı Başlangıç: Her 2D Barkod İçin ECI Politikasını Ayarlayın

Politikayı bir kez atayın, ardından normalde yaptığınız gibi barkodları oluşturun. Her 2D formatı bunu takip eder, daha fazla argümana gerek yoktur.

  1. 1IronBarcode ile NuGet Package Manager'u yükleyin

    PM > Install-Package BarCode

  2. 2Bu kod parçacığını kopyalayın ve çalıştırın.

    IronBarCode.BarcodeWriter.DefaultEciMode = IronBarCode.EciMode.ForceUtf8;
    IronBarCode.BarcodeWriter.CreateBarcode("BK005|8389|0001", IronBarCode.BarcodeEncoding.QRCode).SaveAsPng("part-qr.png");
  3. 3Canlı ortamınızda test için dağıtım yapın

    Projenizde IronBarcode'yi bugün ücretsiz deneme sürümü ile kullanmaya başlayın
    arrow pointer


IronBarcode Ne Zaman Bir ECI Başlığı Ekler?

Zaten yazdığınız çağrıda hiçbir şey değişmez. Bir ASCII parça numarasından bir DataMatrix oluşturun ve sembol herhangi bir başlık taşımaz; aynı yönteme içeriğinde ünlü bulunan bir yük verin ve başlık belirdiğinde, çünkü değer buna ihtiyaç duyar. Çağrıdaki bir EciMode argümanı bu yargıyı geçersiz kılar.

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

Yukarıdaki üç sembol yalnızca yük açısından ve bir modun sağlanıp sağlanmadığı açısından farklılık gösterir. Aşağıdaki görüntüler sabit bir modül boyutunda çizilmiştir, bu nedenle semboller, etiket üzerine basıldıklarında farklılık gösterir.

EciMode.Auto altında bir ASCII parça numarasını kodlayan DataMatrix, ECI başlığı olmayan 16x16 modüllük bir sembol

ASCII, Auto - 16 × 16 modüller, başlık yok

EciMode.Auto altında Almanca umlaut içeren bir parça numarasını kodlayan DataMatrix, UTF-8 ECI başlığı taşıyan 22x22 modüllük bir sembol

ASCII olmayan, Auto - 22 × 22 modüller, başlık eklendi

EciMode.ForceUtf8 altında aynı ASCII parça numarasını kodlayan DataMatrix, düz ASCII sembolüyle aynı boyutta 16x16 modüllük bir sembol

ASCII, ForceUtf8 - 16 × 16 modüller, başlık zorunlu


ASCII yükü, başlık zorunlu olup olmadığına bakılmaksızın 16 × 16 bir ızgaraya kodlanır: bu özel değer, ekstra kod kelimelerinin maliyeti olmadan yeterli yedek kapasiteye sahiptir. ASCII olmayan yük daha fazla bir tam boyut katmanı gerektirir, 22 × 22, çünkü başlık ve çok baytlı içerik bir araya gelerek artık 16 × 16'a sığmıyor. Başlık yalnızca yük halihazırda bir boyut sınırına yakın olduğunda sembolü büyütür ve bunun, belirli bir değer için doğru olup olmadığı, dizeden görünür değildir.

Üç ECI Modu Nedir?

  • Auto: Yalnızca veriler ASCII olmayan karakterler içerdiğinde UTF-8 ECI başlığını yazar. Bu varsayılandır ve saf-ASCII yüklü bir sembol için en küçük sembolü üretir.
  • ForceUtf8: Her zaman başlığı yazar, saf ASCII için de dahil. Katı standartlara uyum için veya her sembolün kodlamasını belirlemesi gerektiği durumlarda kullanın.
  • Off: Asla başlığı yazmaz. Yalnızca verilerin ASCII veya Latin-1 olarak bilindiği ve kod çözücünün ECI'yi anlamadığı yerlerde kullanın.
Lütfen dikkat: ECI yalnızca 2D formatlara uygulanır. EciMode, Code 128, EAN veya UPC gibi 1D barkodlarda etkisi yoktur.

ECI Modunu Nasıl Ayarlayabilirim?

Uygulama Genelinde Bir Politikayı Nasıl Uygularım?

BarcodeWriter.DefaultEciMode, BarcodeWriter üzerinde kamuya açık statik bir alandır ve varsayılan olarak EciMode.Auto şeklindedir. Bir kez atayın ve uygulamanın ürettiği her 2D barkod bunu takip eder, hangi formatta ve kod tabanının hangi bölümünde üretilmiş olursa olsun. Var olan BarcodeWriter.DefaultCharacterEncoding alanını yansıtır:

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

Tek Bir DataMatrix İçin Modu Nasıl Geçersiz Kılarım?

Bir çağrı başına EciMode, CreateDataMatrix aşırı yüklemesinde BarcodeWriter.DefaultEciMode'ye üstün gelir ve yalnızca o çağrıya uygulanır.

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

Bir EciMode alanını alan her CreateDataMatrix aşırı yüklemesi aynı deseni takip eder. Veriler önce bir string, byte[] veya Stream olarak girilir. Boyutlandırma ya tek bir piksel boyutu olarak ya da belirli bir genişlik ve yükseklikte bir DataMatrixWriter.DataMatrixShape olarak gelir. EciMode her zaman son parametredir. Yukarıdaki örnek bir boyut geçirir; şekil aşırı yüklemesi aynı son pozisyonda aynı EciMode'yi alır:

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

QR, Aztek ve PDF417 Nasıl Kontrol Edilir?

Bu üç format, herhangi bir EciMode argümanına sahip değildir. QRCodeWriter üzerinde böyle bir parametre yoktur ve genel BarcodeWriter.CreateBarcode aşırı yüklemelerinde de yoktur, bu nedenle onları kontrol etmenin tek yolu BarcodeWriter.DefaultEciMode'dir.

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

Bir QR kodu ve bir DataMatrix aynı çalışmada farklı ECI davranışı gerektiriyorsa, DataMatrix çağrı başına argümanı alır ve QR kodu statik varsayılanı takip eder.


Ayar Çalışma Zamanında Nasıl Davranır?

DefaultEciMode Ne Zaman Etkili Olur?

CreateBarcode, CreateDataMatrix ve CreateQrCodeları, modu henüz sabitlenmemiş bir nesne döner. DefaultEciMode, barkod kaydedildiğinde veya başka bir şekilde render edildiğinde okunur, bu nedenle koşu sırasında ortasında yeni bir değer atamak, değişiklikten önce oluşturulan nesneler dahil olmak üzere o noktadan sonra kaydedilen her barkodu etkiler.

Bu, yaygın parti şeklini yakalar: DefaultEciMode'yi çağrılar arasında değiştirirken birkaç barkod oluşturun, ardından sonunda birlikte kaydedin. Hepsi, en son ayarlanan modu alır. Sonraki barkod için modu değiştirmeden önce her barkodu kaydedin veya statik varsayılanın ulaşamayacağı çağrılar başına EciMode'i CreateDataMatrix'ya geçirin.

Uyarı: DefaultEciMode bir değiştirilebilir süreç-genel statik değeridir ve thread-güvenli değildir. Bir yeniden atama, her iş parçacığına hemen görünür, bu nedenle başka bir iş parçacığı oluştururken veya kaydederken değiştirmek, o iş parçacığının değişikliği koşu sırasında gözlemlediği anlamına gelir. Bunu, neden BarcodeWriter.DefaultCharacterEncoding ile olduğu gibi uygulama başlatma politikası olarak ele alın.

EciMode.Off Ne Zaman Fırlatır?

Off, verilerin ASCII olduğu vaadidir. Bu vaadi bozmaktan IronBarCodeEncodingException fırlatır ve BarcodeWriter.DefaultCharacterEncoding ayarının ikisi de altında gerçekleşir. UTF-8 varsayılanı, daha yararlı mesajı verir:

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

ISO_8859_1 altında aynı kombinasyon daha düşük seviyede bir yerel kodlayıcı hatası olarak yüzeye çıkar.

Yük genellikle tam olarak uygulamanın kontrolünde değildir: kullanıcı girişi, yukarı akış beslemesi, bir tedarikçi kataloğundan bir ürün adı. Bir savunma sarıcı bunu kapsar:

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

Buradaki geri dönüş, görüşteki sembolü Auto'e geçirir, doğru bir barkodun ECI-bilinçli bir tarayıcıya ulaşmasının hiç olmamasından daha iyi bir seçim olduğu görüşüyle. Doğru kurtarma, dağıtım yerine bağlıdır; tarayıcıların gerçekten ECI'yi okuyamadığı bir yerde, kaydı manuel işleme için reddetmek daha güvenli bir seçenektir.

Tür, hata yönetimi ve hata ayıklama kılavuzunda da listelenmiştir, ancak bu özel sebebe değinmeden exception ailesine örtü sağlar.


Bir Mod Nasıl Seçilir?

Her Sembolü Yeniden Nasıl Etiketlerim?

Başlangıçta bir satır:

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, her 2D formatını her zaman etikete dönüşen davranışa geri döndürür, 2026.8.6 ve önceki sürümlerdeki aynı girdi için bayt özdeş çıkış üretir. Bu, etiketli çıktıya karşı oluşturulmuş sistemlerin bulunduğu bir uygulama için doğru tercihtir, her sembolde açık bir kodlama beyanı gerektiren bir standart veya etkilerinin değerlendirilmesi sırasında değişikliği ertelemenin bir yolu olarak.

Ters durum da ad vermeye değerdir. Yükseltilmiş, sembollerinin küçüldüğünü tespit etmiş ve bundan memnun bir uygulamanın hiçbir işlem yapmasına gerek yoktur: Auto zaten varsayılan.

Hangi Mod Hangi Duruma Uyar?

Senaryoya göre önerilen ECI modu ve her biri hangi yerde yapılandırılmıştır

SenaryoECI ModuNereye Ayarlanmalı
Genel amaçlı oluşturma, karışık içerikAutoYapacak bir şey yok; varsayılan
ECI üzerinde başarısız olan eski tarayıcı filosuOffbaşlangıçta DefaultEciMode
Standart her sembolde açık bir kodlama gerektiriyorForceUtf8başlangıçta DefaultEciMode
Başka türlü normal çıktının içinde bir uyum sembolüForceUtf8Çağrı başına, yalnızca DataMatrix
Yük içeriği ASCII garantili değilAuto veya Off ile hata ayıklama yapmakİkisi de, exception yönetimi ile

Sonraki Nereye Gidilir

Burada açıklanan davranış, üç değere sahip bir ayardır ve çoğu uygulama bunu bir kez ayarlayacak ve asla yeniden ziyaret etmeyecektir. Kasti olarak yapılmaya değer iki karar, tarayıcı filosunun ECI'yi anladığını mı anlamadığı mı ve herhangi bir aşağı akış standardın her sembolde bir beyan gerektirip gerektirmediğidir.

Unicode içeriği ilk etapta hangi barkod formatlarının desteklediğini görmek için format düzeyinde Unicode desteğini kapsayan ve ECI detayı için buraya bağlantı veren UTF-8 ve Unicode Barkodları nasıl yazılır nasıl kılavuzuna bakın. 2D formatlarını kendilerini oluşturmak için, 2D Barkodları Nasıl Oluşturulur kılavuzu, DataMatrix, QR, Aztek ve PDF417 oluşturmayı kapsar. Tam sınıf belgeleri IronBarcode API referansında bulunmaktadır.

Ahmad, C#, Python ve web teknolojilerinde sağlam bir temele sahip bir full-stack geliştiricidir. Gerçek dünyadaki uygulamalarda ölçeklenebilir yazılım çözümleri oluşturmaktan ve tasarım ile işlevselliğin nasıl buluştuğunu keşfetmekten derin bir ilgi duyar.

Daha Fazla Oku

Başlamaya Hazır mısınız?

NuGet İndirmeleri 2,564,559Sürüm:2026.11yeni çıktı