Como Tratar Erros e Depurar Operações de Código de Barras em C#

Como Capturar e Interpretar Exceções do IronBarcode?

Tratamos exceções do IronBarcode capturando-as do mais específico ao mais geral. O namespace IronBarCode.Exceptions define 11 tipos de exceções, cada um mapeando para um modo de falha distinto. Ordenar blocos de captura do tipo mais estreito ao mais amplo nos dá controle preciso sobre a lógica de recuperação.

Ordenamos os blocos de captura das exceções mais acionáveis (arquivo, senha do PDF, codificação) para o tipo base. Filtros de exceção com cláusulas when nos permitem roteirizar tipos sobrepostos sem aninhamento profundo:

//:path=/static-assets/barcode/content-code-examples/how-to/detailed-error-messages/exception-hierarchy.cs
using IronBarCode;
using IronBarCode.Exceptions;

string filePath = "warehouse-labels.pdf";

try
{
    BarcodeResults results = BarcodeReader.Read(filePath);
    foreach (BarcodeResult result in results)
    {
        Console.WriteLine($"[{result.BarcodeType}] {result.Value} (Confidence: {result.Confidence})");
    }
}
catch (IronBarCodePdfPasswordException ex)
{
    Console.Error.WriteLine($"PDF requires password: {filePath} — {ex.Message}");
}
catch (IronBarCodeFileException ex)
{
    Console.Error.WriteLine($"Cannot read file: {filePath} — {ex.Message}");
}
catch (IronBarCodeNativeException ex) when (ex.Message.Contains("DLL"))
{
    Console.Error.WriteLine($"Missing native dependency: {ex.Message}");
}
catch (IronBarCodeException ex)
{
    Console.Error.WriteLine($"IronBarcode error: {ex.GetType().Name} — {ex.Message}");
}

//:path=/static-assets/barcode/content-code-examples/how-to/detailed-error-messages/exception-hierarchy.cs
using IronBarCode;
using IronBarCode.Exceptions;

string filePath = "warehouse-labels.pdf";

try
{
    BarcodeResults results = BarcodeReader.Read(filePath);
    foreach (BarcodeResult result in results)
    {
        Console.WriteLine($"[{result.BarcodeType}] {result.Value} (Confidence: {result.Confidence})");
    }
}
catch (IronBarCodePdfPasswordException ex)
{
    Console.Error.WriteLine($"PDF requires password: {filePath} — {ex.Message}");
}
catch (IronBarCodeFileException ex)
{
    Console.Error.WriteLine($"Cannot read file: {filePath} — {ex.Message}");
}
catch (IronBarCodeNativeException ex) when (ex.Message.Contains("DLL"))
{
    Console.Error.WriteLine($"Missing native dependency: {ex.Message}");
}
catch (IronBarCodeException ex)
{
    Console.Error.WriteLine($"IronBarcode error: {ex.GetType().Name} — {ex.Message}");
}

O filtro when (ex.Message.Contains("DLL")) em IronBarCodeNativeException direciona erros de dependência ausente para um manipulador específico sem consumir outras exceções nativas. Esse padrão é particularmente útil em implantações Docker onde pacotes específicos da plataforma podem estar ausentes.

Note que IronSoftware.Exceptions.LicensingException é lançado separadamente quando a chave de licença é inválida ou ausente. Recomendamos capturá-lo na inicialização do aplicativo em vez de em chamadas individuais de leitura/gravação.

Como Extrair Detalhes de Diagnóstico de Leituras Falhadas?

Uma operação de leitura que retorna zero resultados não é uma exceção — é uma coleção BarcodeResults vazia. Extraímos o contexto de diagnóstico inspecionando os parâmetros de entrada, as opções que configuramos e quaisquer resultados parciais que retornaram.

O objeto BarcodeResult expõe várias propriedades úteis para análise post-mortem: BarcodeType, Value, Confidence, coordenadas Y, PageNumber, BarcodeImage, e BinaryValue. Quando resultados estão presentes, mas inesperados, a propriedade Confidence é o primeiro valor a ser inspecionado.

