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

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

Os fluxos de trabalho de código QR que processam entradas do mundo real, incluindo etiquetas impressas, capturas de câmera ou documentos digitalizados, encontrarão símbolos que estão muito danificados para serem decodificados e resultados que passam na verificação de integridade, mas falham na validação comercial.

A correção de erros Reed-Solomon resolve automaticamente os danos físicos durante a decodificação. Se um símbolo não puder ser recuperado, a coleção de resultados estará vazia em vez de parcial. A validação em nível de aplicação é um processo separado e envolve verificar se o valor decodificado não está vazio, se corresponde ao formato esperado ou se contém um URI válido antes de prosseguir com o processamento.

Este guia explica como validar checksums de códigos QR e aplicar verificações de tolerância a falhas com a biblioteca IronQR .

Início Rápido: Validar Checksums de Código QR

Leia um código QR e verifique se a decodificação foi bem-sucedida: um resultado não vazio significa que a verificação Reed-Solomon foi aprovada.

  1. Instale IronQR com o Gerenciador de Pacotes NuGet

    PM > Install-Package IronQR
  2. Copie e execute este trecho de código.

    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. Implante para testar em seu ambiente de produção.

    Comece a usar IronQR em seu projeto hoje com uma avaliação gratuita

    arrow pointer

Validação de somas de verificação 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 em 7%, Médio em 15%, Quartil em 25% ou Alto em 30%) determina a porcentagem de palavras-código que podem ser perdidas e ainda assim serem recuperadas.

No lado da leitura, a validação do checksum é executada internamente durante a decodificação. A classe QrResult não expõe uma propriedade de confiança; Se existir um resultado na coleção, o checksum foi aprovado. Se a decodificação falhar, a coleção ficará vazia.

Entrada

Uma etiqueta de produto com código QR, codificando https://ironsoftware.com/, gerada com correção de erros média, representando uma etiqueta que pode ter sido manuseada ou levemente arranhada durante o transporte.

Codificação de código QR https://ironsoftware.com usada como entrada para validação de checksum
: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}");
}
$vbLabelText   $csharpLabel

Saída

O console mostra o valor decodificado https://ironsoftware.com/, confirmando que a decodificação Reed-Solomon foi bem-sucedida e a carga útil foi recuperada intacta.

Saída do terminal mostrando o código QR decodificado: https://ironsoftware.com

Para maior resistência a danos físicos, gere códigos QR com um nível de correção de erros mais elevado. O nível Alto recupera até 30% da perda de dados, ao custo de um símbolo maior.


Lidando com a Consciência de Formato na Leitura de Códigos QR

O IronQR suporta três formatos de codificação QR: QR padrão, Micro QR e Micro QR retangular. O scanner detecta automaticamente o formato durante a leitura. Após a digitalização, o campo QrResult.QrType fornece o formato detectado como um valor de enumeração.

Para PDFs, use QrPdfInput em vez de QrImageInput. O modo de digitalização determina o equilíbrio entre velocidade e precisão: Auto combina a detecção por aprendizado de máquina com uma digitalização clássica, OnlyDetectionModel usa apenas o modelo de aprendizado de máquina para um processamento mais rápido e OnlyBasicScan ignora completamente o aprendizado de máquina para obter imagens pré-processadas de alta qualidade.

Entrada

Uma etiqueta de produto em PNG (à esquerda) e uma captura de câmera em JPEG (à direita), demonstrando a leitura com reconhecimento de formato em dois tipos de entrada comuns.

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));
$vbLabelText   $csharpLabel

Saída

O console exibe o formato detectado, o valor decodificado, o URI resolvido e a contagem de cantos para o rótulo do produto, seguidos pela contagem de resultados da varredura rápida para a captura da câmera.

Saída do terminal mostrando Formato: QRCode, Valor: https://ironsoftware.com/product, URI e Cantos: 4 pontos detectados

O campo QrType é útil quando o aplicativo requer um formato específico. Por exemplo, um sistema de armazém que produz apenas códigos QR padrão pode filtrar detecções inesperadas de Micro QR ou Micro QR retangular, que podem indicar ruído ou etiquetas não relacionadas. Cada formato possui características de capacidade distintas: o QR padrão suporta até 7.089 caracteres numéricos, o Micro QR até 35, e o Micro QR retangular oferece um formato retangular para espaços limitados em etiquetas.


Aplicando verificações de valores nulos aos resultados do código QR

QrReader.Read retorna uma coleção vazia se nenhum código QR for encontrado; nunca retorna null. No entanto, as propriedades individuais dos resultados ainda requerem validação. Por exemplo, Value pode estar vazio, e Url retorna nulo se a string decodificada não for um URI válido.

Um padrão de validação robusto verifica três aspectos: contagem da coleção, integridade do valor e validade do tipo ou URI antes de passar os dados para outro sistema.

Entrada

Uma imagem branca em branco, sem código QR, representando uma página de documento em um lote misto onde algumas páginas não possuem rótulo legível por máquina.

Imagem branca em branco, sem código QR, usada como entrada para demonstração de verificação de nulo.
: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);
}
$vbLabelText   $csharpLabel

Saída

O console exibe a resposta de resultado vazio do validador: nenhum código QR foi detectado, portanto a coleção está vazia e nenhum dado é encaminhado para o processamento subsequente.

Saída do terminal mostrando

O validador retorna uma lista vazia (nunca nula), eliminando a necessidade de verificação de nulos no ponto de chamada. O parâmetro opcional expectedFormat funciona como um filtro de formato, garantindo que o código que faz a chamada receba apenas resultados que correspondam ao tipo de formato esperado. A propriedade Url usa o operador condicional nulo para lidar com segurança com payloads URI e não-URI.

Para fluxos de trabalho assíncronos, aplique os mesmos padrões de validação ao ReadAsync: aguarde a chamada e use verificações idênticas na coleção resultante.


Leitura complementar

Veja as opções de licenciamento quando estiver pronto para produção.

Clique aqui para baixar o projeto completo do aplicativo de console ChecksumFaultToleranceTest.

Curtis Chau
Redator Técnico

Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais ...

Leia mais
Pronto para começar?
Nuget Downloads 62,157 | Versão: 2026.3 acaba de ser lançado
Still Scrolling Icon

Ainda está rolando a tela?

Quer provas rápidas? PM > Install-Package IronQR
executar um exemplo Veja seu URL se transformar em um código QR.