A arquitetura CameraBarcodeReaderView

O controle CameraBarcodeReaderView é o componente central do ZXing.Net.MAUI. Ele é declarado em XAML e configurado através de uma ligação BarcodeReaderOptions. Cada página que o utiliza deve implementar OnAppearing e substituir OnDisappearing para gerenciar o estado 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;  // Não 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;  // Não 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 ' Não 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 varredura em um aplicativo ZXing .NET.MAUI contém esse código padrão de ciclo de vida. A ausência de IDisposable significa que o estado da câmera deve ser gerido manualmente através do flag IsDetecting em vez do padrão Dispose.

Comparação Detalhada de Recursos

Abordagem ZXing .NET.MAUI

ZXing.Net.MAUI é projetado em torno das APIs de câmera de plataforma para iOS e Android.Windows MAUIsuporta apenas geração de código de barras — digitalização com câmera não está implementada e não está em um roteiro público. Isso reflete a escolha arquitetônica de construir a biblioteca em torno de um controle de visor de câmera ao vivo cujas implementações de plataforma foram escritas apenas para sistemas operacionais móveis.

Um projeto MAUI que mira net8.0-windows10.0.19041.0 não terá funcionalidade de digitalização de código de barras do ZXing.Net.MAUI. Mac Catalyst está presente na lista de frameworks de destino, mas a digitalização nesse destino não está oficialmente documentada. Equipes que iniciam um projeto com alvos somente móveis e posteriormente adicionam um requisito para Windows ou macOS descobrirão que ZXing.Net.MAUI não pode cobrir digitalização nesses alvos. O próprio suporte ao iOS traz um aviso: o problema do GitHub #260 documenta que os dispositivos iPhone 15 Pro e Pro Max são afetados por um problema de foco automático que impede a detecção confiável.

Abordagem do IronBarcode

O IronBarcode é compatível com todas as estruturas de destino do MAUI — iOS, Android, Windows e macOS — a partir do mesmo pacote e do mesmo padrão de código. A abordagem MediaPicker + BarcodeReader.Read() mapeia-se naturalmente para cada plataforma: em dispositivos móveis, MediaPicker.CapturePhotoAsync() aciona a câmera do dispositivo; Não Windows, ele é mapeado para o seletor de arquivos, o que é um comportamento apropriado para um ambiente de desktop. Não é necessário código específico da plataforma, compilação condicional ou registro de serviço da plataforma.

O padrão de código de barras MAUI para desktop, tanto para Windows quanto para macOS, é abrangido pelo mesmo pacote que lida com a leitura em dispositivos móveis. A mesma chamada BarcodeReader.Read() que roda em um dispositivo Android também funciona em um endpoint ASP.NET Core, uma aplicação desktop WinForms ou uma Função Azure — o alvo de implantação não afeta a API.

Abordagem ZXing .NET.MAUI

CameraBarcodeReaderView é um controle de câmera persistente incorporado na página XAML. Ele começa a processar os quadros da câmera quando IsDetecting é ajustado para true e para quando é ajustado para false. A ausência de uma implementação Dispose() significa que os recursos da câmera não são liberados através do padrão IDisposable quando o usuário navega para longe. A mitigação documentada é ajustar IsDetecting = false em OnDisappearing() e restaurá-la em 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

Esse padrão deve ser repetido em todas as páginas que contêm um scanner. Aplicações que navegam frequentemente para e de páginas de digitalização podem acumular recursos de câmera que não foram totalmente liberados, o que é acompanhado pelo problema do GitHub #164 ao lado de relatórios de crescimento de memória e inicialização intermitente da câmera no retorno. O problema de auto-foco do iPhone 15 Pro (problema do GitHub #260) é uma preocupação separada dentro da camada de integração da câmera: o visor da câmera exibe o código de barras claramente, mas o sistema de auto-foco não trava com nitidez suficiente para a detecção nos hardwares iPhone16,1 e iPhone16,2. A solução alternativa documentada é instruir o usuário a ajustar manualmente a distância entre o dispositivo e o código de barras.

Abordagem do IronBarcode