//:path=/static-assets/barcode/content-code-examples/how-to/detailed-error-messages/diagnostic-logging.cs
using IronBarCode;

string filePath = "scanned-invoice.png";

var options = new BarcodeReaderOptions
{
    ExpectBarcodeTypes = BarcodeEncoding.Code128 | BarcodeEncoding.QRCode,
    Speed = ReadingSpeed.Detailed,
    ExpectMultipleBarcodes = true
};

BarcodeResults results = BarcodeReader.Read(filePath, options);

if (results == null || results.Count == 0)
{
    // No barcodes detected — log the full diagnostic context
    Console.Error.WriteLine($"[WARN] No barcodes found in: {filePath}");
    Console.Error.WriteLine($"  ExpectedTypes: {options.ExpectBarcodeTypes}");
    Console.Error.WriteLine($"  Speed: {options.Speed}");
    Console.Error.WriteLine($"  Action: Retry with ReadingSpeed.ExtremeDetail or broaden ExpectBarcodeTypes");
}
else
{
    foreach (BarcodeResult result in results)
    {
        // Flag low-confidence reads for manual review
        string flag = result.Confidence < 80 ? " ⚠ LOW_CONFIDENCE" : "";
        Console.WriteLine($"[{result.BarcodeType}] {result.Value} "
            + $"(Confidence: {result.Confidence}%, Page: {result.PageNumber}, "
            + $"Position: {result.X},{result.Y}){flag}");
    }
}

//:path=/static-assets/barcode/content-code-examples/how-to/detailed-error-messages/diagnostic-logging.cs
using IronBarCode;

string filePath = "scanned-invoice.png";

var options = new BarcodeReaderOptions
{
    ExpectBarcodeTypes = BarcodeEncoding.Code128 | BarcodeEncoding.QRCode,
    Speed = ReadingSpeed.Detailed,
    ExpectMultipleBarcodes = true
};

BarcodeResults results = BarcodeReader.Read(filePath, options);

if (results == null || results.Count == 0)
{
    // No barcodes detected — log the full diagnostic context
    Console.Error.WriteLine($"[WARN] No barcodes found in: {filePath}");
    Console.Error.WriteLine($"  ExpectedTypes: {options.ExpectBarcodeTypes}");
    Console.Error.WriteLine($"  Speed: {options.Speed}");
    Console.Error.WriteLine($"  Action: Retry with ReadingSpeed.ExtremeDetail or broaden ExpectBarcodeTypes");
}
else
{
    foreach (BarcodeResult result in results)
    {
        // Flag low-confidence reads for manual review
        string flag = result.Confidence < 80 ? " ⚠ LOW_CONFIDENCE" : "";
        Console.WriteLine($"[{result.BarcodeType}] {result.Value} "
            + $"(Confidence: {result.Confidence}%, Page: {result.PageNumber}, "
            + $"Position: {result.X},{result.Y}){flag}");
    }
}

Três padrões comumente surgem durante diagnósticos. Primeiro, resultados vazios com uma configuração ExpectBarcodeTypes estreita geralmente significam que o código de barras real é de uma simbologia diferente — ampliar para BarcodeEncoding.All confirma isso. Segundo, leituras de baixa confiança abaixo de 70% geralmente indicam baixa qualidade da imagem, e a aplicação de filtros de imagem (contraste, nitidez, limiar adaptativo) antes de tentar novamente normalmente resolve o problema. Terceiro, a opção RemoveFalsePositive em BarcodeReaderOptions pode ser alternada para eliminar leituras fantasmas de fundos ruidosos.

Como Ativar o Registro Detalhado para Operações de Código de Barras?

IronBarcode expõe uma API de log incorporada através da classe compartilhada IronSoftware.Logger. Definimos o modo de registro e o caminho do arquivo antes de qualquer operação de código de barras para capturar a saída de diagnóstico interna das pipelines de leitura e gravação da biblioteca.

//:path=/static-assets/barcode/content-code-examples/how-to/detailed-error-messages/enable-logging.cs
using IronBarCode;

