Como lidar com mensagens de erro de código QR em C

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

O sistema de tratamento de erros do IronQR ajuda você a detectar falhas de leitura e gravação, registrar diagnósticos e obter resultados claros em cada verificação. Se você não adicionar verificações explícitas, tanto um resultado vazio quanto um arquivo corrompido não retornarão nada, então você não saberá o que deu errado. Ao adicionar tratamento de exceções direcionado e registro de diagnóstico, você pode transformar falhas silenciosas em feedback útil. Este guia explica como lidar com resultados vazios, gerenciar exceções de tempo de gravação e criar um wrapper de registro estruturado para processamento em lote.

Início Rápido: Lidar com Erros de Código QR

Envolva operações de leitura de QR em um bloco try-catch e registre diagnósticos para falhas de arquivo e decodificação.

  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;
    
    try
    {
        var input = new QrImageInput(AnyBitmap.FromFile("label.png"));
        var results = new QrReader().Read(input);
        Console.WriteLine($"Found {results.Count()} QR code(s)");
    }
    catch (IOException ex)
    {
        Console.Error.WriteLine($"File error: {ex.Message}");
    }
  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

Tratamento de erros de leitura e resultados vazios

Sem registro de logs, um resultado vazio e um arquivo corrompido parecem idênticos para quem fez a chamada. O exemplo a seguir detecta falhas de acesso a arquivos e emite um aviso caso a verificação não retorne resultados.

Entrada

Este exemplo de entrada QR existe no disco. Vamos simular os dois cenários: um em que o usuário recupera e decodifica o arquivo, e outro em que o caminho do arquivo está incorreto.

Codificação de entrada de código QR válida: https://ironsoftware.com/qr/scan-1
:path=/static-assets/qr/content-code-examples/how-to/detailed-error-messages/read-diagnostics.cs
using IronQr;
using IronSoftware.Drawing;

string filePath = "damaged-scan.png";

try
{
    // File-level failure throws IOException or FileNotFoundException
    var inputBmp = AnyBitmap.FromFile(filePath);
    var imageInput = new QrImageInput(inputBmp);

    var reader = new QrReader();
    IEnumerable<QrResult> results = reader.Read(imageInput);

    if (!results.Any())
    {
        // Not an exception — but a diagnostic event worth logging
        Console.Error.WriteLine($"[WARN] No QR codes found in: {filePath}");
        Console.Error.WriteLine($"  Action: Verify image quality or try a different scan");
    }
    else
    {
        foreach (QrResult result in results)
        {
            Console.WriteLine($"[{result.QrType}] {result.Value}");
        }
    }
}
catch (FileNotFoundException)
{
    Console.Error.WriteLine($"[ERROR] File not found: {filePath}");
}
catch (IOException ex)
{
    Console.Error.WriteLine($"[ERROR] Cannot read file: {filePath} — {ex.Message}");
}
catch (Exception ex)
{
    Console.Error.WriteLine($"[ERROR] Unexpected failure reading {filePath}: {ex.GetType().Name} — {ex.Message}");
}
$vbLabelText   $csharpLabel

Saída

Saída do terminal mostrando [QRCode] https://ironsoftware.com/qr/scan-1 para uma leitura bem-sucedida do código QR.

ObserveUma leitura bem-sucedida retornaria apenas o valor do código QR, enquanto um erro durante a execução exibiria a mensagem de exceção ou os avisos mostrados abaixo.

O console abaixo mostra um [WARN] para o caso de resultado vazio e um [ERROR] para o arquivo ausente, com o caminho do arquivo e uma ação sugerida para cada caso.

Saída do terminal mostrando AVISO: nenhum código QR encontrado em damaged-scan.png e ERRO: arquivo não encontrado para missing-label.png

Tratamento de falhas de gravação

Passar null para QrWriter.Write aciona um IronQrEncodingException. Os dados que excedem a capacidade do nível de correção de erros configurado também geram erros, uma vez que níveis de correção mais altos reduzem a capacidade de dados disponível.

Entrada

As duas variáveis ​​de entrada abaixo definem os cenários de falha: nullContent é null e oversizedContent é uma sequência de 5.000 caracteres que excede a capacidade do QR Code no nível de correção mais alto.

:path=/static-assets/qr/content-code-examples/how-to/detailed-error-messages/write-diagnostics.cs
using IronQr;

string? content = null; // null throws IronQrEncodingException 
string oversizedContent = new string('A', 5000); // 5,000 chars exceeds QR capacity at Highest error correction level 

// Scenario 1: null input
try
{   
    QrCode qr = QrWriter.Write(content); // Input
}
catch (Exception ex)
{
    Console.Error.WriteLine($"[ERROR] Null content: {ex.GetType().Name} — {ex.Message}"); // Output
}

