바코드 작업에서 오류 처리 및 디버그 하는 방법 C#

IronBarcode 예외를 포착하고 해석하는 방법?

IronBarcode 예외는 가장 구체적인 것에서 가장 일반적인 것으로 잡아 처리합니다. IronBarCode.Exceptions 네임스페이스는 고유한 실패 모드에 매핑되는 11 종류의 예외 유형을 정의합니다. 가장 좁은 유형에서 가장 넓은 유형으로 캐치 블록을 정렬하면 복구 논리에서 정확한 제어가 가능합니다.

우리는 가장 조치 가능한 예외(파일, PDF 비밀번호, 인코딩)에서 기본 유형으로 캐치 블록을 정렬합니다. 중첩을 깊게 하지 않고 겹치는 유형을 라우팅할 수 있도록 하는 when 절을 가진 예외 필터:

//:path=/static-assets/barcode/content-code-examples/how-to/detailed-error-messages/exception-hierarchy.cs
using IronBarCode;
using IronBarCode.Exceptions;

string filePath = "warehouse-labels.pdf";

try
{
    BarcodeResults results = BarcodeReader.Read(filePath);
    foreach (BarcodeResult result in results)
    {
        Console.WriteLine($"[{result.BarcodeType}] {result.Value} (Confidence: {result.Confidence})");
    }
}
catch (IronBarCodePdfPasswordException ex)
{
    Console.Error.WriteLine($"PDF requires password: {filePath} — {ex.Message}");
}
catch (IronBarCodeFileException ex)
{
    Console.Error.WriteLine($"Cannot read file: {filePath} — {ex.Message}");
}
catch (IronBarCodeNativeException ex) when (ex.Message.Contains("DLL"))
{
    Console.Error.WriteLine($"Missing native dependency: {ex.Message}");
}
catch (IronBarCodeException ex)
{
    Console.Error.WriteLine($"IronBarcode error: {ex.GetType().Name} — {ex.Message}");
}

//:path=/static-assets/barcode/content-code-examples/how-to/detailed-error-messages/exception-hierarchy.cs
using IronBarCode;
using IronBarCode.Exceptions;

string filePath = "warehouse-labels.pdf";

try
{
    BarcodeResults results = BarcodeReader.Read(filePath);
    foreach (BarcodeResult result in results)
    {
        Console.WriteLine($"[{result.BarcodeType}] {result.Value} (Confidence: {result.Confidence})");
    }
}
catch (IronBarCodePdfPasswordException ex)
{
    Console.Error.WriteLine($"PDF requires password: {filePath} — {ex.Message}");
}
catch (IronBarCodeFileException ex)
{
    Console.Error.WriteLine($"Cannot read file: {filePath} — {ex.Message}");
}
catch (IronBarCodeNativeException ex) when (ex.Message.Contains("DLL"))
{
    Console.Error.WriteLine($"Missing native dependency: {ex.Message}");
}
catch (IronBarCodeException ex)
{
    Console.Error.WriteLine($"IronBarcode error: {ex.GetType().Name} — {ex.Message}");
}

when (ex.Message.Contains("DLL")) 필터는 IronBarCodeNativeException에서 의존성 누락 오류를 특정 핸들러로 라우팅하는 데 사용하며, 다른 네이티브 예외는 소비하지 않습니다. 이 패턴은 플랫폼별 패키지가 없을 수 있는 Docker 배포에 특히 유용합니다.

라이선스 키가 잘못되었거나 누락된 경우 IronSoftware.Exceptions.LicensingException가 별도로 throw됩니다. 개별 읽기/쓰기 호출보다 애플리케이션 시작 시 이를 포착하는 것이 좋습니다.

실패한 읽기에서 진단 세부 정보를 추출하는 방법?

결과가 없는 읽기 작업은 예외가 아닙니다 — 빈 BarcodeResults 컬렉션입니다. 입력 매개변수, 구성한 옵션 및 일부 반환된 결과를 검토하여 진단 컨텍스트를 추출합니다.

BarcodeResult 객체는 사후 분석에 유용한 몇 가지 속성을 노출합니다: BarcodeType, Value, Confidence, Y 좌표, PageNumber, BarcodeImage 및 BinaryValue. 결과가 존재하지만 예상치 못한 경우, Confidence 속성은 조사할 첫 번째 값입니다.