// Enable IronBarcode's built-in logging — set BEFORE any read/write calls
IronSoftware.Logger.LoggingMode = IronSoftware.Logger.LoggingModes.All;
IronSoftware.Logger.LogFilePath = "ironbarcode-debug.log";

// All subsequent operations will write diagnostic output to the log file
var options = new BarcodeReaderOptions
{
    Speed = ReadingSpeed.Detailed,
    ExpectBarcodeTypes = BarcodeEncoding.All
};

BarcodeResults results = BarcodeReader.Read("problem-scan.tiff", options);
Console.WriteLine($"Read complete. Results: {results.Count}. See ironbarcode-debug.log for details.");

//:path=/static-assets/barcode/content-code-examples/how-to/detailed-error-messages/enable-logging.cs
using IronBarCode;

// Enable IronBarcode's built-in logging — set BEFORE any read/write calls
IronSoftware.Logger.LoggingMode = IronSoftware.Logger.LoggingModes.All;
IronSoftware.Logger.LogFilePath = "ironbarcode-debug.log";

// All subsequent operations will write diagnostic output to the log file
var options = new BarcodeReaderOptions
{
    Speed = ReadingSpeed.Detailed,
    ExpectBarcodeTypes = BarcodeEncoding.All
};

BarcodeResults results = BarcodeReader.Read("problem-scan.tiff", options);
Console.WriteLine($"Read complete. Results: {results.Count}. See ironbarcode-debug.log for details.");

IronSoftware.Logger.LoggingModes.All captura tanto a saída de depuração quanto o log ao nível de arquivo. O arquivo de log registra etapas de processamento internas — estágios de pré-processamento de imagem, tentativas de detecção de formato e chamadas de interoperabilidade nativa — que não são visíveis apenas através da API pública.

Para pipelines de produção que já utilizam um framework de log estruturado (Serilog, NLog, Microsoft.Extensions.Logging), recomendamos envolver operações do IronBarcode em uma camada middleware que escreva entradas JSON estruturadas juntamente com o arquivo de log embutido. O logger embutido escreve diagnósticos em texto simples úteis para a escalada de suporte; o wrapper estruturado nos dá campos consultáveis em nossa pilha de observabilidade.

//:path=/static-assets/barcode/content-code-examples/how-to/detailed-error-messages/structured-wrapper.cs
using IronBarCode;
using System.Diagnostics;

// Lightweight wrapper for structured observability
BarcodeResults ReadWithDiagnostics(string filePath, BarcodeReaderOptions options)
{
    var sw = Stopwatch.StartNew();
    try
    {
        BarcodeResults results = BarcodeReader.Read(filePath, options);
        sw.Stop();
        Console.WriteLine($"{{\"file\":\"{filePath}\",\"status\":\"ok\","
            + $"\"count\":{results.Count},\"elapsed_ms\":{sw.ElapsedMilliseconds}}}");
        return results;
    }
    catch (Exception ex)
    {
        sw.Stop();
        Console.Error.WriteLine($"{{\"file\":\"{filePath}\",\"status\":\"error\","
            + $"\"exception\":\"{ex.GetType().Name}\",\"message\":\"{ex.Message}\","
            + $"\"elapsed_ms\":{sw.ElapsedMilliseconds}}}");
        throw;
    }
}

//:path=/static-assets/barcode/content-code-examples/how-to/detailed-error-messages/structured-wrapper.cs
using IronBarCode;
using System.Diagnostics;

// Lightweight wrapper for structured observability
BarcodeResults ReadWithDiagnostics(string filePath, BarcodeReaderOptions options)
{
    var sw = Stopwatch.StartNew();
    try
    {
        BarcodeResults results = BarcodeReader.Read(filePath, options);
        sw.Stop();
        Console.WriteLine($"{{\"file\":\"{filePath}\",\"status\":\"ok\","
            + $"\"count\":{results.Count},\"elapsed_ms\":{sw.ElapsedMilliseconds}}}");
        return results;
    }
    catch (Exception ex)
    {
        sw.Stop();
        Console.Error.WriteLine($"{{\"file\":\"{filePath}\",\"status\":\"error\","
            + $"\"exception\":\"{ex.GetType().Name}\",\"message\":\"{ex.Message}\","
            + $"\"elapsed_ms\":{sw.ElapsedMilliseconds}}}");
        throw;
    }
}

