Arquitectura CameraBarcodeReaderView

El control CameraBarcodeReaderView es el componente central de ZXing.Net.MAUI. Se declara en XAML y se configura mediante una vinculación BarcodeReaderOptions. Cada página que lo use debe implementar OnAppearing y las anulaciones de OnDisappearing para gestionar el estado de IsDetecting:

<ContentPage xmlns:zxing="clr-namespace:ZXing.Net.Maui.Controls;assembly=ZXing.Net.MAUI.Controls">
    <zxing:CameraBarcodeReaderView
        x:Name="CameraView"
        Options="{Binding ReaderOptions}"
        BarcodesDetected="OnBarcodesDetected" />
</ContentPage>

<ContentPage xmlns:zxing="clr-namespace:ZXing.Net.Maui.Controls;assembly=ZXing.Net.MAUI.Controls">
    <zxing:CameraBarcodeReaderView
        x:Name="CameraView"
        Options="{Binding ReaderOptions}"
        BarcodesDetected="OnBarcodesDetected" />
</ContentPage>

// Toggling IsDetecting in lifecycle overrides is the documented pattern
protected override void OnDisappearing()
{
    base.OnDisappearing();
    if (CameraView != null)
        CameraView.IsDetecting = false;  // No IDisposable on the control
}

protected override void OnAppearing()
{
    base.OnAppearing();
    if (CameraView != null)
        CameraView.IsDetecting = true;
}

// Toggling IsDetecting in lifecycle overrides is the documented pattern
protected override void OnDisappearing()
{
    base.OnDisappearing();
    if (CameraView != null)
        CameraView.IsDetecting = false;  // No IDisposable on the control
}

protected override void OnAppearing()
{
    base.OnAppearing();
    if (CameraView != null)
        CameraView.IsDetecting = true;
}

' Toggling IsDetecting in lifecycle overrides is the documented pattern
Protected Overrides Sub OnDisappearing()
    MyBase.OnDisappearing()
    If CameraView IsNot Nothing Then
        CameraView.IsDetecting = False ' No IDisposable on the control
    End If
End Sub

Protected Overrides Sub OnAppearing()
    MyBase.OnAppearing()
    If CameraView IsNot Nothing Then
        CameraView.IsDetecting = True
    End If
End Sub

Cada página de escaneo en una aplicación ZXing .NET.MAUI contiene este código estándar del ciclo de vida. La ausencia de IDisposable significa que el estado de la cámara debe ser gestionado manualmente a través del indicador IsDetecting en lugar del patrón estándar Dispose.

Comparación detallada de características

Enfoque ZXing .NET.MAUI

ZXing.Net.MAUI está diseñado en torno a las APIs de cámara de la plataforma para iOS y Android. MAUI de Windowsadmite solo la generación de códigos de barras — el escaneo con cámara no se ha implementado y no está en una hoja de ruta pública. Esto refleja la elección arquitectónica de construir la biblioteca alrededor de un control de visor de cámara en vivo cuyas implementaciones de plataforma se escribieron solo para sistemas operativos móviles.

Un proyecto MAUI que tenga como objetivo net8.0-windows10.0.19041.0 no obtendrá funcionalidad de escaneo de códigos de barras de ZXing.Net.MAUI. Mac Catalyst está presente en la lista de frameworks objetivo, pero el escaneo en ese objetivo no está documentado oficialmente. Los equipos que inician un proyecto con objetivos solo móviles y luego añaden un requisito de Windows o macOS encontrarán que ZXing.Net.MAUI no puede cubrir el escaneo en esos objetivos. El propio soporte de iOS lleva un aviso: El problema de GitHub #260 documenta que los dispositivos iPhone 15 Pro y Pro Max se ven afectados por un problema de enfoque automático que impide una detección confiable.

Enfoque IronBarcode

IronBarcode es compatible con todos los frameworks de destino de MAUI (iOS, Android, Windows y macOS) desde el mismo paquete y con el mismo patrón de código. El enfoque MediaPicker + BarcodeReader.Read() se mapea naturalmente a cada plataforma: en móvil, MediaPicker.CapturePhotoAsync() invoca la cámara del dispositivo; En Windows, se corresponde con el selector de archivos, lo cual es un comportamiento apropiado para un entorno de escritorio. No se requiere código específico de la plataforma, compilación condicional ni registro en los servicios de la plataforma.