O IronBarcode não incorpora um controle de câmera no layout XAML. Em vez disso, a chamada MediaPicker.CapturePhotoAsync() abre a interface da câmera do sistema quando o usuário toca em um botão. A câmera do sistema controla o foco, a exposição e o autofoco de forma independente. Quando o usuário confirma a captura, a imagem resultante é passada para BarcodeReader.Read() como uma 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}");
}

// Não 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}");
}

// Não 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

' Não OnAppearing or OnDisappearing needed — no camera state to manage

O tutorial do leitor de código de barras .NET MAUI aborda a configuração completa do projeto para esse padrão, incluindo a configuração de permissões para iOS e Android. Como não há uma visualização de câmera persistente, não há recursos para liberar, nenhum estado para alternar e nenhum código repetitivo de ciclo de vida para manter entre as páginas.

Abordagem ZXing .NET.MAUI

O ZXing .NET.MAUI herda os requisitos de especificação de formato do ZXing .NET . Antes que a digitalização comece, o desenvolvedor deve preencher BarcodeReaderOptions.Formats com uma máscara de bits dos valores de enum BarcodeFormats que devem ser detectados. Os formatos não incluídos nesta lista não serão detectados — silenciosamente, sem erro ou aviso:

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

Se um usuário apontar a câmera para um GS1 DataBar, um código Azteca, um MaxiCode ou qualquer formato que não foi declarado nas opções, a digitalização não retorna resultado sem gerar um erro. A câmera renderiza o código de barras e nenhum resultado é retornado para a aplicação. Em um ambiente controlado — um armazém onde cada item possui uma etiqueta com o código 128 — isso é administrável. Em implantações onde os formatos de código de barras são determinados por fornecedores externos, clientes ou sistemas de terceiros, a ausência de um caminho de fallback se torna um problema recorrente de suporte.

Abordagem do IronBarcode

O IronBarcode realiza a detecção automática de formatos em todos os formatos suportados, sem qualquer configuração prévia. BarcodeReader.Read() analisa a imagem e retorna resultados para cada código de barras que identifica, independentemente do formato. Nenhuma lista BarcodeReaderOptions é necessária:

// 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

Caso seja necessário otimizar o desempenho em um cenário controlado onde apenas um formato é esperado, as dicas de formato podem ser fornecidas opcionalmente — mas nunca são obrigatórias para a detecção correta. Um código de barras em um formato não previsto pelo desenvolvedor ainda será detectado e retornado.

Abordagem ZXing .NET.MAUI

ZXing .NET.MAUI é uma biblioteca de controle de câmeras. Não possui uma API para leitura de códigos de barras a partir de caminhos de arquivos, arrays de bytes passados ​​diretamente do armazenamento ou documentos PDF. O controle CameraBarcodeReaderView requer uma transmissão de câmera ao vivo; Não existe um método estático que aceite um caminho de arquivo e retorne resultados de código de barras. Equipes que precisam ler códigos de barras de PDFs carregados, sistemas de gerenciamento de documentos ou filas de processamento de imagens em lote não podem usar o ZXing .NET.MAUI para esses cenários e devem introduzir uma biblioteca separada.

Abordagem do IronBarcode

O IronBarcode lê códigos de barras de qualquer fonte através do mesmo método BarcodeReader.Read(). Ele aceita caminhos de arquivos, matrizes de bytes, fluxos e documentos PDF. A análise de PDFs é nativa — o IronBarcode processa páginas PDF diretamente, sem uma etapa intermediária de rasterização:

// 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

O fluxo de trabalho completo de leitura de códigos de barras em PDF, incluindo documentos com várias páginas e formatos de código de barras mistos em diferentes páginas, está documentado no guia de leitura de códigos de barras em PDF . Isso abrange faturas de envio, bilhetes digitais, fluxos de trabalho de gerenciamento de documentos e cenários de processamento em lote que a arquitetura baseada apenas em câmera do ZXing .NET.MAUI não consegue atender.

Requisitos do MAUI do Windows

