Padrão de varredura da câmera ao vivo

O padrão completo da API BarcodeScanning.Native.Maui consiste em um controle XAML combinado com um manipulador de eventos C#:

<scanner:CameraView x:Name="CameraView"
                    OnDetectionFinished="OnBarcodeDetected"
                    CameraEnabled="True"
                    BarcodeFormats="All" />

<scanner:CameraView x:Name="CameraView"
                    OnDetectionFinished="OnBarcodeDetected"
                    CameraEnabled="True"
                    BarcodeFormats="All" />

private void OnBarcodeDetected(object sender, OnDetectionFinishedEventArg e)
{
    var barcode = e.BarcodeResults.FirstOrDefault();
    if (barcode != null)
        ResultLabel.Text = barcode.DisplayValue;
}

private void OnBarcodeDetected(object sender, OnDetectionFinishedEventArg e)
{
    var barcode = e.BarcodeResults.FirstOrDefault();
    if (barcode != null)
        ResultLabel.Text = barcode.DisplayValue;
}

Private Sub OnBarcodeDetected(sender As Object, e As OnDetectionFinishedEventArg)
    Dim barcode = e.BarcodeResults.FirstOrDefault()
    If barcode IsNot Nothing Then
        ResultLabel.Text = barcode.DisplayValue
    End If
End Sub

Este controle oferece aos usuários um visor em tempo real incorporado à página MAUI. A detecção de código de barras é contínua enquanto o feed da câmera está ativo. A UX é bem adaptada para aplicativos de consumo onde "apontar e digitalizar" é a interação principal. A restrição é que esta é a única interação que a biblioteca suporta - requisitos que vão além da detecção ao vivo da câmera em um contexto MAUI ficam fora de seu escopo.

Comparação Detalhada de Recursos

Abordagem de leitura de código de barras MAUI

BarcodeScanning.Native.Maui encapsula o pipeline nativo de detecção de câmera em cada plataforma. Não Android, ML Kit processa quadros; no iOS e macOS, o framework Vision da Apple processa frames; no Windows, ZXingCpp processa quadros. A biblioteca apresenta isso como um controle CameraView MAUI com um evento OnDetectionFinished. O código do aplicativo nunca manipula bytes de imagem diretamente — ele manipula apenas os valores de código de barras detectados que emergem do evento.

private void OnBarcodeDetected(object sender, OnDetectionFinishedEventArg e)
{
    var barcode = e.BarcodeResults.FirstOrDefault();
    if (barcode != null)
        ResultLabel.Text = barcode.DisplayValue;
}

private void OnBarcodeDetected(object sender, OnDetectionFinishedEventArg e)
{
    var barcode = e.BarcodeResults.FirstOrDefault();
    if (barcode != null)
        ResultLabel.Text = barcode.DisplayValue;
}

Private Sub OnBarcodeDetected(sender As Object, e As OnDetectionFinishedEventArg)
    Dim barcode = e.BarcodeResults.FirstOrDefault()
    If barcode IsNot Nothing Then
        ResultLabel.Text = barcode.DisplayValue
    End If
End Sub

A consequência desse projeto é que não há outro ponto de entrada. A câmera não é opcional — é a única entrada que a biblioteca reconhece. Um servidor, um arquivo, um PDF ou qualquer host não MAUI não tem caminho na biblioteca.

Abordagem do IronBarcode

IronBarcode recebe dados de imagem através de seu método estático BarcodeReader.Read(). O solicitante fornece os dados — de qualquer fonte — e a biblioteca os decodifica. Não MAUI, os dados vêm de MediaPicker; Em um servidor, ele vem do envio de um formulário; Em um aplicativo de desktop, ele vem de uma caixa de diálogo de arquivo.

//IronBarcode in MAUI: capture a photo, then read barcodes from it
// NuGet: dotnet add package IronBarcode
using IronBarCode;

private async void ScanBarcodeButton_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 result in results)
        ResultLabel.Text = result.Value;
}

//IronBarcode in MAUI: capture a photo, then read barcodes from it
// NuGet: dotnet add package IronBarcode
using IronBarCode;

private async void ScanBarcodeButton_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 result in results)
        ResultLabel.Text = result.Value;
}

Imports IronBarCode
Imports System.IO
Imports Microsoft.Maui.Media

Private Async Sub ScanBarcodeButton_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 result In results
                ResultLabel.Text = result.Value
            Next
        End Using
    End Using
End Sub