El patrón de código de barras de escritorio de MAUI para Windows y macOS está cubierto por el mismo paquete que gestiona el escaneo en dispositivos móviles. La misma llamada BarcodeReader.Read() que se ejecuta en un dispositivo Android también se ejecuta en un punto de conexión ASP.NET Core, una aplicación de escritorio WinForms o una Azure Function: el objetivo de despliegue no afecta la API.

Enfoque ZXing .NET.MAUI

CameraBarcodeReaderView es un control de cámara persistente incrustado en la página XAML. Comienza a procesar los fotogramas de la cámara cuando IsDetecting está configurado en true y se detiene cuando está configurado en false. La ausencia de una implementación de Dispose() significa que los recursos de la cámara no se liberan a través del patrón estándar IDisposable cuando el usuario navega lejos. La mitigación documentada es configurar IsDetecting = false en OnDisappearing() y restaurarlo en OnAppearing():

// ZXing.Net.MAUI: toggle IsDetecting in page lifecycle overrides
protected override void OnDisappearing()
{
    base.OnDisappearing();
    CameraView.IsDetecting = false;
}

protected override void OnAppearing()
{
    base.OnAppearing();
    CameraView.IsDetecting = true;
}

// ZXing.Net.MAUI: toggle IsDetecting in page lifecycle overrides
protected override void OnDisappearing()
{
    base.OnDisappearing();
    CameraView.IsDetecting = false;
}

protected override void OnAppearing()
{
    base.OnAppearing();
    CameraView.IsDetecting = true;
}

' ZXing.Net.MAUI: toggle IsDetecting in page lifecycle overrides
Protected Overrides Sub OnDisappearing()
    MyBase.OnDisappearing()
    CameraView.IsDetecting = False
End Sub

Protected Overrides Sub OnAppearing()
    MyBase.OnAppearing()
    CameraView.IsDetecting = True
End Sub

Este patrón debe repetirse en cada página que contenga un escáner. Las aplicaciones que navegan frecuentemente hacia y desde páginas de escaneo pueden acumular recursos de cámara que no se han liberado completamente, lo que se rastrea en el problema de GitHub #164 junto con informes de crecimiento de memoria e inicialización intermitente de la cámara al regresar. El problema de enfoque automático del iPhone 15 Pro (problema de GitHub #260) es una preocupación separada dentro de la capa de integración de la cámara: la vista de la cámara representa claramente el código de barras, pero el sistema de enfoque automático no se bloquea con suficiente nitidez para la detección en el hardware iPhone16,1 y iPhone16,2. La solución documentada es instruir al usuario para que ajuste manualmente la distancia entre el dispositivo y el código de barras.

Enfoque IronBarcode

IronBarcode no incluye un control de cámara en el diseño XAML. En su lugar, la llamada MediaPicker.CapturePhotoAsync() abre la interfaz de usuario de la cámara del sistema cuando el usuario toca un botón. La cámara del sistema gestiona el enfoque, la exposición y el autoenfoque de forma independiente. Cuando el usuario confirma la captura, la imagen resultante se pasa a BarcodeReader.Read() como una matriz de bytes:

// NuGet: dotnet add package IronBarcode
using IronBarCode;

private async void ScanButton_Clicked(object sender, EventArgs e)
{
    var photo = await MediaPicker.CapturePhotoAsync();
    if (photo == null) return;

    using var stream = await photo.OpenReadAsync();
    using var ms = new MemoryStream();
    await stream.CopyToAsync(ms);

    var results = BarcodeReader.Read(ms.ToArray());
    foreach (var barcode in results)
        Console.WriteLine($"{barcode.Format}: {barcode.Value}");
}

// No OnAppearing or OnDisappearing needed — no camera state to manage

// NuGet: dotnet add package IronBarcode
using IronBarCode;

private async void ScanButton_Clicked(object sender, EventArgs e)
{
    var photo = await MediaPicker.CapturePhotoAsync();
    if (photo == null) return;

    using var stream = await photo.OpenReadAsync();
    using var ms = new MemoryStream();
    await stream.CopyToAsync(ms);

    var results = BarcodeReader.Read(ms.ToArray());
    foreach (var barcode in results)
        Console.WriteLine($"{barcode.Format}: {barcode.Value}");
}

