Cómo manejar errores y depurar operaciones de códigos de barras en C#

¿Cómo capturar e interpretar excepciones de IronBarcode?

Manejamos las excepciones de IronBarcode capturándolas de las más específicas a las más generales. El espacio de nombres IronBarCode.Exceptions define 11 tipos de excepciones, cada uno mapeado a un modo de falla distinto. Ordenar los bloques catch del tipo más estrecho al más amplio nos da un control preciso sobre la lógica de recuperación.

Ordenamos los bloques catch desde las excepciones más procesables (archivo, contraseña de PDF, codificación) hasta el tipo base. Los filtros de excepción con cláusulas when nos permiten enrutar tipos superpuestos sin anidamiento 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}");
}

El filtro when (ex.Message.Contains("DLL")) en IronBarCodeNativeException enruta errores de dependencia faltante a un manejador específico sin consumir otras excepciones nativas. Este patrón es particularmente útil en implementaciones de Docker donde los paquetes específicos de plataforma pueden faltar.

Tenga en cuenta que IronSoftware.Exceptions.LicensingException se lanza por separado cuando la clave de licencia es inválida o está ausente. Recomendamos capturarlo al inicio de la aplicación en lugar de alrededor de llamadas de lectura/escritura individuales.

¿Cómo extraer detalles de diagnóstico de lecturas fallidas?

Una operación de lectura que devuelve cero resultados no es una excepción: es una colección BarcodeResults vacía. Extraemos el contexto de diagnóstico inspeccionando los parámetros de entrada, las opciones que configuramos y cualquier resultado parcial que haya regresado.

El objeto BarcodeResult expone varias propiedades útiles para el análisis forense post-mortem: BarcodeType, Value, Confidence, coordenadas Y, PageNumber, BarcodeImage, y BinaryValue. Cuando los resultados están presentes pero son inesperados, la propiedad Confidence es el primer valor a inspeccionar.

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

Tres patrones surgen comúnmente durante los diagnósticos. Primero, resultados vacíos con un ajuste estrecho de ExpectBarcodeTypes generalmente significa que el código de barras real es una simbología diferente: ampliando a BarcodeEncoding.All se confirma esto. Segundo, lecturas de baja confianza bajo el 70% a menudo indican baja calidad de imagen, y aplicar filtros de imagen (contraste, nitidez, umbral adaptativo) antes de volver a intentar suele resolver el problema. Tercero, la opción RemoveFalsePositive en BarcodeReaderOptions se puede activar para eliminar lecturas fantasmas de fondos ruidosos.

¿Cómo habilitar el registro detallado para operaciones de código de barras?

IronBarcode expone una API de registro incorporada a través de la clase compartida IronSoftware.Logger. Establecemos el modo de registro y la ruta del archivo antes de cualquier operación de código de barras para capturar la salida de diagnóstico interno de las rutas de lectura y escritura de la 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 la salida de depuración como el registro a nivel de archivo. El archivo de registro registra pasos internos de procesamiento — etapas de pre-procesamiento de la imagen, intentos de detección de formato y llamadas de interoperabilidad nativa — que no son visibles a través de la API pública solamente.

Para cadenas de producción que ya usan un marco de registro estructurado (Serilog, NLog, Microsoft.Extensions.Logging), recomendamos envolver las operaciones de IronBarcode en una capa de middleware que escriba entradas JSON estructuradas junto al archivo de registro incorporado. El registrador incorporado escribe diagnósticos en texto plano útiles para la escalada de soporte; el envoltorio estructurado nos da campos consultables en nuestra pila de observabilidad.

//: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;
    }
}

La salida estructurada se integra directamente con herramientas de agregación de registros — stdout canalizado a Fluentd, Datadog, o CloudWatch en una implementación en contenedores. El campo de tiempo transcurrido muestra regresiones de rendimiento antes de que se conviertan en violaciones de SLA.

¿Cómo depurar el procesamiento por lotes de códigos de barras?

Procesamos N archivos aislando cada lectura en su propio bloque try-catch, registrando los resultados por archivo y produciendo un resumen agregado al final. La cadena continúa a través de fallos en lugar de abortar al primer error.

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

El patrón distingue tres categorías de resultados: éxito (códigos de barras encontrados y decodificados), vacío (archivo leído exitosamente pero no se detectaron códigos de barras) y fallo (excepción lanzada). Esta división en tres es crítica porque las lecturas vacías y los fallos duros requieren diferentes remedios: las lecturas vacías pueden necesitar configuraciones de formato más amplias o filtros de corrección de imagen, mientras que los fallos apuntan a problemas de infraestructura (archivos faltantes, recursos bloqueados, DLLs nativas faltantes).

La lista errors preserva el contexto por archivo para análisis post-mortem. En una cadena CI/CD, podemos analizar esta salida para establecer códigos de salida: cero para todo éxito, no cero si failCount > 0 — o alimentar los detalles del error a un sistema de alertas.

Para un mayor rendimiento, podemos habilitar el procesamiento paralelo estableciendo options.Multithreaded = true y ajustando options.MaxParallelThreads para que coincida con los núcleos de CPU disponibles. El patrón de aislamiento por archivo sigue siendo el mismo; envolvemos la iteración paralela en Parallel.ForEach con una colección segura para hilos para la lista de errores.

¿Cuales son mis próximos pasos?

Abordamos la jerarquía de excepciones de IronBarcode con 11 excepciones tipificadas, extracción de diagnóstico de propiedades BarcodeResult, registro incorporado a través de IronSoftware.Logger, y un patrón de procesamiento por lotes listo para producción con aislamiento de errores por archivo.

Para una mayor lectura, explora estos recursos:

• Tutoriales de IronBarcode — Lectura de códigos de barras para recorridos de lectura completos.
• Prevención de Falsos Positivos para reducir lecturas fantasmas en imágenes ruidosas.
• Guía de Corrección de Imagen para filtros que mejoran la precisión de lectura.
• Guía de Configuración de Docker para implementación en contenedores con dependencias nativas correctas.
• Referencia de API de BarcodeReaderOptions para documentación de configuración completa.
• Registro de Cambios de IronBarcode para correcciones específicas de versión y adiciones de funciones.

Obtén una licencia de prueba gratuita para probar todas las funciones en un entorno en vivo, o ver opciones de licenciamiento cuando el pipeline esté listo para producción.