O fator mais comum que leva a uma reavaliação é a adição de um alvo MAUI para Windows a um projeto que começou como exclusivo para iOS e Android. As equipes da MAUI frequentemente começam com versões focadas em dispositivos móveis e expandem para versões desktop à medida que os requisitos evoluem. Quando essa expansão ocorrer, o ZXing .NET.MAUI não oferece uma solução — a plataforma Windows não está implementada e não consta em um roteiro público. A equipe terá que aceitar que a leitura de código de barras não estará disponível no Windows ou substituir a biblioteca. Como a substituição envolve uma mudança estrutural no padrão de digitalização, as equipes normalmente fazem a alteração para todas as plataformas ao mesmo tempo.

Compatibilidade com hardware da geração atual

O problema de foco automático do iPhone 15 Pro (problema do GitHub #260) é uma consideração real para qualquer equipe que esteja lançando um scanner de código de barras de produção para usuários de iOS. O iPhone 15 Pro e Pro Max são comuns no segmento de consumidores que espera uma experiência de aplicação polida, e uma solução alternativa que pede aos usuários para ajustar sua distância de um código de barras é uma regressão notável de UX em comparação com o hardware do iPhone mais antigo. Equipes que encontram esse problema no QA, ou recebem relatórios de suporte de usuários do iPhone 15 Pro, enfrentam uma escolha entre permanecer em uma biblioteca onde nenhuma correção está atualmente disponível ou migrar para uma abordagem que não seja afetada pelo modelo de foco da visualização da câmera.

Processamento de Arquivos e Documentos

Os requisitos de leitura de código de barras raramente se limitam à captura de imagens ao vivo por câmera. Aplicações que começam como leitores de inventário frequentemente se expandem para incluir a leitura de códigos de barras de PDFs carregados, o processamento de faturas de envio ou o gerenciamento de ingressos digitais anexados a e-mails. O ZXing .NET.MAUI não possui uma API para nenhum desses cenários. Quando um requisito de produto que envolve a leitura de um código de barras de um arquivo ou documento entra na lista de pendências, as equipes que usam ZXing .NET.MAUI precisam introduzir uma biblioteca separada para lidar com isso. Se a equipe já utiliza o IronBarcode para algum desses cenários baseados em arquivos, consolidar a digitalização da câmera MAUI na mesma biblioteca torna-se o próximo passo natural.

Requisitos de estabilidade de produção

A designação pré-1.0 na v0.7.4 — embora o próprio pacote seja um lançamento estável do NuGet — tem implicações para equipes sujeitas a análise de composição de software, auditorias de dependência ou processos de aprovação interna. Alguns ambientes corporativos exigem que dependências de produção tenham um lançamento estável 1.0+ ou um contrato de suporte comercial, ou ambos. ZXing.Net.MAUI é mantido pela comunidade e pré-1.0, o que se encaixa em ferramentas internas e protótipos, mas adiciona etapas de revisão em aplicações voltadas para o cliente onde o scanner de código de barras é o fluxo de trabalho principal. A ausência de um nível de suporte pago significa que qualquer bug crítico depende da disponibilidade do mantenedor da comunidade.

Padrão CameraBarcodeReaderView para MediaPicker

O controle XAML CameraBarcodeReaderView e sua declaração de namespace xmlns:zxing são removidos completamente. Em cada arquivo XAML que continha uma visualização do scanner, a substituição é um controle Button que invoca MediaPicker.CapturePhotoAsync() em seu manipulador Clicked. O modelo orientado a eventos — onde os resultados chegam através de BarcodesDetected — é substituído pela leitura do valor de retorno de BarcodeReader.Read() diretamente no manipulador assíncrono.

Detecção de remoção do ciclo de vida

Cada substituição de OnAppearing e OnDisappearing que existe apenas para alternar CameraView.IsDetecting pode ser deletada. Se essas substituições contiverem outra lógica de ciclo de vida da página, as linhas IsDetecting são removidas e a lógica restante é preservada. Não existe um equivalente do IronBarcode para IsDetecting porque não há estado de câmera persistente para gerenciar entre navegações de página.

Remoção do registro UseBarcodeReader()

O ZXing.Net.MAUI requer uma chamada única builder.UseBarcodeReader() em MauiProgram.cs para registrar seus serviços de câmera da plataforma. O IronBarcode não requer qualquer registro MauiProgram.cs. A linha UseBarcodeReader() é removida, e a importação do namespace using ZXing.Net.Maui; que a suporta é removida junto com a desinstalação do pacote.