//:path=/static-assets/barcode/content-code-examples/how-to/detailed-error-messages/diagnostic-logging.cs
using IronBarCode;

string filePath = "scanned-invoice.png";

var options = new BarcodeReaderOptions
{
    ExpectBarcodeTypes = BarcodeEncoding.Code128 | BarcodeEncoding.QRCode,
    Speed = ReadingSpeed.Detailed,
    ExpectMultipleBarcodes = true
};

BarcodeResults results = BarcodeReader.Read(filePath, options);

if (results == null || results.Count == 0)
{
    // No barcodes detected — log the full diagnostic context
    Console.Error.WriteLine($"[WARN] No barcodes found in: {filePath}");
    Console.Error.WriteLine($"  ExpectedTypes: {options.ExpectBarcodeTypes}");
    Console.Error.WriteLine($"  Speed: {options.Speed}");
    Console.Error.WriteLine($"  Action: Retry with ReadingSpeed.ExtremeDetail or broaden ExpectBarcodeTypes");
}
else
{
    foreach (BarcodeResult result in results)
    {
        // Flag low-confidence reads for manual review
        string flag = result.Confidence < 80 ? " ⚠ LOW_CONFIDENCE" : "";
        Console.WriteLine($"[{result.BarcodeType}] {result.Value} "
            + $"(Confidence: {result.Confidence}%, Page: {result.PageNumber}, "
            + $"Position: {result.X},{result.Y}){flag}");
    }
}

//:path=/static-assets/barcode/content-code-examples/how-to/detailed-error-messages/diagnostic-logging.cs
using IronBarCode;

string filePath = "scanned-invoice.png";

var options = new BarcodeReaderOptions
{
    ExpectBarcodeTypes = BarcodeEncoding.Code128 | BarcodeEncoding.QRCode,
    Speed = ReadingSpeed.Detailed,
    ExpectMultipleBarcodes = true
};

BarcodeResults results = BarcodeReader.Read(filePath, options);

if (results == null || results.Count == 0)
{
    // No barcodes detected — log the full diagnostic context
    Console.Error.WriteLine($"[WARN] No barcodes found in: {filePath}");
    Console.Error.WriteLine($"  ExpectedTypes: {options.ExpectBarcodeTypes}");
    Console.Error.WriteLine($"  Speed: {options.Speed}");
    Console.Error.WriteLine($"  Action: Retry with ReadingSpeed.ExtremeDetail or broaden ExpectBarcodeTypes");
}
else
{
    foreach (BarcodeResult result in results)
    {
        // Flag low-confidence reads for manual review
        string flag = result.Confidence < 80 ? " ⚠ LOW_CONFIDENCE" : "";
        Console.WriteLine($"[{result.BarcodeType}] {result.Value} "
            + $"(Confidence: {result.Confidence}%, Page: {result.PageNumber}, "
            + $"Position: {result.X},{result.Y}){flag}");
    }
}

진단 중 흔히 나타나는 세 가지 패턴이 있습니다. 먼저 ExpectBarcodeTypes 설정이 좁은 빈 결과는 실제 바코드가 다른 심볼로지임을 의미하며, BarcodeEncoding.All로 확장하면 이를 확인할 수 있습니다. 두 번째, 70% 미만의 저신뢰도 읽기는 흔히 이미지 품질 부족을 나타내며, 재시도하기 전에 이미지 필터(대조, 선명화, 적응형 임계값)를 적용하면 이를 해결할 수 있습니다. BarcodeReaderOptions의 RemoveFalsePositive 옵션을 토글하여 노이즈가 있는 배경에서 유령 판독을 제거할 수 있습니다.

바코드 작업에 대해 자세한 로깅을 활성화하는 방법?

IronBarcode는 공유 IronSoftware.Logger 클래스를 통해 내장된 로깅 API를 제공합니다. 바코드 작업 전에 로깅 모드와 파일 경로를 설정하여 라이브러리의 읽기 및 쓰기 파이프라인에서 내부 진단 출력을 캡처합니다.

//:path=/static-assets/barcode/content-code-examples/how-to/detailed-error-messages/enable-logging.cs
using IronBarCode;

// Enable IronBarcode's built-in logging — set BEFORE any read/write calls
IronSoftware.Logger.LoggingMode = IronSoftware.Logger.LoggingModes.All;
IronSoftware.Logger.LogFilePath = "ironbarcode-debug.log";