Este código roda de forma idêntica nos alvos MAUI que podem capturar uma imagem. Para uso do lado do servidor, o mesmo método BarcodeReader.Read() aceita um array de bytes de um arquivo enviado ou um caminho de PDF. A documentação do IronBarcode abrange todos os tipos de entrada suportados.

Abordagem de leitura de código de barras MAUI

BarcodeScanning.Native.Maui suporta todos os quatro alvos MAUI (iOS, Android, Windows desde 3.0.1 e macOS Catalyst), mas cada alvo usa um motor de reconhecimento diferente: Apple Vision no iOS e macOS, Google ML Kit no Android e ZXingCpp no Windows. A cobertura de simbologia e o comportamento de decodificação diferem entre os três motores, então um código de barras que decodifica de forma confiável em uma plataforma pode se comportar de forma diferente em outra. Fora do MAUI - ASP.NET, console, WPF, WinForms, Blazor Server, Azure Functions - a biblioteca não tem implementação. Equipes que precisam de lógica de código de barras tanto em um aplicativo MAUI quanto em um serviço de back-end devem usar uma biblioteca diferente para o código não MAUI.

Abordagem do IronBarcode

A chamada BarcodeReader.Read() do IronBarcode usa o mesmo motor gerenciado em todos os alvos suportados, para que o comportamento seja consistente em Windows, Linux, macOS, ASP.NET e qualquer alvo MAUI que possa capturar uma imagem e passá-la ao leitor. Não há blocos #if WINDOWS, não há carregamento condicional de dependências, e não são necessárias implementações de stub. Para entradas de arquivos e PDFs, o padrão também é consistente:

using IronBarCode;

// Read barcodes from a file the user selected
var file = await FilePicker.PickAsync();
if (file != null)
{
    var results = BarcodeReader.Read(file.FullPath);
    foreach (var result in results)
        Console.WriteLine($"{result.Format}: {result.Value}");
}

// Read barcodes directly from a PDF — no image extraction step needed
var pdfResults = BarcodeReader.Read("shipment-manifest.pdf");

using IronBarCode;

// Read barcodes from a file the user selected
var file = await FilePicker.PickAsync();
if (file != null)
{
    var results = BarcodeReader.Read(file.FullPath);
    foreach (var result in results)
        Console.WriteLine($"{result.Format}: {result.Value}");
}

// Read barcodes directly from a PDF — no image extraction step needed
var pdfResults = BarcodeReader.Read("shipment-manifest.pdf");

Imports IronBarCode

' Read barcodes from a file the user selected
Dim file = Await FilePicker.PickAsync()
If file IsNot Nothing Then
    Dim results = BarcodeReader.Read(file.FullPath)
    For Each result In results
        Console.WriteLine($"{result.Format}: {result.Value}")
    Next
End If

' Read barcodes directly from a PDF — no image extraction step needed
Dim pdfResults = BarcodeReader.Read("shipment-manifest.pdf")

O guia de integração IronBarcode MAUI fornece instruções completas de configuração para todos os dispositivos MAUI. O IronBarcode também oferece suporte à implantação no lado do servidor em ambientes ASP.NET, Docker, Azure Functions e AWS Lambda, onde o caminho BarcodeScanning.Native.Maui não está presente.

Abordagem de leitura de código de barras MAUI

No iOS, a detecção subjacente do BarcodeScanning.Native.Maui (Apple Vision) pode retornar 13 dígitos para códigos de barras UPC-A. O código UPC-A tem um formato de 12 dígitos; O zero à esquerda adicional corresponde à codificação EAN-13. A biblioteca passa esse valor bruto, e os aplicativos normalizam conforme necessário. Aplicativos que armazenam valores UPC-A em um banco de dados sem normalização podem acumular registros com um zero à esquerda.

O trabalho alternativo documentado verifica o formato e ajusta o valor:

// Normalize iOS UPC-A — strip the leading zero when present
private void OnBarcodeDetected(object sender, OnDetectionFinishedEventArg e)
{
    var barcode = e.BarcodeResults.FirstOrDefault();
    if (barcode == null) return;

    var value = barcode.DisplayValue;
    if (barcode.BarcodeFormat == BarcodeFormats.Upca && value.Length == 13)
        value = value.Substring(1);

    ProcessBarcode(value);
}

// Normalize iOS UPC-A — strip the leading zero when present
private void OnBarcodeDetected(object sender, OnDetectionFinishedEventArg e)
{
    var barcode = e.BarcodeResults.FirstOrDefault();
    if (barcode == null) return;

    var value = barcode.DisplayValue;
    if (barcode.BarcodeFormat == BarcodeFormats.Upca && value.Length == 13)
        value = value.Substring(1);

    ProcessBarcode(value);
}