A saída estruturada integra-se diretamente com ferramentas de agregação de logs — stdout canalizado para Fluentd, Datadog ou CloudWatch em uma implantação conteinerizada. O campo de tempo decorrido destaca regressões de desempenho antes que se tornem violações de SLA.

Como Depurar Processamento em Lote de Código de Barras?

Processamos N arquivos isolando cada leitura em seu próprio bloco try-catch, registrando resultados por arquivo e produzindo um resumo agregado no final. O pipeline continua através de falhas em vez de abortar no primeiro erro.

//:path=/static-assets/barcode/content-code-examples/how-to/detailed-error-messages/batch-processing.cs
using IronBarCode;
using IronBarCode.Exceptions;
using System.Diagnostics;

// Enable built-in logging for the entire batch run
IronSoftware.Logger.LoggingMode = IronSoftware.Logger.LoggingModes.All;
IronSoftware.Logger.LogFilePath = "batch-run.log";

string[] files = Directory.GetFiles("scans/", "*.*", SearchOption.TopDirectoryOnly);

var options = new BarcodeReaderOptions
{
    Speed = ReadingSpeed.Balanced,
    ExpectBarcodeTypes = BarcodeEncoding.Code128 | BarcodeEncoding.QRCode,
    ExpectMultipleBarcodes = true
};

int successCount = 0;
int failCount = 0;
int emptyCount = 0;
var errors = new List<(string File, string Error)>();
var sw = Stopwatch.StartNew();

foreach (string file in files)
{
    try
    {
        BarcodeResults results = BarcodeReader.Read(file, options);

        if (results == null || results.Count == 0)
        {
            emptyCount++;
            errors.Add((file, "No barcodes detected"));
            continue;
        }

        foreach (BarcodeResult result in results)
        {
            Console.WriteLine($"{Path.GetFileName(file)} | {result.BarcodeType} | {result.Value} | {result.Confidence}%");
        }
        successCount++;
    }
    catch (IronBarCodePdfPasswordException)
    {
        failCount++;
        errors.Add((file, "Password-protected PDF"));
    }
    catch (IronBarCodeFileException ex)
    {
        failCount++;
        errors.Add((file, $"File error: {ex.Message}"));
    }
    catch (IronBarCodeException ex)
    {
        failCount++;
        errors.Add((file, $"{ex.GetType().Name}: {ex.Message}"));
    }
    catch (Exception ex)
    {
        failCount++;
        errors.Add((file, $"Unexpected: {ex.GetType().Name}: {ex.Message}"));
    }
}

sw.Stop();

// Summary report
Console.WriteLine("\n--- Batch Summary ---");
Console.WriteLine($"Total files:    {files.Length}");
Console.WriteLine($"Success:        {successCount}");
Console.WriteLine($"Empty reads:    {emptyCount}");
Console.WriteLine($"Failures:       {failCount}");
Console.WriteLine($"Elapsed:        {sw.Elapsed.TotalSeconds:F1}s");

if (errors.Any())
{
    Console.WriteLine("\n--- Error Details ---");
    foreach (var (errorFile, errorMsg) in errors)
    {
        Console.Error.WriteLine($"  {Path.GetFileName(errorFile)}: {errorMsg}");
    }
}

//:path=/static-assets/barcode/content-code-examples/how-to/detailed-error-messages/batch-processing.cs
using IronBarCode;
using IronBarCode.Exceptions;
using System.Diagnostics;

// Enable built-in logging for the entire batch run
IronSoftware.Logger.LoggingMode = IronSoftware.Logger.LoggingModes.All;
IronSoftware.Logger.LogFilePath = "batch-run.log";

string[] files = Directory.GetFiles("scans/", "*.*", SearchOption.TopDirectoryOnly);

var options = new BarcodeReaderOptions
{
    Speed = ReadingSpeed.Balanced,
    ExpectBarcodeTypes = BarcodeEncoding.Code128 | BarcodeEncoding.QRCode,
    ExpectMultipleBarcodes = true
};

