QR 코드 체크섬을 검증하고 C#에서 내결함성을 적용하는 방법

This article was translated from English: Does it need improvement?
Translated
View the article in English

인쇄된 라벨, 카메라로 촬영한 이미지 또는 스캔한 문서와 같은 실제 입력을 처리하는 QR 코드 파이프라인은 디코딩하기에는 너무 손상된 기호와 체크섬은 통과했지만 비즈니스 유효성 검사에 실패하는 결과를 접하게 될 수 있습니다.

리드-솔로몬 오류 수정은 디코딩 중 발생하는 물리적 손상을 자동으로 수정합니다. 심볼을 복구할 수 없는 경우 결과 컬렉션은 부분적인 것이 아니라 비어 있습니다. 애플리케이션 수준의 유효성 검사는 별도로 수행되며, 디코딩된 값이 비어 있지 않은지, 예상 형식과 일치하는지, 또는 유효한 URI를 포함하는지 확인한 후 추가 처리를 진행합니다.

이 가이드에서는 IronQR 라이브러리를 사용하여 QR 코드 체크섬을 검증하고 오류 허용 오차 검사를 적용하는 방법을 설명합니다.

체크섬을 검증하기 위한 빠른 시작 QR 코드

QR 코드를 읽고 디코딩이 성공했는지 확인합니다. 결과가 비어 있지 않으면 리드-솔로몬 체크섬 검사를 통과한 것입니다.

  1. NuGet 패키지 관리자를 사용하여 https://www.nuget.org/packages/IronQR 설치하기

    PM > Install-Package IronQR
  2. 다음 코드 조각을 복사하여 실행하세요.

    using IronQr;
    using IronSoftware.Drawing;
    
    var reader = new QrReader();
    IEnumerable<QrResult> results = reader.Read(new QrImageInput("label.png"));
    
    if (!results.Any())
    {
        Console.WriteLine("No QR code detected or decoding failed.");
        return;
    }
    
    Console.WriteLine(results.First().Value);
  3. 실제 운영 환경에서 테스트할 수 있도록 배포하세요.

    무료 체험판으로 오늘 프로젝트에서 IronQR 사용 시작하기

    arrow pointer

QR 코드 체크섬 검증

QR 코드는 Reed-Solomon 오류 수정을 사용하여 인코딩된 데이터의 손상을 감지하고 복구합니다. 수정 수준(낮음 7%, 중간 15%, 사분위수 25%, 높음 30%)은 손실되더라도 복구 가능한 암호어의 비율을 결정합니다.

읽기 측면에서는 디코딩 중에 내부적으로 체크섬 유효성 검사가 실행됩니다. QrResult 클래스는 신뢰도 속성을 노출하지 않습니다. 해당 결과가 컬렉션에 존재하면 체크섬이 통과된 것입니다. 디코딩에 실패하면 컬렉션은 비어 있습니다.

입력

QR 코드 제품 라벨로, 중간 오류 정정(Medium error correction)으로 생성된 https://ironsoftware.com/을 인코딩한 것으로, 운송 중에 취급되거나 가볍게 긁힌 흔적이 있을 수 있는 라벨을 나타냅니다.