// No OnAppearing or OnDisappearing needed — no camera state to manage

Imports IronBarCode
Imports System.IO
Imports System.Threading.Tasks

Private Async Sub ScanButton_Clicked(sender As Object, e As EventArgs)
    Dim photo = Await MediaPicker.CapturePhotoAsync()
    If photo Is Nothing Then Return

    Using stream = Await photo.OpenReadAsync()
        Using ms As New MemoryStream()
            Await stream.CopyToAsync(ms)

            Dim results = BarcodeReader.Read(ms.ToArray())
            For Each barcode In results
                Console.WriteLine($"{barcode.Format}: {barcode.Value}")
            Next
        End Using
    End Using
End Sub

' No OnAppearing or OnDisappearing needed — no camera state to manage

El tutorial del escáner de códigos de barras .NET MAUI cubre la configuración completa del proyecto para este patrón, incluida la configuración de permisos tanto para iOS como para Android. Dado que no existe una vista de cámara persistente, no hay recursos que liberar, ni estados que alternar, ni código repetitivo del ciclo de vida que mantener en todas las páginas.

Enfoque ZXing .NET.MAUI

ZXing .NET.MAUI hereda el requisito de especificación de formato de ZXing .NET . Antes de que comience el escaneo, el desarrollador debe poblar BarcodeReaderOptions.Formats con una máscara de bits de los valores de la enumeración BarcodeFormats que deberían ser detectados. Los formatos no incluidos en esta lista no serán detectados, de forma silenciosa, sin error ni advertencia:

// ZXing.Net.MAUI: formats must be declared explicitly
// Formats not listed here are not detected
ReaderOptions = new BarcodeReaderOptions
{
    Formats = BarcodeFormats.QRCode |
              BarcodeFormats.Code128 |
              BarcodeFormats.Ean13 |
              BarcodeFormats.UpcA,
    TryHarder = true,
    AutoRotate = true
};

// ZXing.Net.MAUI: formats must be declared explicitly
// Formats not listed here are not detected
ReaderOptions = new BarcodeReaderOptions
{
    Formats = BarcodeFormats.QRCode |
              BarcodeFormats.Code128 |
              BarcodeFormats.Ean13 |
              BarcodeFormats.UpcA,
    TryHarder = true,
    AutoRotate = true
};

' ZXing.Net.MAUI: formats must be declared explicitly
' Formats not listed here are not detected
ReaderOptions = New BarcodeReaderOptions With {
    .Formats = BarcodeFormats.QRCode Or
               BarcodeFormats.Code128 Or
               BarcodeFormats.Ean13 Or
               BarcodeFormats.UpcA,
    .TryHarder = True,
    .AutoRotate = True
}

Si un usuario apunta la cámara a un GS1 DataBar, un código Aztec, un MaxiCode o cualquier formato que no esté declarado en las opciones, la exploración no devuelve resultados sin generar un error. La cámara representa el código de barras y no se devuelve ningún resultado a la aplicación. En un entorno controlado, como un almacén donde cada artículo lleva una etiqueta con el código 128, esto es manejable. En despliegues donde los formatos de códigos de barras son determinados por proveedores externos, clientes o sistemas de terceros, la ausencia de una ruta de respaldo se convierte en un problema de soporte recurrente.

Enfoque IronBarcode

IronBarcode realiza la detección automática de formatos en todos los formatos compatibles sin necesidad de configuración previa. BarcodeReader.Read() analiza la imagen y devuelve resultados para cada código de barras que identifica, independientemente del formato. No se requiere una lista BarcodeReaderOptions:

// IronBarcode: no format specification needed
// All 50+ formats detected automatically
var results = BarcodeReader.Read(imageBytes);
foreach (var barcode in results)
    Console.WriteLine($"{barcode.Format}: {barcode.Value}");

// IronBarcode: no format specification needed
// All 50+ formats detected automatically
var results = BarcodeReader.Read(imageBytes);
foreach (var barcode in results)
    Console.WriteLine($"{barcode.Format}: {barcode.Value}");

Imports IronBarcode

