1. IronQR
  2. Tutoriais
  3. Mensagens de Erro Detalhadas & Depuração

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

Curtis Chau
Curtis Chau
Atualizado:
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

Fluxo de trabalho mínimo (5 etapas)

  1. Baixe a biblioteca IronQR C# para tratamento de erros de código QR
  2. Envolva chamadas de leitura/escrita de QR em blocos try-catch
  3. Capture IOException e ArgumentException para falhas específicas
  4. Registre diagnósticos para resultados vazios e exceções
  5. 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.

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

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

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
$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

Digitalização 1

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

Digitalização 2

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

Digitalização 3

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

Digitalização 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");

Imports IronQr
Imports IronSoftware.Drawing
Imports System.Diagnostics
Imports System.IO
Imports System.Linq

' 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
Private Function ReadQrWithDiagnostics(ByVal filePath As String) As (IEnumerable(Of QrResult), Boolean, String)
    Dim sw = Stopwatch.StartNew()
    Try
        Dim input = New QrImageInput(AnyBitmap.FromFile(filePath))
        Dim 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, Nothing)
    Catch ex As Exception
        sw.Stop()
        Dim error As String = $"{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(Of QrResult)(), False, error)
    End Try
End Function

' Usage: process a batch with per-file isolation
Dim files As String() = Directory.GetFiles("qr-scans/", "*.png")
Dim ok As Integer = 0, fail As Integer = 0

For Each file As String In files
    Dim result = ReadQrWithDiagnostics(file)
    Dim results = result.Item1
    Dim success = result.Item2
    Dim error = result.Item3

    If success AndAlso results.Any() Then
        ok += 1
    Else
        fail += 1
    End If
Next

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 ao mesmo tempo. 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: direcione 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
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 ...

Leia mais
Pronto para começar?
Nuget Downloads 64,787 | Versão: 2026.4 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.