int successCount = 0;
int failCount = 0;
int emptyCount = 0;
var errors = new List<(string File, string Error)>();
var sw = Stopwatch.StartNew();

foreach (string file in files)
{
    try
    {
        BarcodeResults results = BarcodeReader.Read(file, options);

        if (results == null || results.Count == 0)
        {
            emptyCount++;
            errors.Add((file, "No barcodes detected"));
            continue;
        }

        foreach (BarcodeResult result in results)
        {
            Console.WriteLine($"{Path.GetFileName(file)} | {result.BarcodeType} | {result.Value} | {result.Confidence}%");
        }
        successCount++;
    }
    catch (IronBarCodePdfPasswordException)
    {
        failCount++;
        errors.Add((file, "Password-protected PDF"));
    }
    catch (IronBarCodeFileException ex)
    {
        failCount++;
        errors.Add((file, $"File error: {ex.Message}"));
    }
    catch (IronBarCodeException ex)
    {
        failCount++;
        errors.Add((file, $"{ex.GetType().Name}: {ex.Message}"));
    }
    catch (Exception ex)
    {
        failCount++;
        errors.Add((file, $"Unexpected: {ex.GetType().Name}: {ex.Message}"));
    }
}

sw.Stop();

// Summary report
Console.WriteLine("\n--- Batch Summary ---");
Console.WriteLine($"Total files:    {files.Length}");
Console.WriteLine($"Success:        {successCount}");
Console.WriteLine($"Empty reads:    {emptyCount}");
Console.WriteLine($"Failures:       {failCount}");
Console.WriteLine($"Elapsed:        {sw.Elapsed.TotalSeconds:F1}s");

if (errors.Any())
{
    Console.WriteLine("\n--- Error Details ---");
    foreach (var (errorFile, errorMsg) in errors)
    {
        Console.Error.WriteLine($"  {Path.GetFileName(errorFile)}: {errorMsg}");
    }
}

O padrão distingue três categorias de resultados: sucesso (códigos de barras encontrados e decodificados), vazio (arquivo lido com sucesso, mas sem códigos de barras detectados) e falha (exceção lançada). Essa divisão em três vias é crítica porque leituras vazias e falhas duras requerem remediações diferentes — leituras vazias podem precisar de configurações de formato mais amplas ou filtros de correção de imagem, enquanto falhas apontam para problemas de infraestrutura (arquivos ausentes, recursos bloqueados, DLLs nativas ausentes).

A lista errors preserva o contexto por arquivo para análise post-mortem. Em um pipeline CI/CD, podemos analisar esta saída para definir códigos de saída — zero para todo sucesso, não zero se failCount > 0 — ou alimentar os detalhes do erro em um sistema de alertas.

Para maior throughput, podemos habilitar o processamento em paralelo configurando options.Multithreaded = true e ajustando options.MaxParallelThreads para corresponder aos núcleos de CPU disponíveis. O padrão de isolamento por arquivo permanece o mesmo; envolvemos a iteração paralela em Parallel.ForEach com uma coleção thread-safe para a lista de erros.

Quais são os meus próximos passos?

Cobrimos a hierarquia de exceções do IronBarcode com 11 exceções tipadas, extração de diagnóstico de propriedades BarcodeResult, log incorporado via IronSoftware.Logger, e um padrão de processamento em lote pronto para produção com isolamento de erro por arquivo.

Para leitura adicional, explore estes recursos:

• Tutoriais de IronBarcode — Lendo Códigos de Barras para guias completos de leitura.
• Prevenção de Falsos Positivos para redução de leituras fantasmas em imagens ruidosas.
• Como Fazer Correção de Imagem para filtros que melhoram a precisão de leitura.
• Guia de Configuração do Docker para implantação containerizada com dependências nativas corretas.
• Referência de API BarcodeReaderOptions para documentação completa de configuração.
• Changelog do IronBarcode para correções específicas de versão e adições de recursos.

Obtenha uma licença de teste gratuita para testar todos os recursos em um ambiente real ou ver opções de licenciamento quando o pipeline estiver pronto para produção.