Como Validar Checksums de Código QR e Aplicar Tolerância a Falhas em C&#35

Como Validar Checksums de Código QR?

Os códigos QR usam correção de erros Reed-Solomon para detectar e reparar danos aos dados codificados. O nível de correção — Baixo (7%), Médio (15%), Quartil (25%) ou Alto (30%) — determina qual percentual de palavras-código pode ser perdido e ainda recuperado. Isto é definido no momento da geração via QrOptions e o como corrigir erros cobre a configuração em detalhes.

No lado da leitura, a validação do checksum acontece internamente durante a decodificação. O scanner potenciado por ML do IronQR localiza o símbolo QR, extrai os módulos de dados, executa a decodificação Reed-Solomon, e ou tem sucesso ou descarta o resultado. A classe QrResult não expõe uma propriedade .Confidence — se um resultado existir no IEnumerable<QrResult> retornado, a soma de verificação foi aprovada. Se a decodificação falhar, a coleção estará vazia.

Este resultado binário — decodificado ou não — é a validação prática do checksum. A preocupação ao nível da aplicação muda de "o checksum passou?" para "os dados decodificados correspondem ao que a aplicação espera?"

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

Para sistemas que necessitam de maior recuperabilidade de danos físicos, a solução é gerar códigos QR com um nível de correção de erros mais alto. O como corrigir erros demonstra a configuração de QrErrorCorrectionLevel.High via QrOptions — isso recupera até 30% de perda de dados ao custo de um símbolo maior.

Como Lidar com a Consciência de Formato na Leitura de Código QR?

IronQR suporta três formatos de codificação QR: padrão QRCode, MicroQRCode, e RMQRCode (QR Micro Retangular). O scanner detecta o formato automaticamente durante a leitura — não é necessária configuração para lidar com diferentes tipos. Após a digitalização, o campo QrResult.QrType expõe o formato detectado como um valor enum QrEncoding.

O invólucro QrImageInput aceita múltiplos tipos de entrada. Podemos construí-lo a partir de uma string de caminho de arquivo, um AnyBitmap, um byte[], ou um Stream. Para PDFs, use QrPdfInput. O modo de escaneamento também pode ser especificado: QrScanMode.Auto combina detecção ML com digitalização clássica para máxima confiabilidade, OnlyDetectionModel usa apenas o modelo ML para maior rendimento, e OnlyBasicScan pula o ML completamente para imagens pré-processadas de alta qualidade.

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

O campo .QrType é útil quando o aplicativo espera um formato específico. Por exemplo, um sistema de armazém que só produz códigos QR padrão pode filtrar detecções inesperadas de MicroQRCode ou RMQRCode que podem representar ruído ou etiquetas não relacionadas na imagem. Cada formato tem características de capacidade diferentes: QR padrão suporta até 7.089 caracteres numéricos, MicroQR lida com até 35, e RMQRCode oferece um formato retangular para espaços de etiquetas restritos. O tutorial de leitura de códigos QR cobre cenários de entrada adicionais, incluindo TIFFs com múltiplos quadros e páginas PDF.

Como Aplicar Verificação de Nulos aos Resultados de Códigos QR?

QrReader.Read() retorna IEnumerable<QrResult>. A coleção está vazia quando nenhum código QR é encontrado — não é nula. No entanto, as propriedades individuais de QrResult ainda precisam de validação: .Value é um readonly string que poderia, teoricamente, estar vazio, e .Url retorna nulo quando o valor não é um URI válido. A matriz .Points contém as coordenadas dos cantos e é povoada para cada resultado.

O padrão defensivo verifica três coisas: contagem da coleção, integridade individual .Value, e validade do tipo/URI antes de passar os dados para outro sistema.

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

O validador retorna uma lista vazia (nunca nula), o que elimina a verificação nula no ponto de chamada. O parâmetro opcional expectedFormat atua como um portal de formato — o código de chamada só recebe resultados que correspondem ao QrEncoding esperado. Para a propriedade .Url, o operador condicional nulo (?.) lida com segurança tanto com cargas úteis URI quanto não URI.

Para fluxos de trabalho assíncronos, os mesmos padrões se aplicam a QrReader.ReadAsync() — o tipo de retorno é Task<IEnumerable<QrResult>>, então await a chamada e aplique proteções idênticas à coleção não encapsulada.

Próximos passos

A tolerância a falhas do código QR abrange duas camadas: o nível de correção de erro Reed-Solomon definido no momento da geração e a validação em nível de aplicação aplicada após a leitura. Use o guia de correção de erros para configurar a resiliência no momento da escrita, e os padrões acima para validar os resultados no momento da leitura antes de entrarem nos sistemas a jusante.

Explore a referência da API QrResult para a superfície completa da propriedade, o como ler para opções de formato de entrada, e os exemplos de código para configurações avançadas de digitalização.

Ver opções de licenciamento a partir de $499.