IronBarcode C#에서 BarcodeReader.Read까지 BarcodeResults 컬렉션으로 스캔 결과를 반환합니다. 이 메서드는 입력 이미지를 인식할 수 없는 경우 null을 반환하고, 바코드가 감지되지 않은 경우 빈 컬렉션을 반환합니다. BarcodeWriter.CreateBarcode는 입력이 null이거나 비어 있거나 형식이 잘못된 경우 예외를 발생시킵니다.
카메라 영상, 문서 업로드, 창고 스캐너와 같은 실제 스캔 소스는 항상 판독 가능한 바코드를 제공하지 않을 수 있습니다. 결과 속성에 접근하거나 컬렉션을 순회할 때 null 또는 빈 값을 확인하지 않으면 런타임에 NullReferenceException 오류가 발생할 수 있습니다. 쓰기 API에 유효하지 않은 문자열을 전달하면 ArgumentException이 발생할 수 있습니다. 읽기 및 쓰기 작업 모두에서 가드 절을 사용하면 실제 운영 환경에서 이러한 예외를 방지하는 데 도움이 됩니다.
이 가이드에서는 가드 절, 신뢰도 필터링 및 재사용 가능한 유효성 검사기 패턴을 사용하여 IronBarcode 읽기 및 쓰기 작업에서 null 및 빈 결과를 처리하는 방법을 설명합니다.
빠른 시작: 바코드 작업에서 널 결과 처리
IronBarcode의 가드 패턴을 사용하여 결과 속성에 접근하기 전에 BarcodeResults 컬렉션을 안전하게 검사하세요. 지금 바로 이 간단한 읽기 및 확인 절차를 시작해 보세요.
NuGet 패키지 관리자를 사용하여 https://www.nuget.org/packages/BarCode 설치하기
PM > Install-Package BarCode
다음 코드 조각을 복사하여 실행하세요.
using IronBarCode;
BarcodeResults results = BarcodeReader.Read("label.png");
// Guard: null or empty
if (results is null || results.Count == 0)
{
Console.WriteLine("No barcodes detected.");
return;
}
Console.WriteLine(results.First().Value);
using IronBarCode;
// BarcodeReader.Read() returns a BarcodeResults collection, not a single result
BarcodeResults results = BarcodeReader.Read("shipping-label.png");
// Null check: image was not recognized as a valid image source
// Empty check: image was valid but contained no detectable barcodes
if (results is null || results.Count == 0)
{
// Log, return a default, or throw a domain-specific exception
Console.WriteLine("No barcodes found in the input image.");
return;
}
// Collection is safe to iterate; each BarcodeResult holds one decoded barcode
foreach (BarcodeResult result in results)
{
// Guard individual result properties; partial scans or severely
// damaged barcodes can produce results where .Value is empty or whitespace
if (string.IsNullOrWhiteSpace(result.Value))
{
Console.WriteLine($"Empty value detected for {result.BarcodeType}");
continue;
}
// BarcodeType identifies the symbology (Code128, QRCode, EAN8, etc.)
Console.WriteLine($"Type: {result.BarcodeType}, Value: {result.Value}");
}
Imports IronBarCode
' BarcodeReader.Read() returns a BarcodeResults collection, not a single result
Dim results As BarcodeResults = BarcodeReader.Read("shipping-label.png")
' Null check: image was not recognized as a valid image source
' Empty check: image was valid but contained no detectable barcodes
If results Is Nothing OrElse results.Count = 0 Then
' Log, return a default, or throw a domain-specific exception
Console.WriteLine("No barcodes found in the input image.")
Return
End If
' Collection is safe to iterate; each BarcodeResult holds one decoded barcode
For Each result As BarcodeResult In results
' Guard individual result properties; partial scans or severely
' damaged barcodes can produce results where .Value is empty or whitespace
If String.IsNullOrWhiteSpace(result.Value) Then
Console.WriteLine($"Empty value detected for {result.BarcodeType}")
Continue For
End If
' BarcodeType identifies the symbology (Code128, QRCode, EAN8, etc.)
Console.WriteLine($"Type: {result.BarcodeType}, Value: {result.Value}")
Next
$vbLabelText $csharpLabel
각 BarcodeResult는 디코딩된 바코드 내용을 반환하는 Value 및 Text 문자열 속성을 제공합니다. 바코드가 심하게 손상되었거나 스캔이 부분적으로만 이루어진 경우, 값이 비어 있거나 공백으로 표시될 수 있습니다. 각 결과에 string.IsNullOrWhiteSpace를 추가하여 빈 값이 하위 시스템으로 전달되는 것을 방지하십시오.
BarcodeReaderOptions에는 결과 수집에 도달하기 전에 품질이 낮은 리드를 제거하는 ConfidenceThreshold 속성(0.0~1.0)도 있습니다.
using IronBarCode;
// ConfidenceThreshold filters low-quality reads before they enter the
// BarcodeResults collection. Reads below the threshold are discarded
// during scanning, not after, so no post-filtering of the collection is needed.
var options = new BarcodeReaderOptions
{
ConfidenceThreshold = 0.7 // range 0.0 to 1.0; lower values accept weaker signals
};
BarcodeResults results = BarcodeReader.Read("shipping-label.png", options);
// Still check for null and empty even with a threshold applied;
// an image with no barcodes returns an empty collection, not null
if (results is null || results.Count == 0)
{
Console.WriteLine("No barcodes met the confidence threshold.");
return;
}
foreach (var result in results)
Console.WriteLine($"Type: {result.BarcodeType}, Value: {result.Value}");
Imports IronBarCode
' ConfidenceThreshold filters low-quality reads before they enter the
' BarcodeResults collection. Reads below the threshold are discarded
' during scanning, not after, so no post-filtering of the collection is needed.
Dim options As New BarcodeReaderOptions With {
.ConfidenceThreshold = 0.7 ' range 0.0 to 1.0; lower values accept weaker signals
}
Dim results As BarcodeResults = BarcodeReader.Read("shipping-label.png", options)
' Still check for null and empty even with a threshold applied;
' an image with no barcodes returns an empty collection, not null
If results Is Nothing OrElse results.Count = 0 Then
Console.WriteLine("No barcodes met the confidence threshold.")
Return
End If
For Each result In results
Console.WriteLine($"Type: {result.BarcodeType}, Value: {result.Value}")
Next
$vbLabelText $csharpLabel
바코드 쓰기에 널 안전 패턴을 적용하는 방법?
BarcodeWriter.CreateBarcode는 문자열 값과 BarcodeWriterEncoding 또는 BarcodeEncoding 열거형 값을 받습니다. null 또는 빈 문자열을 전달하면 즉시 예외가 발생합니다. 형식 제약 조건도 적용됩니다. EAN-8은 7~8자리 숫자를 허용하고, UPC-A는 11~12자리 숫자를 허용하며, Code 128은 문자 수 제한이 있습니다. 함수 호출 전에 입력값을 검증하면 이러한 예외가 인코딩 단계에 포함되지 않습니다.
using IronBarCode;
// Input may arrive from user input, a database, or an API response
string inputValue = GetValueFromUserOrDatabase(); // Could be null
// Guard: null, empty, or whitespace input cannot produce a valid barcode
if (string.IsNullOrWhiteSpace(inputValue))
{
Console.WriteLine("Cannot generate barcode: input value is null or empty.");
return;
}
// Guard: format-specific constraints must be satisfied before encoding
// EAN-8 accepts exactly 7 or 8 numeric digits (the 8th is the check digit)
BarcodeWriterEncoding encoding = BarcodeWriterEncoding.EAN8;
if (encoding == BarcodeWriterEncoding.EAN8 && !System.Text.RegularExpressions.Regex.IsMatch(inputValue, @"^\d{7,8}$"))
{
Console.WriteLine("EAN-8 requires exactly 7 or 8 numeric digits.");
return;
}
// Input is validated; CreateBarcode will not throw for null or format mismatch
GeneratedBarcode barcode = BarcodeWriter.CreateBarcode(inputValue, encoding);
barcode.SaveAsPng("output-barcode.png");
Imports IronBarCode
' Input may arrive from user input, a database, or an API response
Dim inputValue As String = GetValueFromUserOrDatabase() ' Could be Nothing
' Guard: null, empty, or whitespace input cannot produce a valid barcode
If String.IsNullOrWhiteSpace(inputValue) Then
Console.WriteLine("Cannot generate barcode: input value is null or empty.")
Return
End If
' Guard: format-specific constraints must be satisfied before encoding
' EAN-8 accepts exactly 7 or 8 numeric digits (the 8th is the check digit)
Dim encoding As BarcodeWriterEncoding = BarcodeWriterEncoding.EAN8
If encoding = BarcodeWriterEncoding.EAN8 AndAlso Not System.Text.RegularExpressions.Regex.IsMatch(inputValue, "^\d{7,8}$") Then
Console.WriteLine("EAN-8 requires exactly 7 or 8 numeric digits.")
Return
End If
' Input is validated; CreateBarcode will not throw for null or format mismatch
Dim barcode As GeneratedBarcode = BarcodeWriter.CreateBarcode(inputValue, encoding)
barcode.SaveAsPng("output-barcode.png")
$vbLabelText $csharpLabel
산출
유효한 7자리 입력(1234567)을 입력하면 스캔 가능한 EAN-8 바코드가 생성됩니다. null, 빈 값 또는 숫자가 아닌 입력은 가드 절에 의해 포착되어 인코딩 단계에 도달하지 않습니다.
쓰기 API는 자체적인 내부 유효성 검사도 수행합니다. 체크섬을 확인하고, 길이 제약 조건을 검증하며, 선택한 인코딩에 유효하지 않은 문자를 거부합니다. 위의 가드 절은 문제를 더 일찍 포착하여 호출자가 오류 메시지와 복구 경로를 제어할 수 있도록 합니다. 지원되는 인코딩 및 제약 조건의 전체 목록은 바코드 생성 방법 및 데이터에서 바코드 생성 가이드를 참조하세요.
후속 처리 전 결과를 검증하는 방법?
바코드 데이터가 다른 시스템(데이터베이스 쓰기, API 호출, 라벨 프린터)으로 전송될 때, 데이터를 전달하기 전에 결과 개수, 값 무결성 및 유형 검사를 하나의 재사용 가능한 메서드로 통합하는 것이 도움이 됩니다.
using IronBarCode;
using System.Collections.Generic;
using System.Linq;
// Reusable validation helper — consolidates null, empty, value, and
// expected-format checks into a single method. Returns an empty list
// (never null) so callers do not need to null-check the return value.
public static class BarcodeValidator
{
public static List<BarcodeResult> GetValidResults(
string imagePath,
BarcodeEncoding? expectedType = null,
double confidenceThreshold = 0.7)
{
// Apply confidence threshold at scan level via BarcodeReaderOptions
var options = new BarcodeReaderOptions
{
ConfidenceThreshold = confidenceThreshold
};
BarcodeResults results = BarcodeReader.Read(imagePath, options);
// Return empty list instead of null so callers never need to null-check the return value
if (results is null || results.Count == 0)
return new List<BarcodeResult>();
return results
.Where(r => !string.IsNullOrWhiteSpace(r.Value)) // skip results with empty decoded data
.Where(r => expectedType == null || r.BarcodeType == expectedType) // null accepts any symbology
.ToList();
}
}
// Usage: pass the image path and the symbology you expect
var validated = BarcodeValidator.GetValidResults(
"warehouse-scan.png",
expectedType: BarcodeEncoding.Code128,
confidenceThreshold: 0.7);
if (validated.Count == 0)
{
// No valid results; log the failure and skip downstream processing
return;
}
// All results have passed null, empty, type, and confidence checks
foreach (var barcode in validated)
{
SendToInventorySystem(barcode.Value, barcode.BarcodeType.ToString()); // placeholder for your downstream call
}
Imports IronBarCode
Imports System.Collections.Generic
Imports System.Linq
' Reusable validation helper — consolidates null, empty, value, and
' expected-format checks into a single method. Returns an empty list
' (never null) so callers do not need to null-check the return value.
Public Module BarcodeValidator
Public Function GetValidResults(
imagePath As String,
Optional expectedType As BarcodeEncoding? = Nothing,
Optional confidenceThreshold As Double = 0.7) As List(Of BarcodeResult)
' Apply confidence threshold at scan level via BarcodeReaderOptions
Dim options As New BarcodeReaderOptions With {
.ConfidenceThreshold = confidenceThreshold
}
Dim results As BarcodeResults = BarcodeReader.Read(imagePath, options)
' Return empty list instead of null so callers never need to null-check the return value
If results Is Nothing OrElse results.Count = 0 Then
Return New List(Of BarcodeResult)()
End If
Return results _
.Where(Function(r) Not String.IsNullOrWhiteSpace(r.Value)) _ ' skip results with empty decoded data
.Where(Function(r) expectedType Is Nothing OrElse r.BarcodeType = expectedType) _ ' null accepts any symbology
.ToList()
End Function
End Module
' Usage: pass the image path and the symbology you expect
Dim validated = BarcodeValidator.GetValidResults(
"warehouse-scan.png",
expectedType:=BarcodeEncoding.Code128,
confidenceThreshold:=0.7)
If validated.Count = 0 Then
' No valid results; log the failure and skip downstream processing
Return
End If
' All results have passed null, empty, type, and confidence checks
For Each barcode In validated
SendToInventorySystem(barcode.Value, barcode.BarcodeType.ToString()) ' placeholder for your downstream call
Next barcode
$vbLabelText $csharpLabel
이 메서드는 null이 아닌 빈 리스트를 반환하므로 호출자는 반환 값에 대해 null 검사를 할 필요가 없습니다. 선택 사항인 expectedType 매개변수는 심볼을 기준으로 필터링하여 스캔 결과 동일한 이미지에서 QR 코드와 Code 128이 모두 감지될 때 하위 시스템에서 예기치 않은 형식을 수신하는 것을 방지합니다.
여러 파일을 일괄 적으로 읽으 려면 파일마다 동일한 패턴을 적용하고 결과를 집계하십시오. BarcodeReaderOptions의 ExpectBarcodeTypes 옵션은 예상되는 심볼로지로 스캔 범위를 좁혀 유효성 검사기에 도달하는 원치 않는 결과를 줄입니다.