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

Updated: 9 de maio de 2026

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.

1Install IronQR with NuGet Package Manager
PM > Install-Package IronQR
```
Install-Package IronQR
```

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

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

3Implante para testar em seu ambiente de produção.

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

Fluxo de trabalho mínimo (5 etapas)

Baixe a biblioteca IronQR C# para tratamento de erros de código QR
Envolva chamadas de leitura/gravação de QR em blocos try-catch
Capture IOException e ArgumentException para falhas específicas
Registre diagnósticos para resultados vazios e exceções
Use log estruturado em JSON para observabilidade do pipeline

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.

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

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

Imports IronQr
Imports IronSoftware.Drawing

Module Module1
    Sub Main()
        Dim filePath As String = "damaged-scan.png"

        Try
            ' File-level failure throws IOException or FileNotFoundException
            Dim inputBmp = AnyBitmap.FromFile(filePath)
            Dim imageInput = New QrImageInput(inputBmp)

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

            If Not results.Any() Then
                ' 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
                For Each result As QrResult In results
                    Console.WriteLine($"[{result.QrType}] {result.Value}")
                Next
            End If
        Catch ex As FileNotFoundException
            Console.Error.WriteLine($"[ERROR] File not found: {filePath}")
        Catch ex As IOException
            Console.Error.WriteLine($"[ERROR] Cannot read file: {filePath} — {ex.Message}")
        Catch ex As Exception
            Console.Error.WriteLine($"[ERROR] Unexpected failure reading {filePath}: {ex.GetType().Name} — {ex.Message}")
        End Try
    End Sub
End Module

Imports IronQr
Imports IronSoftware.Drawing

Module Module1
    Sub Main()
        Dim filePath As String = "damaged-scan.png"

        Try
            ' File-level failure throws IOException or FileNotFoundException
            Dim inputBmp = AnyBitmap.FromFile(filePath)
            Dim imageInput = New QrImageInput(inputBmp)

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

            If Not results.Any() Then
                ' 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
                For Each result As QrResult In results
                    Console.WriteLine($"[{result.QrType}] {result.Value}")
                Next
            End If
        Catch ex As FileNotFoundException
            Console.Error.WriteLine($"[ERROR] File not found: {filePath}")
        Catch ex As IOException
            Console.Error.WriteLine($"[ERROR] Cannot read file: {filePath} — {ex.Message}")
        Catch ex As Exception
            Console.Error.WriteLine($"[ERROR] Unexpected failure reading {filePath}: {ex.GetType().Name} — {ex.Message}")
        End Try
    End Sub
End Module

Saída

Observe: Uma leitura bem-sucedida retornaria apenas o valor do código QR, enquanto um erro durante a execução mostraria 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 string de 5.000 caracteres que excede a capacidade do QR no nível máximo de correção.

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

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

Imports IronQr

Dim content As String = Nothing ' Nothing throws IronQrEncodingException 
Dim oversizedContent As String = New String("A"c, 5000) ' 5,000 chars exceeds QR capacity at Highest error correction level 

' Scenario 1: null input
Try
    Dim qr As QrCode = QrWriter.Write(content) ' Input
Catch ex As Exception
    Console.Error.WriteLine($"[ERROR] Null content: {ex.GetType().Name} — {ex.Message}") ' Output
End Try

' Scenario 2: data exceeds QR capacity at the configured error correction level
Try
    Dim options As New QrOptions(QrErrorCorrectionLevel.Highest)
    Dim qr As QrCode = QrWriter.Write(oversizedContent, options) ' Input
Catch ex As Exception
    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")
End Try

Imports IronQr

Dim content As String = Nothing ' Nothing throws IronQrEncodingException 
Dim oversizedContent As String = New String("A"c, 5000) ' 5,000 chars exceeds QR capacity at Highest error correction level 

' Scenario 1: null input
Try
    Dim qr As QrCode = QrWriter.Write(content) ' Input
Catch ex As Exception
    Console.Error.WriteLine($"[ERROR] Null content: {ex.GetType().Name} — {ex.Message}") ' Output
End Try

