C#에서 2D 바코드의 UTF-8 ECI 태그 제어 방법

아흐마드 소하일
Ahmad Sohail
업데이트됨: 2026년 9월 9일

예상과 다른 크기의 2D 바코드, 이전에 읽혔던 기호를 거부하는 구형 스캐너, 모든 기호가 인코딩을 선언해야 한다는 표준은 모두 동일한 질문으로 귀결됩니다: 바코드에 UTF-8 ECI (확장 채널 해석) 헤더가 포함되어 있습니까?

그 헤더는 스캐너가 페이로드를 UTF-8로 해석하도록 지시하며, 이는 ASCII 외부의 중국어, 아랍어, 태국어나 기타 콘텐츠에 중요합니다. 무료가 아닙니다. 헤더는 코드워드를 소비하며, 페이로드가 이미 크기 경계에 가까운 경우 더 큰 기호로 흘러들 수 있으며, ECI 이전에 만들어진 스캐너는 그 기호를 거부합니다. 따라서 IronBarcode는 데이터에 비ASCII 문자가 포함된 경우에만 헤더를 작성하며, EciMode 설정으로 해당 결정을 무시할 수 있습니다.

유의 사항: IronBarcode 2026.9.2 이상이 필요합니다. API는 2026.8.6 이하에서는 존재하지 않으며, 호출 시 런타임 오류 대신 컴파일 오류가 발생합니다.
빠른 시작: 모든 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 부품 번호에서 DataMatrix를 생성하고, 기호에 헤더가 없습니다. 동일한 메서드에 움라우트가 포함된 페이로드를 전달하면, 그 값이 필요하기 때문에 헤더가 나타납니다. 호출 시의 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");

위의 세 기호는 페이로드와 모드가 제공되었는지를 제외하고는 차이가 없습니다. 아래 이미지는 고정 모듈 크기로 그려져 있어, 인쇄된 라벨에서 크기가 서로 다르게 나타나는 것과 같이 기호가 크기에서 다릅니다.

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에 더 이상 맞지 않기 때문입니다. 페이로드가 이미 크기 경계에 가까울 때만 헤더가 기호를 크게 만듭니다. 주어진 값에 대해 이러한 사실이 맞는지는 문자열 자체에서는 보이지 않습니다.

세 가지 ECI 모드는 무엇입니까?

  • Auto: 데이터가 비ASCII 문자를 포함할 때만 UTF-8 ECI 헤더를 작성합니다. 이는 기본값이며, 순수 ASCII 페이로드에 대해 가장 작은 기호를 생성합니다.
  • ForceUtf8: 항상 헤더를 작성하며, 순수 ASCII도 포함합니다. 엄격한 표준 준수나 모든 기호가 인코딩을 선언해야 하는 경우에 사용하십시오.
  • Off: 헤더를 절대 작성하지 않습니다. 데이터가 ASCII나 Latin-1로 알려져 있고 디코더가 ECI를 이해하지 않는 경우에만 사용하십시오.
유의 사항: ECI는 2D 형식에만 적용됩니다. EciMode은(는) Code 128, EAN 또는 UPC와 같은 1D 바코드에 영향을 미치지 않습니다.

ECI 모드를 어떻게 설정합니까?

응용 프로그램 전반에 하나의 정책을 어떻게 적용합니까?

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

단일 DataMatrix의 모드를 어떻게 무시합니까?

통화별의 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은 무엇이 제어합니까?

이 세 가지 형식에는 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 코드와 DataMatrix가 동일한 실행에서 다른 ECI 동작이 필요할 때, DataMatrix는 호출별 인수를 사용하고 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를 읽을 수 없는 경우, 수동 처리를 위해 레코드를 거부하는 것이 더 안전한 선택입니다.

유형은 오류 처리 및 디버깅 가이드에도 나열되어 있으며, 이 특정 원인을 제외하고 예외 계열을 다룹니다.


모드를 어떻게 선택합니까?

모든 기호를 다시 태그하는 방법

한 줄, 시작 시:

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 시작 시
기타 정상 출력 사이의 준수 기호 하나ForceUtf8통화 별, DataMatrix만
페이로드 콘텐츠가 ASCII가 보장되지 않음Auto, 또는 예외와 함께 Off둘 다, 예외 처리 포함

다음으로 어디로 가야 합니까?

여기서 설명한 동작은 세 가지 값 중 하나의 설정이며, 대부분의 응용 프로그램은 이를 한 번 설정하고 다시 방문하지 않을 것입니다. 고의로 설정할 가치가 있는 두 가지 결정은 스캐너 무리가 ECI를 이해하는지, 그리고 다운스트림 표준이 모든 기호에 대한 선언을 요구하는지 여부입니다.

처음으로 유니코드 콘텐츠를 지원하는 바코드 형식을 보려면, 형식 수준 유니코드 지원을 다루고 ECI 세부사항에 대한 링크가 있는 Write UTF-8 and Unicode Barcodes 활용 방법을 참조하십시오. 2D 형식 자체를 생성하려면, 2D 바코드 생성 사용법은 DataMatrix, QR, Aztec 및 PDF417 생성을 다룹니다. 전체 클래스 문서는 IronBarcode API 참조에 있습니다.

아흐마드는 C#, Python 및 웹 기술에 탄탄한 기반을 갖춘 풀스택 개발자입니다. 그는 확장 가능한 소프트웨어 솔루션 구축에 깊은 관심을 가지고 있으며, 실제 응용 프로그램에서 디자인과 기능이 어떻게 조화를 이루는지 탐구하는 것을 즐깁니다.

더 읽기

시작할 준비 되셨나요?

NuGet 다운로드 수 2,564,559버전:2026.11방금 출시