QR 코드 인코딩(https://ironsoftware.com)은 체크섬 유효성 검사를 위한 입력으로 사용됩니다.
:path=/static-assets/qr/content-code-examples/how-to/checksum-and-fault-tolerance/checksum-validation.cs
using IronQr;
using IronSoftware.Drawing;

var reader = new QrReader();
IEnumerable<QrResult> results = reader.Read(new QrImageInput("damaged-label.png"));

// Reed-Solomon decoding is pass/fail — presence in results means valid checksum
if (!results.Any())
{
    // Decoding failed entirely — damage exceeded the error correction capacity
    Console.WriteLine("QR code could not be decoded. Consider re-scanning or using a higher error correction level at generation time.");
    return;
}

foreach (QrResult result in results)
{
    // Decoded successfully — validate the content matches expected format
    if (string.IsNullOrWhiteSpace(result.Value))
    {
        Console.WriteLine("QR decoded but produced an empty value.");
        continue;
    }

    Console.WriteLine($"Valid QR: {result.Value}");
}
Imports IronQr
Imports IronSoftware.Drawing

Dim reader As New QrReader()
Dim results As IEnumerable(Of QrResult) = reader.Read(New QrImageInput("damaged-label.png"))

' Reed-Solomon decoding is pass/fail — presence in results means valid checksum
If Not results.Any() Then
    ' Decoding failed entirely — damage exceeded the error correction capacity
    Console.WriteLine("QR code could not be decoded. Consider re-scanning or using a higher error correction level at generation time.")
    Return
End If

For Each result As QrResult In results
    ' Decoded successfully — validate the content matches expected format
    If String.IsNullOrWhiteSpace(result.Value) Then
        Console.WriteLine("QR decoded but produced an empty value.")
        Continue For
    End If

    Console.WriteLine($"Valid QR: {result.Value}")
Next
$vbLabelText   $csharpLabel

산출

콘솔에는 디코딩된 값 https://ironsoftware.com/이 표시되어, 리드-솔로몬 디코딩이 성공했고 페이로드가 손상 없이 복구되었음을 확인해 줍니다.

터미널 출력 결과: 디코딩된 QR 코드: https://ironsoftware.com

물리적 손상에 대한 복원력을 높이려면 오류 수정 수준이 더 높은 QR 코드를 생성하세요. 하이 레벨은 더 큰 심볼 크기를 감수하는 대신 최대 30%의 데이터 손실을 복구합니다.


QR 코드 판독 시 형식 인식 처리

IronQR 표준 QR, 마이크로 QR, 직사각형 마이크로 QR의 세 가지 QR 인코딩 형식을 지원합니다. 스캐너는 읽는 동안 자동으로 형식을 감지합니다. 스캔 후, QrResult.QrType 필드는 감지된 형식을 열거형 값으로 제공합니다.

PDF의 경우 QrImageInput 대신 QrPdfInput을 사용하십시오. 스캔 모드는 속도와 정확도 간의 균형을 결정합니다: Auto는 머신 러닝 탐지 기능과 기존 스캔 방식을 결합하고, OnlyDetectionModel는 더 빠른 처리를 위해 ML 모델만 사용하며, OnlyBasicScan는 고품질의 사전 처리된 이미지를 위해 ML을 완전히 생략합니다.

입력

PNG 형식의 제품 라벨(왼쪽)과 JPEG 형식의 카메라 캡처 이미지(오른쪽)는 두 가지 일반적인 입력 유형에 걸쳐 형식을 인식하는 읽기 기능을 보여줍니다.

product-label.png QR code used as input for format-aware reading
camera-capture.jpg JPEG QR code simulating a camera capture
:path=/static-assets/qr/content-code-examples/how-to/checksum-and-fault-tolerance/format-awareness.cs
using IronQr;
using IronSoftware.Drawing;
using IronQr.Enum;

// Read from an image file with ML + classic scan (default)
var reader = new QrReader();
IEnumerable<QrResult> results = reader.Read(new QrImageInput("product-label.png"));

foreach (QrResult result in results)
{
    // Inspect the detected QR format
    Console.WriteLine($"Format: {result.QrType}");   // QRCode, MicroQRCode, or RMQRCode
    Console.WriteLine($"Value:  {result.Value}");

    // Url is non-null only if Value is a valid URI
    if (result.Url != null)
    {
        Console.WriteLine($"URI:    {result.Url.AbsoluteUri}");
    }

    // Corner coordinates for positional context
    Console.WriteLine($"Corners: {result.Points.Length} points detected");
}

// Read from a bitmap with ML-only mode for faster throughput
var bitmap = AnyBitmap.FromFile("camera-capture.jpg");
var fastResults = reader.Read(new QrImageInput(bitmap, QrScanMode.OnlyDetectionModel));
Imports IronQr
Imports IronSoftware.Drawing
Imports IronQr.Enum

' Read from an image file with ML + classic scan (default)
Dim reader As New QrReader()
Dim results As IEnumerable(Of QrResult) = reader.Read(New QrImageInput("product-label.png"))

For Each result As QrResult In results
    ' Inspect the detected QR format
    Console.WriteLine($"Format: {result.QrType}")   ' QRCode, MicroQRCode, or RMQRCode
    Console.WriteLine($"Value:  {result.Value}")

    ' Url is non-null only if Value is a valid URI
    If result.Url IsNot Nothing Then
        Console.WriteLine($"URI:    {result.Url.AbsoluteUri}")
    End If

    ' Corner coordinates for positional context
    Console.WriteLine($"Corners: {result.Points.Length} points detected")
Next

' Read from a bitmap with ML-only mode for faster throughput
Dim bitmap As AnyBitmap = AnyBitmap.FromFile("camera-capture.jpg")
Dim fastResults = reader.Read(New QrImageInput(bitmap, QrScanMode.OnlyDetectionModel))
$vbLabelText   $csharpLabel

산출

콘솔에는 제품 라벨에 대해 감지된 형식, 디코딩된 값, 확인된 URI 및 모서리 개수가 표시되고, 이어서 카메라 캡처에 대한 고속 스캔 결과 개수가 표시됩니다.

터미널 출력 내용: 형식: QRCode, 값: https://ironsoftware.com/product, URI, 모서리: 4개 지점 감지됨

QrType 필드는 애플리케이션에서 특정 형식을 요구하는 경우에 유용합니다. 예를 들어, 표준 QR 코드만 생성하는 창고 관리 시스템은 예상치 못한 마이크로 QR 코드 또는 직사각형 마이크로 QR 코드 감지를 걸러낼 수 있습니다. 이러한 코드는 노이즈 또는 관련 없는 라벨을 나타낼 수 있습니다. 각 형식은 용량 특성이 다릅니다. 표준 QR 코드는 최대 7,089개의 숫자 문자를 지원하고, 마이크로 QR 코드는 최대 35개의 숫자를 지원하며, 직사각형 마이크로 QR 코드는 제한된 라벨 공간에 적합한 직사각형 형태를 제공합니다.


QR 코드 결과에 널 검사 적용

QrReader.Read는 QR 코드가 발견되지 않으면 빈 컬렉션을 반환합니다; 결코 null을 반환하지 않습니다. 하지만 개별 결과 속성에 대한 검증은 여전히 ​​필요합니다. 예를 들어, Value은 비어 있을 수 있으며, 디코딩된 문자열이 유효한 URI가 아닌 경우 Url은 null을 반환합니다.

강력한 유효성 검사 패턴은 데이터를 다른 시스템으로 전달하기 전에 컬렉션 개수, 값의 무결성, 유형 또는 URI의 유효성이라는 세 가지 측면을 확인합니다.

입력

QR 코드가 없는 빈 흰색 이미지로, 기계 판독 가능한 라벨이 없는 페이지가 섞여 있는 문서 묶음의 한 페이지를 나타냅니다.

QR 코드가 없는 빈 흰색 이미지를 입력으로 사용하여 null 값 검사 시연을 진행했습니다.
:path=/static-assets/qr/content-code-examples/how-to/checksum-and-fault-tolerance/null-checking-validator.cs
using IronQr;
using IronSoftware.Drawing;
using System.Collections.Generic;
using System.Linq;

public static class QrValidator
{
    public static List<QrResult> GetValidResults(
        string imagePath,
        QrEncoding? expectedFormat = null)
    {
        var reader = new QrReader();
        IEnumerable<QrResult> results = reader.Read(new QrImageInput(imagePath));

        // Guard: no QR codes detected
        if (!results.Any())
            return new List<QrResult>();

        return results
            .Where(r => !string.IsNullOrWhiteSpace(r.Value))
            .Where(r => expectedFormat == null || r.QrType == expectedFormat)
            .ToList();
    }
}

// Usage — only accept standard QR codes with non-empty values
var validated = QrValidator.GetValidResults(
    "shipping-manifest.png",
    expectedFormat: QrEncoding.QRCode);

if (validated.Count == 0)
{
    Console.WriteLine("No valid QR codes found for processing.");
    return;
}

foreach (var qr in validated)
{
    // Safe for downstream: value is non-empty, format is verified
    SendToInventoryApi(qr.Value, qr.Url?.AbsoluteUri);
}
Imports IronQr
Imports IronSoftware.Drawing
Imports System.Collections.Generic
Imports System.Linq

Public Module QrValidator
    Public Function GetValidResults(
        imagePath As String,
        Optional expectedFormat As QrEncoding? = Nothing) As List(Of QrResult)

        Dim reader As New QrReader()
        Dim results As IEnumerable(Of QrResult) = reader.Read(New QrImageInput(imagePath))

        ' Guard: no QR codes detected
        If Not results.Any() Then
            Return New List(Of QrResult)()
        End If

        Return results _
            .Where(Function(r) Not String.IsNullOrWhiteSpace(r.Value)) _
            .Where(Function(r) expectedFormat Is Nothing OrElse r.QrType = expectedFormat) _
            .ToList()
    End Function
End Module

' Usage — only accept standard QR codes with non-empty values
Dim validated = QrValidator.GetValidResults(
    "shipping-manifest.png",
    expectedFormat:=QrEncoding.QRCode)

If validated.Count = 0 Then
    Console.WriteLine("No valid QR codes found for processing.")
    Return
End If

For Each qr In validated
    ' Safe for downstream: value is non-empty, format is verified
    SendToInventoryApi(qr.Value, qr.Url?.AbsoluteUri)
Next qr
$vbLabelText   $csharpLabel

산출

콘솔에는 검증기의 빈 결과 응답이 표시됩니다. QR 코드가 감지되지 않았으므로 컬렉션이 비어 있고 데이터가 하위 처리 단계로 넘어가지 않습니다.

터미널 출력에

검증기는 빈 목록(절대 null이 아님)을 반환하므로 호출 위치에서 null 검사를 할 필요가 없습니다. 선택적 expectedFormat 매개변수는 형식 게이트 역할을 하므로, 호출 코드는 예상된 형식 유형과 일치하는 결과만 수신합니다. Url 속성은 null 조건 연산자를 사용하여 URI 및 비 URI 페이로드를 모두 안전하게 처리합니다.

비동기 워크플로의 경우 ReadAsync에도 동일한 유효성 검사 패턴을 적용합니다. 즉, 호출이 완료될 때까지 기다리고 결과 컬렉션에 대해 동일한 검사를 수행합니다.


추가 자료

제품 출시 준비가 완료되면 라이선스 옵션을 확인하세요 .

ChecksumFaultToleranceTest 콘솔 앱 프로젝트 전체를 다운로드하려면 여기를 클릭하세요 .

A PHP Error was encountered

Severity: Warning

Message: Illegal string offset 'name'

Filename: sections/author_component.php

Line Number: 18

Backtrace:

File: /var/www/ironpdf.com/application/views/main/sections/author_component.php
Line: 18
Function: _error_handler

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 63
Function: view

File: /var/www/ironpdf.com/application/views/products/sections/three_column_docs_page_structure.php
Line: 64
Function: main_view

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 88
Function: view

File: /var/www/ironpdf.com/application/views/products/how-to/index.php
Line: 2
Function: view

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 88
Function: view

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 552
Function: view

File: /var/www/ironpdf.com/application/controllers/Products/Howto.php
Line: 31
Function: render_products_view

File: /var/www/ironpdf.com/index.php
Line: 292
Function: require_once

A PHP Error was encountered

Severity: Warning

Message: Illegal string offset 'title'

Filename: sections/author_component.php

Line Number: 38

Backtrace:

File: /var/www/ironpdf.com/application/views/main/sections/author_component.php
Line: 38
Function: _error_handler

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 63
Function: view

File: /var/www/ironpdf.com/application/views/products/sections/three_column_docs_page_structure.php
Line: 64
Function: main_view

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 88
Function: view

File: /var/www/ironpdf.com/application/views/products/how-to/index.php
Line: 2
Function: view

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 88
Function: view

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 552
Function: view

File: /var/www/ironpdf.com/application/controllers/Products/Howto.php
Line: 31
Function: render_products_view

File: /var/www/ironpdf.com/index.php
Line: 292
Function: require_once

A PHP Error was encountered

Severity: Warning

Message: Illegal string offset 'comment'

Filename: sections/author_component.php

Line Number: 48

Backtrace:

File: /var/www/ironpdf.com/application/views/main/sections/author_component.php
Line: 48
Function: _error_handler

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 63
Function: view

File: /var/www/ironpdf.com/application/views/products/sections/three_column_docs_page_structure.php
Line: 64
Function: main_view

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 88
Function: view

File: /var/www/ironpdf.com/application/views/products/how-to/index.php
Line: 2
Function: view

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 88
Function: view

File: /var/www/ironpdf.com/application/libraries/Render.php
Line: 552
Function: view

File: /var/www/ironpdf.com/application/controllers/Products/Howto.php
Line: 31
Function: render_products_view

File: /var/www/ironpdf.com/index.php
Line: 292
Function: require_once

시작할 준비 되셨나요?
Nuget 다운로드 63,625 | 버전: 2026.4 방금 출시되었습니다
Still Scrolling Icon

아직도 스크롤하고 계신가요?

빠른 증거를 원하시나요? PM > Install-Package IronQR
샘플을 실행하세요 URL이 QR 코드로 바뀌는 것을 확인해 보세요.