// All subsequent operations will write diagnostic output to the log file
var options = new BarcodeReaderOptions
{
    Speed = ReadingSpeed.Detailed,
    ExpectBarcodeTypes = BarcodeEncoding.All
};

BarcodeResults results = BarcodeReader.Read("problem-scan.tiff", options);
Console.WriteLine($"Read complete. Results: {results.Count}. See ironbarcode-debug.log for details.");

//:path=/static-assets/barcode/content-code-examples/how-to/detailed-error-messages/enable-logging.cs
using IronBarCode;

// Enable IronBarcode's built-in logging — set BEFORE any read/write calls
IronSoftware.Logger.LoggingMode = IronSoftware.Logger.LoggingModes.All;
IronSoftware.Logger.LogFilePath = "ironbarcode-debug.log";

// All subsequent operations will write diagnostic output to the log file
var options = new BarcodeReaderOptions
{
    Speed = ReadingSpeed.Detailed,
    ExpectBarcodeTypes = BarcodeEncoding.All
};

BarcodeResults results = BarcodeReader.Read("problem-scan.tiff", options);
Console.WriteLine($"Read complete. Results: {results.Count}. See ironbarcode-debug.log for details.");

IronSoftware.Logger.LoggingModes.All는 디버그 출력과 파일 수준 로깅을 모두 캡처합니다. 로그 파일은 내부 처리 단계 — 이미지 전처리 단계, 포맷 감지 시도 및 네이티브 상호 운용 호출 — 를 기록하는데, 이러한 단계는 공개 API로만은 보이지 않습니다.

이미 구조화된 로깅 프레임워크(Serilog, NLog, Microsoft.Extensions.Logging)를 사용하는 프로덕션 파이프라인의 경우, IronBarcode 작업을 구조화된 JSON 항목을 내부 로그 파일과 함께 기록하는 미들웨어 레이어로 래핑하는 것을 권장합니다. 이 내장 로거는 지원 에스컬레이션에 유용한 일반 텍스트 진단을 작성합니다; 구조화된 래퍼는 관측 가능성 스택에서 쿼리 가능한 필드를 제공합니다.

//:path=/static-assets/barcode/content-code-examples/how-to/detailed-error-messages/structured-wrapper.cs
using IronBarCode;
using System.Diagnostics;

// Lightweight wrapper for structured observability
BarcodeResults ReadWithDiagnostics(string filePath, BarcodeReaderOptions options)
{
    var sw = Stopwatch.StartNew();
    try
    {
        BarcodeResults results = BarcodeReader.Read(filePath, options);
        sw.Stop();
        Console.WriteLine($"{{\"file\":\"{filePath}\",\"status\":\"ok\","
            + $"\"count\":{results.Count},\"elapsed_ms\":{sw.ElapsedMilliseconds}}}");
        return results;
    }
    catch (Exception ex)
    {
        sw.Stop();
        Console.Error.WriteLine($"{{\"file\":\"{filePath}\",\"status\":\"error\","
            + $"\"exception\":\"{ex.GetType().Name}\",\"message\":\"{ex.Message}\","
            + $"\"elapsed_ms\":{sw.ElapsedMilliseconds}}}");
        throw;
    }
}

//:path=/static-assets/barcode/content-code-examples/how-to/detailed-error-messages/structured-wrapper.cs
using IronBarCode;
using System.Diagnostics;

// Lightweight wrapper for structured observability
BarcodeResults ReadWithDiagnostics(string filePath, BarcodeReaderOptions options)
{
    var sw = Stopwatch.StartNew();
    try
    {
        BarcodeResults results = BarcodeReader.Read(filePath, options);
        sw.Stop();
        Console.WriteLine($"{{\"file\":\"{filePath}\",\"status\":\"ok\","
            + $"\"count\":{results.Count},\"elapsed_ms\":{sw.ElapsedMilliseconds}}}");
        return results;
    }
    catch (Exception ex)
    {
        sw.Stop();
        Console.Error.WriteLine($"{{\"file\":\"{filePath}\",\"status\":\"error\","
            + $"\"exception\":\"{ex.GetType().Name}\",\"message\":\"{ex.Message}\","
            + $"\"elapsed_ms\":{sw.ElapsedMilliseconds}}}");
        throw;
    }
}

