1. IronQR
  2. Guías
  3. Mensajes de error detallados y depuración

Cómo gestionar los mensajes de error de códigos QR en C

Curtis Chau
Curtis Chau
Actualizado:
This article was translated from English: Does it need improvement?
Translated
View the article in English

La gestión de errores de IronQR te ayuda a detectar fallos de lectura y escritura, registrar diagnósticos y obtener resultados claros en cada escaneo. Si no se añaden comprobaciones explícitas, tanto un resultado vacío como un archivo dañado no devolverán nada, por lo que no sabrás qué ha fallado. Al añadir un manejo de excepciones específico y un registro de diagnóstico, puede convertir los fallos silenciosos en información útil. Esta guía explica cómo gestionar los resultados vacíos, gestionar las excepciones en tiempo de escritura y crear un envoltorio de registro estructurado para el procesamiento por lotes.

Guía de inicio rápido: Gestionar errores de códigos QR

Envuelve las operaciones de lectura de QR en un bloque try-catch y registra los diagnósticos de los errores de archivo y decodificación.

  1. Instala IronQR con el Administrador de Paquetes NuGet

    PM > Install-Package IronQR

  2. Copie y ejecute este fragmento 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. Despliegue para probar en su entorno real

    Comienza a usar IronQR en tu proyecto hoy mismo con una prueba gratuita

    arrow pointer

Flujo de trabajo mínimo (5 pasos)

  1. Descarga la biblioteca IronQR C# para la gestión de errores de códigos QR
  2. Envuelve las llamadas de lectura/escritura de QR en bloques try-catch
  3. Captura IOException y ArgumentException para errores específicos
  4. Registrar diagnósticos de resultados vacíos y excepciones
  5. Utilice el registro JSON estructurado para la observabilidad del pipeline

Gestión de errores de lectura y resultados vacíos

Sin registro, un resultado vacío y un archivo dañado parecen idénticos para el usuario. El siguiente ejemplo detecta errores de acceso a archivos y emite una advertencia si el análisis no devuelve ningún resultado.

Entrada

Este ejemplo de entrada QR se encuentra en el disco. Simularemos ambos escenarios: uno en el que el usuario recupera y descodifica el archivo, y otro en el que la ruta del archivo es incorrecta.

Codificación válida de entrada de códigos QR 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

Resultado

Salida de terminal que muestra [QR] https://ironsoftware.com/qr/scan-1 para indicar que se ha leído correctamente el código QR

Por favor notaUna lectura correcta devolvería simplemente el valor del código QR, mientras que un error durante la ejecución mostraría el mensaje de excepción o las advertencias que se muestran a continuación.

La consola que se muestra a continuación muestra un [WARN] para el caso de resultado vacío y un [ERROR] para el archivo que falta, con la ruta del archivo y una acción sugerida para cada uno.

Salida de terminal que muestra WARN por no encontrar códigos QR en damaged-scan.png y ERROR por no encontrar el archivo missing-label.png

Gestión de errores de escritura

Al pasar null a QrWriter.Write se activa un IronQrEncodingException. Los datos que superen la capacidad del nivel de corrección de errores configurado también se descartan, ya que los niveles de corrección más altos reducen la capacidad de datos disponible.

Entrada

Las dos variables de entrada siguientes definen los escenarios de fallo: nullContent es null y oversizedContent es una cadena de 5000 caracteres que excede la capacidad del código QR en el nivel de corrección más 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

Resultado

La consola muestra el tipo de excepción y el mensaje para ambos casos de fallo.

Salida de terminal que muestra IronQrEncodingException por contenido nulo pasado a QrWriter.Write

Registre la longitud de la entrada junto con el mensaje de excepción para determinar si el problema requiere un contenido más breve o un nivel de corrección más bajo. En cuanto a las entradas del usuario, valide la longitud de las cadenas y compruebe si hay valores nulos antes de la codificación para reducir la sobrecarga de excepciones y mejorar el diagnóstico.

Registro de operaciones de códigos QR

Utilice IronSoftware.Logger para capturar diagnósticos internos. Para cada operación de lectura, implemente un ayudante que registre la ruta del archivo, el recuento de resultados y el tiempo transcurrido en formato JSON para garantizar una salida clara de todo el lote.

Entrada

El lote incluye cuatro imágenes de códigos QR válidos de qr-scans/ y un quinto archivo, scan-05-broken.png, con bytes no válidos.

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

Escaneo 1

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

Escanear 2

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

Escaneo 3

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

Escanear 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

Resultado

La consola muestra líneas de registro JSON para cada archivo: cuatro lecturas correctas y una entrada de error estructurada para el archivo dañado, seguidas del resumen del lote. IronSoftware.Logger escribe diagnósticos internos en IronQR-debug.log al mismo tiempo. Puedes descargar el registro de depuración completo aquí.

Salida de terminal que muestra líneas de registro estructuradas en JSON para 4 lecturas correctas y 1 error, además de un resumen de finalización del lote

La salida JSON se envía directamente a herramientas de agregación de registros: canaliza stdout a Fluentd, Datadog o CloudWatch en una implementación en contenedores. El campo ms muestra las regresiones de latencia, y el registro de depuración captura los pasos de procesamiento internos que el envoltorio no capta.

Más información

Consulte las opciones de licencia cuando esté listo para la producción.

Haga clic aquí para descargar el proyecto completo de la aplicación de consola DetailedErrorMessagesTest.

Curtis Chau
Curtis Chau
  Chatea con el equipo de ingeniería ahora
Escritor Técnico

Curtis Chau tiene una licenciatura en Ciencias de la Computación (Carleton University) y se especializa en el desarrollo front-end con experiencia en Node.js, TypeScript, JavaScript y React. Apasionado por crear interfaces de usuario intuitivas y estéticamente agradables, disfruta trabajando con frameworks modernos y creando manuales bien ...

Leer más
¿Listo para empezar?
Nuget Descargas 63,625 | Versión: 2026.4 recién lanzado
Still Scrolling Icon

¿Aún desplazándote?

¿Quieres una prueba rápida? PM > Install-Package IronQR
ejecuta una muestra observa cómo tu URL se convierte en un código QR.