' IronBarcode: no format specification needed
' All 50+ formats detected automatically
Dim results = BarcodeReader.Read(imageBytes)
For Each barcode In results
    Console.WriteLine($"{barcode.Format}: {barcode.Value}")
Next

Si se requiere optimizar el rendimiento en un escenario controlado donde solo se espera un formato, se pueden pasar sugerencias de formato de forma opcional, pero nunca son necesarias para una detección correcta. Un código de barras con un formato no previsto por el desarrollador será detectado y devuelto.

Enfoque ZXing .NET.MAUI

ZXing .NET.MAUI es una biblioteca de control de cámara. No dispone de una API para leer códigos de barras desde rutas de archivo, matrices de bytes pasadas directamente desde el almacenamiento o documentos PDF. El control CameraBarcodeReaderView requiere una alimentación de cámara en vivo; No existe ningún método estático que acepte una ruta de archivo y devuelva resultados de código de barras. Los equipos que necesiten leer códigos de barras de archivos PDF cargados, sistemas de gestión documental o colas de procesamiento de imágenes por lotes no pueden usar ZXing .NET.MAUI para esos escenarios y deben introducir una biblioteca independiente.

Enfoque IronBarcode

IronBarcode lee códigos de barras de cualquier fuente a través del mismo método BarcodeReader.Read(). Admite rutas de archivo, matrices de bytes, flujos de datos y documentos PDF. El análisis de PDF es nativo: IronBarcode procesa las páginas PDF directamente sin un paso de rasterización intermedio:

// NuGet: dotnet add package IronBarcode
using IronBarCode;

// Read barcodes from a PDF file
var results = BarcodeReader.Read("invoice.pdf");
foreach (var barcode in results)
    Console.WriteLine($"Page {barcode.PageNumber}: {barcode.Format} — {barcode.Value}");

// Read from a user-selected file using MAUI FilePicker
var file = await FilePicker.PickAsync();
if (file != null)
{
    var fileResults = BarcodeReader.Read(file.FullPath);
    foreach (var result in fileResults)
        ResultLabel.Text += $"\n{result.Format}: {result.Value}";
}

// NuGet: dotnet add package IronBarcode
using IronBarCode;

// Read barcodes from a PDF file
var results = BarcodeReader.Read("invoice.pdf");
foreach (var barcode in results)
    Console.WriteLine($"Page {barcode.PageNumber}: {barcode.Format} — {barcode.Value}");

// Read from a user-selected file using MAUI FilePicker
var file = await FilePicker.PickAsync();
if (file != null)
{
    var fileResults = BarcodeReader.Read(file.FullPath);
    foreach (var result in fileResults)
        ResultLabel.Text += $"\n{result.Format}: {result.Value}";
}

Imports IronBarCode
Imports Microsoft.Maui.Storage

' Read barcodes from a PDF file
Dim results = BarcodeReader.Read("invoice.pdf")
For Each barcode In results
    Console.WriteLine($"Page {barcode.PageNumber}: {barcode.Format} — {barcode.Value}")
Next

' Read from a user-selected file using MAUI FilePicker
Dim file = Await FilePicker.PickAsync()
If file IsNot Nothing Then
    Dim fileResults = BarcodeReader.Read(file.FullPath)
    For Each result In fileResults
        ResultLabel.Text &= $"\n{result.Format}: {result.Value}"
    Next
End If

El flujo de trabajo completo para la lectura de códigos de barras en PDF, incluidos los documentos de varias páginas y los formatos de códigos de barras mixtos en diferentes páginas, está documentado en la guía "Leer códigos de barras desde PDF" . Esto abarca facturas de envío, billetes digitales, flujos de trabajo de gestión de documentos y escenarios de procesamiento por lotes que la arquitectura exclusiva para cámara de ZXing .NET.MAUI no puede abordar.

Requisitos de Windows MAUI

El factor desencadenante más común para una reevaluación es la adición de un destino MAUI para Windows a un proyecto que comenzó siendo solo para iOS y Android. Los equipos de MAUI suelen comenzar con compilaciones diseñadas primero para dispositivos móviles y luego las amplían a plataformas de escritorio a medida que evolucionan los requisitos. Cuando se produzca esa expansión, ZXing .NET.MAUI no ofrece ninguna solución viable: la plataforma Windows no está implementada ni figura en la hoja de ruta pública. El equipo deberá aceptar que el escaneo de códigos de barras no estará disponible en Windows o bien reemplazar la biblioteca. Dado que la sustitución implica un cambio estructural en el patrón de escaneo, los equipos suelen realizar el cambio en todas las plataformas al mismo tiempo.