구조화된 출력은 로그 집계 도구와 직접 통합됩니다 — 컨테이너 배포에서 Fluentd, Datadog 또는 CloudWatch로 stdout를 연결합니다. 경과 시간 필드는 SLA 위반이 되기 전에 성능 퇴행을 나타냅니다.

일괄 바코드 처리 디버그 방법

각 읽기를 자신의 try-catch 블록에서 분리하고 파일 결과를 기록하며 마지막에 집계 요약을 생성하여 N개의 파일을 처리합니다. 파이프라인은 첫 번째 오류에서 중단하지 않고 실패를 통해 계속 진행합니다.

//:path=/static-assets/barcode/content-code-examples/how-to/detailed-error-messages/batch-processing.cs
using IronBarCode;
using IronBarCode.Exceptions;
using System.Diagnostics;

// Enable built-in logging for the entire batch run
IronSoftware.Logger.LoggingMode = IronSoftware.Logger.LoggingModes.All;
IronSoftware.Logger.LogFilePath = "batch-run.log";

string[] files = Directory.GetFiles("scans/", "*.*", SearchOption.TopDirectoryOnly);

var options = new BarcodeReaderOptions
{
    Speed = ReadingSpeed.Balanced,
    ExpectBarcodeTypes = BarcodeEncoding.Code128 | BarcodeEncoding.QRCode,
    ExpectMultipleBarcodes = true
};

int successCount = 0;
int failCount = 0;
int emptyCount = 0;
var errors = new List<(string File, string Error)>();
var sw = Stopwatch.StartNew();

foreach (string file in files)
{
    try
    {
        BarcodeResults results = BarcodeReader.Read(file, options);

        if (results == null || results.Count == 0)
        {
            emptyCount++;
            errors.Add((file, "No barcodes detected"));
            continue;
        }

        foreach (BarcodeResult result in results)
        {
            Console.WriteLine($"{Path.GetFileName(file)} | {result.BarcodeType} | {result.Value} | {result.Confidence}%");
        }
        successCount++;
    }
    catch (IronBarCodePdfPasswordException)
    {
        failCount++;
        errors.Add((file, "Password-protected PDF"));
    }
    catch (IronBarCodeFileException ex)
    {
        failCount++;
        errors.Add((file, $"File error: {ex.Message}"));
    }
    catch (IronBarCodeException ex)
    {
        failCount++;
        errors.Add((file, $"{ex.GetType().Name}: {ex.Message}"));
    }
    catch (Exception ex)
    {
        failCount++;
        errors.Add((file, $"Unexpected: {ex.GetType().Name}: {ex.Message}"));
    }
}

sw.Stop();

// Summary report
Console.WriteLine("\n--- Batch Summary ---");
Console.WriteLine($"Total files:    {files.Length}");
Console.WriteLine($"Success:        {successCount}");
Console.WriteLine($"Empty reads:    {emptyCount}");
Console.WriteLine($"Failures:       {failCount}");
Console.WriteLine($"Elapsed:        {sw.Elapsed.TotalSeconds:F1}s");

if (errors.Any())
{
    Console.WriteLine("\n--- Error Details ---");
    foreach (var (errorFile, errorMsg) in errors)
    {
        Console.Error.WriteLine($"  {Path.GetFileName(errorFile)}: {errorMsg}");
    }
}

//:path=/static-assets/barcode/content-code-examples/how-to/detailed-error-messages/batch-processing.cs
using IronBarCode;
using IronBarCode.Exceptions;
using System.Diagnostics;

// Enable built-in logging for the entire batch run
IronSoftware.Logger.LoggingMode = IronSoftware.Logger.LoggingModes.All;
IronSoftware.Logger.LogFilePath = "batch-run.log";

string[] files = Directory.GetFiles("scans/", "*.*", SearchOption.TopDirectoryOnly);

var options = new BarcodeReaderOptions
{
    Speed = ReadingSpeed.Balanced,
    ExpectBarcodeTypes = BarcodeEncoding.Code128 | BarcodeEncoding.QRCode,
    ExpectMultipleBarcodes = true
};

int successCount = 0;
int failCount = 0;
int emptyCount = 0;
var errors = new List<(string File, string Error)>();
var sw = Stopwatch.StartNew();