' Normalize iOS UPC-A — strip the leading zero when present
Private Sub OnBarcodeDetected(sender As Object, e As OnDetectionFinishedEventArg)
    Dim barcode = e.BarcodeResults.FirstOrDefault()
    If barcode Is Nothing Then Return

    Dim value = barcode.DisplayValue
    If barcode.BarcodeFormat = BarcodeFormats.Upca AndAlso value.Length = 13 Then
        value = value.Substring(1)
    End If

    ProcessBarcode(value)
End Sub

A verificação de formato é necessária para que os valores EAN-13 começando com 0 não sejam cortados por engano. O PDF417 é documentado separadamente nos problemas do GitHub como "muito problemático - a maioria das digitalizações nunca ocorre" nos motores iOS/Android, o que é relevante para etiquetas de envio, carteiras de motorista e cartões de embarque.

Abordagem do IronBarcode

IronBarcode retorna o valor padrão de 12 dígitos do UPC-A por meio de seu motor gerenciado. O PDF417 é um formato suportado. A parte de geração também está disponível através da API do IronBarcode:

using IronBarCode;

// Generate a QR code
QRCodeWriter.CreateQrCode("https://example.com", 500)
    .SaveAsPng("qr.png");

// Generate a Code128 barcode
BarcodeWriter.CreateBarcode("ITEM-12345", BarcodeEncoding.Code128)
    .ResizeTo(400, 100)
    .SaveAsPng("barcode.png");

using IronBarCode;

// Generate a QR code
QRCodeWriter.CreateQrCode("https://example.com", 500)
    .SaveAsPng("qr.png");

// Generate a Code128 barcode
BarcodeWriter.CreateBarcode("ITEM-12345", BarcodeEncoding.Code128)
    .ResizeTo(400, 100)
    .SaveAsPng("barcode.png");

Imports IronBarCode

' Generate a QR code
QRCodeWriter.CreateQrCode("https://example.com", 500) _
    .SaveAsPng("qr.png")

' Generate a Code128 barcode
BarcodeWriter.CreateBarcode("ITEM-12345", BarcodeEncoding.Code128) _
    .ResizeTo(400, 100) _
    .SaveAsPng("barcode.png")

Para aplicações onde a precisão dos dados do código de barras afeta diretamente buscas de inventário, transações de ponto de venda ou integrações da cadeia de suprimentos, o tratamento de formato consistente da IronBarcode reduz a necessidade de normalização específica da plataforma. A documentação de leitura de código de barras IronBarcode aborda detalhadamente o comportamento específico de cada formato.

A Consistência do Motor em Plataformas Cruzadas se Torna uma Necessidade

Aplicações MAUI que visam iOS, Android, Windows e macOS adotam três motores de reconhecimento diferentes ao usar BarcodeScanning.Native.Maui: Apple Vision (iOS/macOS), Google ML Kit (Android) e ZXingCpp (Windows). Cada motor tem sua própria cobertura de simbologia e comportamento de decodificação, então o mesmo código de barras pode ser decodificado de forma diferente entre as plataformas — e os aplicativos frequentemente adicionam camadas de normalização para encobrir as diferenças. Quando esse custo de manutenção cresce, ou quando QA relatam regressões em plataformas cruzadas ligadas às diferenças de motor, as equipes às vezes migram a camada de código de barras para um único motor gerenciado que se comporta da mesma maneira em todos os alvos.

Requisitos para upload de arquivos ou processamento de PDF adicionados.

Os aplicativos móveis geralmente começam com a digitalização da câmera ao vivo como único método de entrada e, posteriormente, expandem-se para aceitar imagens ou documentos carregados. Quando um usuário precisa digitalizar um código de barras de uma foto em sua galeria, de uma imagem recebida por e-mail ou de um PDF contendo manifestos de remessa ou cartões de embarque, o BarcodeScanning.Native.Maui não tem um caminho de código para essas entradas. Equipes que enfrentam essa fronteira de requisitos se deparam com uma escolha: adicionar uma segunda biblioteca de código de barras ao lado do BarcodeScanning.Native.Maui para entradas de arquivo e PDF, ou migrar para uma única biblioteca que lida com todos os tipos de entrada. Gerenciar dois pacotes de código de barras com APIs e tipos de resultados diferentes adiciona complexidade a longo prazo que uma solução de pacote único evita.