' Scenario 2: data exceeds QR capacity at the configured error correction level
Try
    Dim options As New QrOptions(QrErrorCorrectionLevel.Highest)
    Dim qr As QrCode = QrWriter.Write(oversizedContent, options) ' Input
Catch ex As Exception
    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")
End Try

Saída

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

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 codificando https://ironsoftware.com/qr/scan-1

Digitalização 1

QR code codificando https://ironsoftware.com/qr/scan-2

Digitalização 2

QR code codificando https://ironsoftware.com/qr/scan-3

Digitalização 3

QR code codificando https://ironsoftware.com/qr/scan-4

Digitalização 4

using IronQr;
using IronSoftware.Drawing;
using System.Diagnostics;

// Enable shared Iron Software logging for internal diagnostics
IronQr.Logging.Logger.LoggingMode = IronQr.Logging.Logger.LoggingModes.All;
IronQr.Logging.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");

using IronQr;
using IronSoftware.Drawing;
using System.Diagnostics;

// Enable shared Iron Software logging for internal diagnostics
IronQr.Logging.Logger.LoggingMode = IronQr.Logging.Logger.LoggingModes.All;
IronQr.Logging.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");

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 grava diagnósticos internos em IronQR-debug.log ao mesmo tempo. Você pode baixar o log de depuração completo aqui.

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

Leitura complementar

Níveis de correção de erros : ajuste a resiliência do QR Code no nível de codificação.
Como ler códigos QR : passo a passo completo da leitura.
Tutorial de Gerador de Código QR : geração com estilos e logotipos.
Referência da API do QrReader : assinaturas de métodos e observações.
Referência de API QrWriter: todas as Write sobrecargas.

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.

Perguntas frequentes

Como posso depurar operações de leitura/escrita de código QR em C#?

Você pode depurar operações de leitura/escrita de código QR em C# usando o IronQR, capturando exceções, registrando diagnósticos e monitorando o processamento em lote com saída estruturada.

O que devo fazer se encontrar um erro ao processar códigos QR em C#?

Se você encontrar um erro ao processar códigos QR em C#, use o IronQR para capturar e tratar exceções. Isso permitirá que você identifique e resolva problemas de forma eficaz.

Como o IronQR ajuda no monitoramento do processamento de lotes de códigos QR?

O IronQR ajuda no monitoramento do processamento de lotes de códigos QR ao fornecer saída estruturada, que auxilia na identificação e resolução de quaisquer erros ou ineficiências durante o processo.

O IronQR pode registrar diagnósticos para operações de código QR?

Sim, o IronQR pode registrar diagnósticos para operações de código QR, permitindo que você rastreie e analise o desempenho e os erros em suas aplicações C#.

Quais são as exceções comuns no processamento de códigos QR com o IronQR?

Exceções comuns no processamento de códigos QR com o IronQR incluem problemas relacionados a códigos QR ilegíveis e manuseio de formato incorreto, que podem ser geridos por meio de tratamento adequado de exceções no seu código C#.

How can I improve error detection during QR code processing with IronQR?

Improve error detection by implementing logging that captures detailed information on file paths, operation status, result counts, and execution time. This data supports easier debugging and system observability.

Can IronQR's logging output be integrated with log aggregation tools?

Yes, the JSON output from IronQR can be fed directly into log aggregation tools such as Fluentd, Datadog, or CloudWatch, making it suitable for containerized deployments and enhancing monitoring capabilities.

What approach does IronQR suggest for handling batch QR code operations?

IronQR recommends processing each file in isolation, logging the results for each read operation to help identify errors, and providing a complete batch summary that tallies successes and failures.

How does IronQR assist in diagnosing file-level failures during QR code scans?

IronQR detects file-level failures like IOException and FileNotFoundException, providing descriptive error messages which can be logged to pinpoint issues such as incorrect file paths or unreadable files.

Why is it important to wrap QR read/write calls in try-catch blocks?

Wrapping read/write operations in try-catch blocks ensures that failures do not crash the application, allowing you to handle exceptions gracefully, log necessary diagnostics, and guide the user with useful messages.

Curtis Chau

Converse agora mesmo com a equipe de engenharia.

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 bem estruturados e visualmente atraentes.

...