foreach (string file in files)
{
    try
    {
        BarcodeResults results = BarcodeReader.Read(file, options);

        if (results == null || results.Count == 0)
        {
            emptyCount++;
            errors.Add((file, "No barcodes detected"));
            continue;
        }

        foreach (BarcodeResult result in results)
        {
            Console.WriteLine($"{Path.GetFileName(file)} | {result.BarcodeType} | {result.Value} | {result.Confidence}%");
        }
        successCount++;
    }
    catch (IronBarCodePdfPasswordException)
    {
        failCount++;
        errors.Add((file, "Password-protected PDF"));
    }
    catch (IronBarCodeFileException ex)
    {
        failCount++;
        errors.Add((file, $"File error: {ex.Message}"));
    }
    catch (IronBarCodeException ex)
    {
        failCount++;
        errors.Add((file, $"{ex.GetType().Name}: {ex.Message}"));
    }
    catch (Exception ex)
    {
        failCount++;
        errors.Add((file, $"Unexpected: {ex.GetType().Name}: {ex.Message}"));
    }
}

sw.Stop();

// Summary report
Console.WriteLine("\n--- Batch Summary ---");
Console.WriteLine($"Total files:    {files.Length}");
Console.WriteLine($"Success:        {successCount}");
Console.WriteLine($"Empty reads:    {emptyCount}");
Console.WriteLine($"Failures:       {failCount}");
Console.WriteLine($"Elapsed:        {sw.Elapsed.TotalSeconds:F1}s");

if (errors.Any())
{
    Console.WriteLine("\n--- Error Details ---");
    foreach (var (errorFile, errorMsg) in errors)
    {
        Console.Error.WriteLine($"  {Path.GetFileName(errorFile)}: {errorMsg}");
    }
}

이 패턴은 세 가지 결과 범주를 구별합니다: 성공(바코드가 발견되고 디코딩됨), 비어 있음(파일이 성공적으로 읽혔지만 바코드가 감지되지 않음), 실패(예외 발생). 이 세 가지 구분은 중요합니다. 공간 읽기와 심각한 실패에는 다른 수정이 필요합니다 — 공간 읽기는 더 넓은 형식 설정 또는 이미지 수정 필터를 필요로 할 수 있으며, 실패는 인프라 문제(누락된 파일, 잠긴 리소스, 누락된 네이티브 DLL)를 가리킵니다.

errors 목록은 사후 분석을 위한 파일 별 문맥을 보존합니다. CI/CD 파이프라인에서 이 출력을 구문 분석하여 종료 코드를 설정할 수 있습니다 — 모든 성공 시에는 0, failCount > 0인 경우 비 0 — 또는 오류 상세 정보를 경보 시스템에 피드할 수 있습니다.

더 높은 처리량을 위해 options.Multithreaded = true을 설정하고 options.MaxParallelThreads을 사용 가능한 CPU 코어에 맞게 조정하여 병렬 처리를 활성화할 수 있습니다. 파일별 분리 패턴은 동일하게 유지됩니다; 오류 목록에 대한 스레드 안전한 컬렉션과 함께 Parallel.ForEach에서 병렬 반복을 래핑합니다.

내 다음 단계는 무엇인가요?

IronBarcode 예외 계층 구조를 11개의 타입화된 예외와 BarcodeResult 속성에서의 진단 추출, IronSoftware.Logger을 통한 내장 로깅, 파일별 오류 격리를 가진 프로덕션 준비 배치 처리 패턴과 함께 다루었습니다.

추가 읽기를 위해 이 리소스를 탐색하세요:

• IronBarcode 튜토리얼 — 바코드 읽기엔드 투 엔드 읽기 안내.
• 시끄러운 이미지에서 환상적인 읽기를 줄이기 위한 오탐 방지.
• 읽기 정확도를 향상시키는 필터에 대한 이미지 수정 방법.
• 올바른 네이티브 종속성과 함께 컨테이너화된 배포에 대한 Docker 설정 가이드.
• 전체 구성 문서를 위한 BarcodeReaderOptions API 참조.
• 버전별 수정 및 기능 추가를 위한 IronBarcode 변경 로그.

라이브 환경에서 모든 기능을 테스트할 수 있는 무료 체험판 라이선스를 얻으세요, 또는 파이프라인이 생산 준비가 되었을 때 라이선스 옵션을 보세요.