Compatibilidad con hardware de última generación

El problema de enfoque automático de iPhone 15 Pro (problema de GitHub #260) es una consideración real para cualquier equipo que entregue un escáner de código de barras en producción a usuarios de iOS. El iPhone 15 Pro y Pro Max son comunes en el segmento de consumidores que espera una experiencia de aplicación pulida, y una solución temporal que pide a los usuarios ajustar su distancia de un código de barras es una regresión visible de UX en comparación con el hardware de iPhone más antiguo. Los equipos que detectan este problema en QA, o reciben informes de soporte de usuarios de iPhone 15 Pro, enfrentan una elección entre permanecer en una biblioteca donde actualmente no hay una solución disponible o migrar a un enfoque que no se ve afectado por el modelo de enfoque de la vista de cámara.

Procesamiento de archivos y documentos

Los requisitos de escaneo de códigos de barras rara vez se limitan a la captura de vídeo en directo. Las aplicaciones que comienzan como escáneres de inventario con frecuencia se amplían para incluir la lectura de códigos de barras de archivos PDF cargados, el procesamiento de facturas de envío o la gestión de billetes digitales desde archivos adjuntos de correo electrónico. ZXing .NET.MAUI no tiene una API para ninguno de estos escenarios. Cuando se añade a la lista de tareas pendientes un requisito de producto que implica leer un código de barras de un archivo o documento, los equipos que utilizan ZXing .NET.MAUI deben introducir una biblioteca independiente para gestionarlo. Si el equipo ya utiliza IronBarcode para alguno de esos escenarios basados ​​en archivos, consolidar el escaneo de la cámara MAUI en la misma biblioteca se convierte en el siguiente paso lógico.

Requisitos de estabilidad de la producción

La designación pre-1.0 en v0.7.4 — mientras el paquete en sí es un lanzamiento estable de NuGet — tiene implicaciones para los equipos sujetos a análisis de composición de software, auditorías de dependencia, o procesos de aprobación interna. Algunos entornos empresariales requieren que las dependencias de producción lleven un lanzamiento estable 1.0+, un contrato de soporte comercial, o ambos. ZXing.Net.MAUI está mantenido por la comunidad y es pre-1.0, lo que encaja en herramientas internas y prototipos pero añade etapas de revisión en aplicaciones orientadas al cliente donde el escáner de código de barras es un flujo de trabajo principal. La ausencia de un nivel de soporte pagado significa que cualquier error crítico depende de la disponibilidad del mantenedor de la comunidad.

Patrón de CameraBarcodeReaderView a MediaPicker

El control XAML CameraBarcodeReaderView y su declaración de espacio de nombres xmlns:zxing se eliminan por completo. En cada archivo XAML que contenía una vista de escáner, el reemplazo es un control Button que invoca MediaPicker.CapturePhotoAsync() en su controlador Clicked. El modelo impulsado por eventos, donde los resultados llegan a través de BarcodesDetected, se reemplaza leyendo el valor de retorno de BarcodeReader.Read() directamente en el controlador asíncrono.

¿Detección de eliminación del ciclo de vida?

Cada OnAppearing y anulación de OnDisappearing que existe únicamente para alternar CameraView.IsDetecting puede ser eliminada. Si esas anulaciones contienen otra lógica del ciclo de vida de la página, las líneas de IsDetecting se eliminan y se conserva la lógica restante. No hay un equivalente de IronBarcode a IsDetecting porque no hay estado de cámara persistente que gestionar entre navegaciones de página.

Eliminación del registro mediante UseBarcodeReader()

ZXing.Net.MAUI requiere una llamada builder.UseBarcodeReader() única en MauiProgram.cs para registrar sus servicios de cámara de plataforma. IronBarcode no requiere ningún registro de MauiProgram.cs. Se elimina la línea UseBarcodeReader(), y la importación del espacio de nombres using ZXing.Net.Maui; que la admite se elimina junto con la desinstalación del paquete.