C#での2Dバコードに対するUTF-8 ECIタグの制御方法

Ahmad Sohail
Ahmad Sohail
更新日: 2026年9月9日

予想外のサイズで生成された2Dバコード、読み取れなくなったレガシースキャナー、そして全てのシンボルが自らのエンコーディングを宣言することを要求する標準、すべて同じ質問に行き着きます: バーコードにUTF-8 ECI(拡張チャンネル解釈)ヘッダーが含まれているかどうか?

そのヘッダーはスキャナーにペイロードをUTF-8として解釈させます。これは、通常のASCIIに含まれない中国語、アラビア語、タイ語またはその他のコンテンツにとって重要です。 それは無料ではありません。 ヘッダーはコードワードを消費するため、すでにサイズ境界に近いペイロードがより大きなシンボルにあふれる可能性があり、ECIが存在する前に作られたスキャナーはそれを含むシンボルを拒否します。 そのため、IronBarcodeはデータに非ASCII文字が含まれる場合にのみヘッダーを書きます。そして、EciMode設定はその判断をどちらの方向にも上書きします。

注意してください: IronBarcode 2026.9.2以上が必要です。 2026.8.6以前にはAPIが存在せず、コールはランタイムの失敗ではなくコンパイルエラーを引き起こします。
クイックスタート: すべての2Dバーコードに対するECIポリシーの設定

ポリシーを一度設定し、通常通りにバーコードを生成してください。 すべての2Dフォーマットはそれに従い、追加の引数は不要です。

  1. 1IronBarcode を NuGet Package Manager でインストールします

    PM > Install-Package BarCode

  2. 2このコード スニペットをコピーして実行します。

    IronBarCode.BarcodeWriter.DefaultEciMode = IronBarCode.EciMode.ForceUtf8;
    IronBarCode.BarcodeWriter.CreateBarcode("BK005|8389|0001", IronBarCode.BarcodeEncoding.QRCode).SaveAsPng("part-qr.png");
  3. 3実際の環境でテストするためにデプロイする

    今日からご自身のプロジェクトでIronBarcodeを使い始めるには、無料トライアルをお試しください。
    arrow pointer


IronBarcodeがECIヘッダーを追加するのはいつですか?

既に書いたコールについて何も変わりません。 ASCII部品番号からデータマトリックスを生成し、シンボルはヘッダーを持ちません; 同じメソッドにウムラウトを含むペイロードを渡すと、値がそれを必要とするためにヘッダーが現れます。 コールに対するEciMode引数がその判断を上書きします。

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

上記の3つのシンボルは、ペイロードと提供されたモードの有無だけが異なります。 以下の画像は固定のモジュールサイズで描かれているため、印刷されたラベル上でのようにシンボルの全体の大きさが異なります。

EciMode.Auto で ASCII の部品番号をエンコードした DataMatrix。ECI ヘッダーのない 16×16 モジュールのシンボル

ASCII、Auto - 16 × 16 モジュール、ヘッダーなし

EciMode.Auto でドイツ語のウムラウトを含む部品番号をエンコードした DataMatrix。UTF-8 ECI ヘッダーを持つ 22×22 モジュールのシンボル

非ASCII、Auto - 22 × 22 モジュール、ヘッダー追加

EciMode.ForceUtf8 で同じ ASCII の部品番号をエンコードした DataMatrix。プレーンな ASCII のものと同じサイズの 16×16 モジュールのシンボル

ASCII、ForceUtf8 - 16 × 16 モジュール、ヘッダー強制


ASCIIペイロードはヘッダーが強制されるかどうかにかかわらず16 × 16グリッドにエンコードされます。この特定の値は十分な予備容量を持っているため、余分なコードワードが何もコストを生じません。 非ASCIIペイロードは完全なサイズ階層、22 × 22を必要とします。なぜなら、ヘッダーとマルチバイトコンテンツが一緒になると16 × 16には収まらなくなるからです。ペイロードが既にサイズの境界に近い場合にのみ、ヘッダーがシンボルを拡張し、ある値に対してそれが真であるかどうかは文字列自体からは見えません。

3つのECIモードとは何ですか?

  • Auto: データが非ASCII文字を含む場合にのみUTF-8 ECIヘッダーを書きます。 これがデフォルトであり、純粋なASCIIペイロードに対して最も小さなシンボルを生成します。
  • ForceUtf8: 常にヘッダーを書き、純粋ASCIIを含みます。 厳密な標準準拠を必要とする場合やすべてのシンボルがエンコーディングを宣言しなければならない場合に使用してください。
  • Off: ヘッダーを書きません。 データがASCIIまたはLatin-1であることが知られており、デコーダーがECIを理解しない場合にのみ使用してください。
注意してください: ECIは2Dフォーマットにのみ適用されます。 1Dバーコードには、Code 128、EAN、UPCなどへのEciModeの効果はありません。

ECIモードをどのように設定しますか?

アプリケーション全体に1つのポリシーを適用する方法は?

BarcodeWriter.DefaultEciModeはBarcodeWriterのパブリックスタティックフィールドであり、デフォルトはEciMode.Autoです。 それを一度割り当てるとアプリケーションが生成するすべての2Dバーコードがそれに従います。どのフォーマットでもどのコードベースの部分で生成されても。 それは既存の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);
}

単一のデータマトリックスに対してモードを上書きする方法は?

1回ごとの呼び出しにおけるEciModeはCreateDataMatrixのオーバーロードに対して優先され、BarcodeWriter.DefaultEciModeよりも上位にあり、その呼び出しにのみ適用されます。

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

