Como Depurar Operações de Código QR e Lidar com Mensagens de Erro em C#

Como Obter Mensagens de Erro Detalhadas da Leitura de Códigos QR?

Lidamos com falhas de tempo de leitura capturando exceções de AnyBitmap.FromFile() (acesso ao arquivo) e QrReader.Read() (decodificação), em seguida, inspecionando o caso de resultado vazio separadamente. Uma leitura que não encontra códigos QR retorna um IEnumerable<QrResult> vazio em vez de lançar — este é o comportamento esperado, não um erro, mas ainda precisa ser registrado como um evento de diagnóstico em um pipeline de produção.

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

O objeto QrResult expõe três campos de diagnóstico: Value (a string decodificada), Points (as coordenadas dos quatro cantos da região QR detectada) e QrType (um de QRCode, MicroQRCode, ou RMQRCode). Quando uma leitura produz resultados parciais ou inesperados, o campo QrType ajuda a identificar se o leitor detectou um QR padrão ou um formato variante.

Como Depurar Falhas na Geração de Códigos QR?

QrWriter.Write() lança uma exceção quando a entrada viola as restrições de codificação QR. Passar null aciona um ArgumentNullException. Dados que excedem a capacidade máxima para o nível de correção de erro selecionado lançam um ArgumentException — níveis de correção mais altos (como QrErrorCorrectionLevel.Highest) reduzem a capacidade de dados disponível, então a mesma string pode ser bem-sucedida em Medium mas falhar em Highest.

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

using IronQr;

string? content = null;
string oversizedContent = new string('A', 5000);

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

// 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);
}
catch (ArgumentException ex)
{
    Console.Error.WriteLine($"[ERROR] QR capacity exceeded: {ex.Message}");
    Console.Error.WriteLine($"  Input length: {oversizedContent.Length} chars");
    Console.Error.WriteLine($"  Action: Reduce content or lower error correction level");
}

Registramos o comprimento da entrada junto com a mensagem de exceção para dar aos engenheiros de plantão contexto suficiente para determinar se a correção é conteúdo mais curto ou um nível de correção de erros mais baixo. O artigo sobre correção de erros cobre os compromissos de capacidade em detalhe — fornecemos um link aqui em vez de duplicar esse conteúdo.

Para fluxos de trabalho de geração que aceitam conteúdo fornecido pelo usuário, recomendamos validar o comprimento da string e verificar nulos antes de chamar QrWriter.Write(). Pré-validação é mais barata do que o tratamento de exceções e produz mensagens de diagnóstico mais claras.

Como registrar e monitorar operações de código QR?

IronQR não expõe uma API de logging específica do produto. A classe compartilhada IronSoftware.Logger — disponível em todos os produtos Iron Software — captura saídas de diagnóstico internas quando ativada. Para uma observabilidade estruturada, envolvemos as operações de QR em um método auxiliar que registra o caminho de entrada, contagem de resultados, tempo decorrido e quaisquer exceções como saída processável por máquina.

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

A saída JSON se integra diretamente a pipelines de agregação de logs — stdout encaminhado para Fluentd, Datadog ou CloudWatch em um implante containerizado. O campo ms revela regressões de latência. O arquivo IronSoftware.Logger captura detalhes internos de processamento que o wrapper não captura — útil para escalonamento de suporte quando o log estruturado sozinho não explica uma falha.

Para confiabilidade no nível de codificação, o guia de correção de erro cobre como ajustar QrErrorCorrectionLevel para melhorar a resiliência da digitalização para códigos danificados ou parcialmente obstruídos. Ajustar a correção de erros é uma estratégia complementar — reduz o número de falhas de leitura que chegam à camada de tratamento de erros.

Quais são os meus próximos passos?

Cobrimos o tratamento de erros em tempo de leitura com diagnósticos de resultado vazio, padrões de falha em tempo de gravação para violações de nulidade e capacidade, e um wrapper de logging reutilizável que produz saída JSON estruturada para a observabilidade do pipeline.

Para leitura adicional:

• Níveis de Correção de Erros — ajuste a resiliência do QR no nível de codificação.
• Como Ler Códigos QR — passo a passo do início ao fim.
• Tutorial de Gerador de Código QR — geração com estilização e logotipos.
• Configuração de Docker & Linux — deployment containerizado.
• Referência da API QrReader — assinaturas de métodos e observações.
• Referência da API QrWriter — todas as sobrecargas de Write.

Visualizar opções de licenciamento quando o pipeline estiver pronto para produção.