Processamento de código de barras no servidor introduzido

Aplicativos que leem códigos de barras em dispositivos móveis geralmente desenvolvem um componente do lado do servidor — um endpoint de API ASP.NET que valida códigos de barras, uma tarefa em segundo plano que processa PDFs ou uma função na nuvem que extrai números de rastreamento de documentos carregados. BarcodeScanning.Native.Maui é uma biblioteca de controle de UI do MAUI; ela não tem uma implementação no lado do servidor. Uma equipe que precisa da mesma lógica de leitura de código de barras tanto em dispositivos móveis quanto em servidores deve usar uma biblioteca diferente para o lado do servidor. Quando surge a necessidade de implementar a lógica no servidor, as equipes frequentemente avaliam se consolidar tudo em uma única biblioteca que abranja ambas as versões é preferível a manter duas implementações separadas.

Normalização de Dados UPC-A se Torna uma Preocupação

O comportamento do código UPC-A de 13 dígitos do iOS nem sempre é detectado durante o desenvolvimento. Códigos de barras UPC-A digitalizados em desenvolvimento podem parecer funcionar corretamente, mas o zero à esquerda do framework Vision da Apple pode aparecer no banco de dados quando a normalização está ausente. Equipes que descobrem valores UPC-A de 13 dígitos em registros de inventário, sistemas de ponto de venda ou integrações de cadeia de suprimentos podem precisar tanto de uma correção de código quanto de uma etapa de correção de dados. Adicionar a normalização documentada lida com novas digitalizações; migrar para uma biblioteca com saída consistente de UPC-A às vezes é preferido como uma solução de longo prazo.

Obrigatório o uso do PDF417 (digitalização de documentos)

O PDF417 é o formato de código de barras usado em etiquetas de envio, carteiras de motorista e cartões de embarque na América do Norte. Esses são alvos de escaneamento comuns para aplicações de logística, verificação de identidade e viagens. O rastreador de problemas do GitHub do BarcodeScanning.Native.Maui documenta o PDF417 como "muito problemático - a maioria das digitalizações nunca ocorre" nos motores iOS/Android. Para aplicações onde a confiabilidade do PDF417 é um requisito funcional, as equipes frequentemente avaliam bibliotecas alternativas.

Evento da câmera para MediaPicker e leitura estática

A principal mudança estrutural na migração é substituir o padrão de evento contínuo da câmera por uma captura MediaPicker seguida de BarcodeReader.Read(). O manipulador de evento OnDetectionFinished, o controle XAML CameraView, e a declaração de namespace XML scanner: são todos removidos. Em seu lugar, um botão aciona MediaPicker.CapturePhotoAsync(), e os bytes da foto resultante são passados para BarcodeReader.Read(). Isso altera a experiência do usuário, passando de um visor contínuo ao vivo para uma tela de câmera do sistema — adequada para a maioria das aplicações empresariais.

Alterações na organização de threads

BarcodeScanning.Native.Maui dispara OnDetectionFinished em um thread de segundo plano, então todos os manipuladores existentes que atualizam elementos da interface do usuário encapsulam suas atualizações em MainThread.BeginInvokeOnMainThread(). Com o padrão MediaPicker + async usado pelo IronBarcode, a continuação após await retorna no contexto de chamada, que é tipicamente o thread principal. Na maioria dos casos, os encapsulamentos MainThread.BeginInvokeOnMainThread() podem ser removidos, simplificando o código do manipulador de eventos.

Remoção de Normalização UPC-A

Qualquer código que lidava com o comportamento de 13 dígitos UPC-A do iOS do BarcodeScanning.Native.Maui terá código que verifica BarcodeFormats.Upca e chama Substring(1) para remover o zero inicial. Esse código deve ser removido após a migração - o IronBarcode retorna o valor padrão de 12 dígitos, e deixar a normalização em vigor removeria incorretamente o primeiro dígito de leituras válidas de UPC-A.

Permissões MAUI

BarcodeScanning.Native.Maui adiciona permissões de câmera automaticamente aos manifestos de Android e iOS como parte da configuração do pacote. Com o IronBarcode usando MediaPicker, as permissões de câmera padrão do MAUI em AndroidManifest.xml e Info.plist são necessárias — as mesmas permissões que qualquer app MAUI precisa para MediaPicker.CapturePhotoAsync(). Essas permissões geralmente já estão presentes em projetos MAUI que utilizam a câmera para qualquer finalidade.