// Scenario 2: data exceeds QR capacity at the configured error correction level
try
{
    var options = new QrOptions(QrErrorCorrectionLevel.Highest);
    QrCode qr = QrWriter.Write(oversizedContent, options); // Input
}
catch (Exception ex)
{
    Console.Error.WriteLine($"[ERROR] QR capacity exceeded: {ex.Message}"); // Output
    Console.Error.WriteLine($"  Input length: {oversizedContent.Length} chars");
    Console.Error.WriteLine($"  Action: Reduce content or lower error correction level");
}
$vbLabelText   $csharpLabel

Saída

O console exibe o tipo de exceção e a mensagem para ambos os cenários de falha.

Saída do terminal mostrando IronQrEncodingException para conteúdo nulo passado para QrWriter.Write

Registre o comprimento da entrada com a mensagem de exceção para identificar se o problema requer conteúdo mais curto ou um nível de correção inferior. Para entrada de dados do usuário, valide o comprimento da string e verifique a presença de valores nulos antes da codificação para reduzir a sobrecarga de exceções e melhorar o diagnóstico.


Registro de operações de código QR

Use IronSoftware.Logger para capturar diagnósticos internos. Para cada operação de leitura, implemente uma função auxiliar que registre o caminho do arquivo, a contagem de resultados e o tempo decorrido em formato JSON para garantir uma saída clara para todo o lote.

Entrada

O lote inclui quatro imagens de código QR válidas de qr-scans/ e um quinto arquivo, scan-05-broken.png, com bytes inválidos.

QR code encoding https://ironsoftware.com/qr/scan-1
QR code encoding https://ironsoftware.com/qr/scan-2
QR code encoding https://ironsoftware.com/qr/scan-3
QR code encoding https://ironsoftware.com/qr/scan-4
:path=/static-assets/qr/content-code-examples/how-to/detailed-error-messages/logging-wrapper.cs
using IronQr;
using IronSoftware.Drawing;
using System.Diagnostics;

// Enable shared Iron Software logging for internal diagnostics
IronSoftware.Logger.LoggingMode = IronSoftware.Logger.LoggingModes.All;
IronSoftware.Logger.LogFilePath = "ironqr-debug.log";

// Reusable wrapper for structured observability
(IEnumerable<QrResult> Results, bool Success, string Error) ReadQrWithDiagnostics(string filePath)
{
    var sw = Stopwatch.StartNew();
    try
    {
        var input = new QrImageInput(AnyBitmap.FromFile(filePath));
        var results = new QrReader().Read(input).ToList();
        sw.Stop();

        Console.WriteLine($"{{\"op\":\"qr_read\",\"file\":\"{Path.GetFileName(filePath)}\","
            + $"\"status\":\"ok\",\"count\":{results.Count},\"ms\":{sw.ElapsedMilliseconds}}}");

        return (results, true, null);
    }
    catch (Exception ex)
    {
        sw.Stop();
        string error = $"{ex.GetType().Name}: {ex.Message}";

        Console.Error.WriteLine($"{{\"op\":\"qr_read\",\"file\":\"{Path.GetFileName(filePath)}\","
            + $"\"status\":\"error\",\"exception\":\"{ex.GetType().Name}\","
            + $"\"message\":\"{ex.Message}\",\"ms\":{sw.ElapsedMilliseconds}}}");

        return (Enumerable.Empty<QrResult>(), false, error);
    }
}

// Usage: process a batch with per-file isolation
string[] files = Directory.GetFiles("qr-scans/", "*.png");
int ok = 0, fail = 0;

foreach (string file in files)
{
    var (results, success, error) = ReadQrWithDiagnostics(file);
    if (success && results.Any()) ok++;
    else fail++;
}

Console.WriteLine($"\nBatch complete: {ok} success, {fail} failed/empty out of {files.Length} files");
$vbLabelText   $csharpLabel

Saída

O console exibe linhas de log JSON para cada arquivo: quatro leituras bem-sucedidas e uma entrada de erro estruturada para o arquivo corrompido, seguidas pelo resumo do lote. IronSoftware.Logger escreve diagnósticos internos para IronQR-debug.log simultaneamente. Você pode baixar o log de depuração completo aqui .

Saída do terminal mostrando linhas de log estruturadas em JSON para 4 leituras bem-sucedidas e 1 erro, Plus de um resumo da conclusão do lote.

A saída JSON alimenta diretamente ferramentas de agregação de logs: pipe stdout para Fluentd, Datadog ou CloudWatch em uma implantação conteinerizada . O campo ms revela regressões de latência, e o log de depuração captura etapas de processamento interno que o wrapper não captura.


Leitura complementar

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

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

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.