すべてのCreateDataMatrixオーバーロードでEciModeを取るものは同じパターンに従います。 データは最初にstring、byte[]またはStreamとして入力されます。 次に単一のピクセルサイズとして、または明示的な幅と高さを持つDataMatrixWriter.DataMatrixShapeとしてサイズ指定されます。 常に最後のパラメーターがEciModeです。 上記の例ではサイズを渡します。同じ最後の位置に同じEciModeを取る形状オーバーロードがあります:

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、Aztec、およびPDF417を何が制御しますか?

これらの3つのフォーマットにはEciMode引数がありません。 QRCodeWriterにはそのようなパラメータはなく、ジェネリックBarcodeWriter.CreateBarcodeオーバーロードにもないので、BarcodeWriter.DefaultEciModeがそれらを制御する唯一の方法です。

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

QRコードとデータマトリックスが同じ実行で異なるECI動作を必要とする場合、データマトリックスはコールごとの引数を取り、QRコードは静的デフォルトに従います。


実行時に設定はどのように動作しますか?

DefaultEciModeはいつ効果を発揮するのですか?

CreateBarcode、CreateDataMatrixとCreateQrCodeは、モードがまだ確定していないオブジェクトを返します。 DefaultEciModeはバーコードが保存されるか、その他の形でレンダリングされるときに読み取られ、新しい値を実行中に割り当てると、その時点以降に保存されるすべてのバーコードに影響を与えます。変更前に作成されたオブジェクトも含みます。

これは一般的なバッチ形状をとらえます:DefaultEciModeをコール間で変更しながら複数のバーコードを作成し、最後に一緒に保存します。 それらすべては最後に設定されたモードを取ります。次のバーコードのためにモードを変更する前に各バーコードを保存するか、静的デフォルトが届かないEciModeをCreateDataMatrixに呼び出しごとに渡します。

警告: DefaultEciModeは可変のプロセスグローバルスタティックであり、スレッドセーフではありません。 再割り当てはすべてのスレッドに即座に見え、別のスレッドが生成または保存している間にそれを変更すると、そのスレッドは実行中に変更を観測します。 それをアプリケーション起動時のポリシーとして扱い、BarcodeWriter.DefaultCharacterEncodingと全く同様にしてください。

EciMode.Offはいつスローしますか?

OffはデータがASCIIであるという約束です。 その約束を破ると、呼び出しがIronBarCodeEncodingExceptionを発生させ、どちらのBarcodeWriter.DefaultCharacterEncoding設定でも発生します。 UTF-8デフォルトではより有用なメッセージを提供します:

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下では、同じ組み合わせが低レベルのネイティブエンコーダーエラーとして表面化します。

ペイロードはしばしばアプリケーションのコントロール下にない場合があります: ユーザー入力、上流フィード、サプライヤーカタログからの製品名。 防御的ラッパーでそれをカバーします:

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

ここでのフォールバックはそのシンボルをAutoに切り替えます。ECIを認識するスキャナーに届く正しいバーコードは、バーコードなしより優れるという考えからです。 正しい回復はデプロイメントに依存します: スキャナーが本当にECIを読み取ることができない場所では、手動で処理するためにレコードを拒否するほうが安全です。

タイプはエラーハンドリングとデバッグガイドにも記載されており、特定の原因は含まず、例外ファミリーをカバーしています。


モードをどのように選択するか?

もう一度すべてのシンボルにタグを付ける方法は?

スタートアップで1行:

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 は、すべての2Dフォーマットを常時タグ付けされた動作に戻し、同じ入力に対して2026.8.6およびそれ以前とバイト同一の出力を生成します。 これは、下流システムがタグ付き出力に対して構築されたアプリケーション、すべてのシンボルで明示的なエンコーディング宣言を必要とする標準、あるいはその効果が評価される間に変化を延期する方法として、適切な選択です。

逆の場合も名前を付ける価値があります。 アップグレードした後、シンボルが小さくなり喜んでいるアプリケーションは何の行動も必要なく、Autoがすでにデフォルトです。

どのモードがどの状況に適しているか?

シナリオごとに推奨されるECIモードと各モードが設定される場所

シナリオECIモード設定する場所
一般用途の生成、混合コンテンツAuto何もすることはありません; それがデフォルトです
ECIで失敗する古いスキャナー群OffDefaultEciModeをスタートアップで
標準はすべてのシンボルでの明示的なエンコーディングを要求しますForceUtf8DefaultEciModeをスタートアップで
正常な出力中の1つのコンプライアンスシンボルForceUtf8コールごとに、データマトリックスのみ
ペイロード内容がASCIIである保証なしAuto、またはOffをcatchと共に使用どちらでも、例外処理付き

どこに進むべきか

ここで説明されている動作は、3つの値を持つ1つの設定であり、ほとんどのアプリケーションはそれを一度設定し、再訪することはありません。 注意して行う価値のある2つの決定は、スキャナー群がECIを理解するかどうか、下流標準がすべてのシンボルでの宣言を要求するかどうかです。

どのバーコードフォーマットがUnicodeコンテンツを最初にサポートするかについては、UTF-8とUnicodeバーコードの書き方ハウツーを参照してください。これはフォーマットレベルのUnicodeサポートをカバーし、ECIの詳細についてはこちらにリンクしています。 2Dフォーマット自体を生成するには、2Dバーコードの作成ハウツーがDataMatrix、QR、Aztec、PDF417の生成をカバーしています。 完全なクラスのドキュメントは、IronBarcode APIリファレンスにあります。

Ahmadは、C#、Python、およびウェブ技術に強い基盤を持つフルスタック開発者です。彼はスケーラブルなソフトウェアソリューションの構築に深い関心を持ち、デザインと機能が実際のアプリケーションでどのように融合するかを探求することを楽しんでいます。

もっと読む

準備はできましたか?

NuGetダウンロード数 2,564,559バージョン:2026.11ちょうどリリースされました