Leitor de código de barras MAUI com IronBarcode: Guia passo a passo

Entendendo Como o IronBarcode se Encaixa no MAUI

.NET MAUI lhe dá uma única base de código que tem como alvo Android, iOS, macOS, e Windows. O desafio com a leitura de códigos de barras neste ambiente é que cada plataforma lida com o acesso à câmera de maneira diferente. IronBarcode aborda isso trabalhando na camada de processamento de imagem -- você captura a imagem através do MediaPicker do MAUI, depois passa os bytes para o IronBarcode para análise.

Essa separação de preocupações mantém seu código limpo e evita SDKs de código de barras específicos de plataforma. O modelo de processamento offline do IronBarcode também significa que os dados de código de barras nunca saem do dispositivo, o que importa para aplicativos em indústrias regulamentadas.

Formatos de Código de Barras Suportados

IronBarcode lê uma ampla gama de formatos, incluindo:

Instalando IronBarcode via NuGet

Abra o Console do Gerenciador de Pacotes NuGet e execute:

Install-Package BarCode

Alternativamente, clique com o botão direito no seu projeto no Solution Explorer, escolha 'Gerenciar Pacotes NuGet', procure IronBarCode e instale a versão estável mais recente. Para projetos .NET MAUI especificamente, o pacote NuGet do IronBarcode inclui todas as dependências nativas necessárias.

Ativando sua Licença

Após a instalação, ative o IronBarcode com sua chave de licença no início do ciclo de vida da aplicação. O melhor lugar é em MauiProgram.cs antes de o construtor do aplicativo rodar:

IronBarCode.License.LicenseKey = "YOUR-LICENSE-KEY";

IronBarCode.License.LicenseKey = "YOUR-LICENSE-KEY";

Obtenha uma chave de licença de teste gratuito no site da IronSoftware. As chaves de teste permitem avaliar todos os recursos sem restrições de tempo durante o desenvolvimento, embora o resultado possa incluir uma marca d'água de teste até que você aplique uma licença completa.

Permissões Android

Edite Platforms/Android/AndroidManifest.xml para declarar acesso à câmera:

<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera" android:required="true" />
<uses-feature android:name="android.hardware.camera.autofocus" />

<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera" android:required="true" />
<uses-feature android:name="android.hardware.camera.autofocus" />

A entrada android.permission.CAMERA solicita permissão de tempo de execução do usuário. As declarações uses-feature informam a Google Play Store que seu aplicativo requer hardware de câmera e capacidade de autofoco. Sem isso, dispositivos Android podem conceder a solicitação de permissão mas ainda bloquear o acesso à câmera internamente.

Para Android 13 e posterior (nível de API 33+), você também pode precisar lidar com permissões de mídia granulares em seu MainActivity.cs usando ActivityCompat.RequestPermissions. A abstração MediaPicker do MAUI lida com a maior parte disso automaticamente, mas é recomendado testar em dispositivos físicos antes do lançamento.

Permissões iOS

Modifique Platforms/iOS/Info.plist para incluir a descrição do uso da câmera:

<key>NSCameraUsageDescription</key>
<string>This app requires camera access to scan barcodes</string>

<key>NSCameraUsageDescription</key>
<string>This app requires camera access to scan barcodes</string>

iOS exige uma explicação legível para cada permissão sensível à privacidade. O processo de revisão da App Store da Apple rejeitará seu aplicativo se esta descrição estiver ausente ou vaga. O texto aparece no diálogo de permissão do sistema mostrado ao usuário na primeira vez que o aplicativo solicita acesso à câmera.

Para iPadOS, também considere adicionar NSPhotoLibraryUsageDescription se planejar permitir que os usuários escaneiem códigos de barras de fotos salvas, além da câmera ao vivo.

Windows e macOS

Para os alvos Windows Desktop e macOS, as permissões de acesso à câmera são gerenciadas através do manifesto do aplicativo e arquivos de direitos, respectivamente. O framework MAUI lida com a maior parte disso no nível do template, mas verifique se Package.appxmanifest no Windows inclui a capacidade do dispositivo webcam.

Adicionando Feedback de Status do Escaneamento

Para uma experiência aprimorada, considere envolver os botões de escaneamento em um ActivityIndicator que apareça enquanto o processamento está em andamento. A API assíncrona do IronBarcode torna isso simples -- você pode definir IsRunning = true antes de chamar BarcodeReader.ReadAsync e redefini-lo no bloco finally.

Testando Sua Implementação de Escaneamento

Com o código implementado, você pode testar com um código de barras padrão:

Após o escaneamento, o valor decodificado aparece na tela:

Alvejando Tipos Específicos de Código de Barras

Especificar os tipos exatos de código de barras que você espera reduz drasticamente o tempo de processamento porque o IronBarcode pula verificações de formato desnecessárias:

var options = new BarcodeReaderOptions
{
    Speed = ReadingSpeed.Balanced,
    ExpectMultipleBarcodes = true,
    ExpectBarcodeTypes = BarcodeEncoding.QRCode | BarcodeEncoding.Code128
};

var results = await BarcodeReader.ReadAsync(bitmap, options);

var options = new BarcodeReaderOptions
{
    Speed = ReadingSpeed.Balanced,
    ExpectMultipleBarcodes = true,
    ExpectBarcodeTypes = BarcodeEncoding.QRCode | BarcodeEncoding.Code128
};

var results = await BarcodeReader.ReadAsync(bitmap, options);

Definir ExpectMultipleBarcodes = true instrui o IronBarcode a continuar escaneando após encontrar o primeiro resultado, o que é essencial para fluxos de trabalho de armazém onde um único talão de embalagem pode conter uma dúzia de códigos de barras.

Opções de Velocidade de Leitura

O enum ReadingSpeed oferece quatro níveis: ExtremeDetail, Detailed, Balanced, e QuickScan. Use QuickScan para cenários de alto volume onde os códigos de barras são limpos e bem iluminados. Mude para Detailed ou ExtremeDetail ao escanear de capturas de câmera de baixa resolução ou etiquetas que foram parcialmente danificadas.

Para mais sobre ajustar BarcodeReaderOptions, incluindo filtros de correção de imagem e limiares de confiança, a documentação fornece exemplos detalhados.

Correção de Imagem e Pré-processamento

IronBarcode inclui correção de imagem embutida que lida automaticamente com códigos de barras rotacionados, inclinados ou mal iluminados. Você também pode aplicar filtros de pré-processamento manualmente através de BarcodeReaderOptions.ImageFilters:

var options = new BarcodeReaderOptions
{
    Speed = ReadingSpeed.Detailed,
    ImageFilters = new ImageFilterCollection
    {
        new SharpenFilter(),
        new ContrastFilter(1.2f)
    }
};

var options = new BarcodeReaderOptions
{
    Speed = ReadingSpeed.Detailed,
    ImageFilters = new ImageFilterCollection
    {
        new SharpenFilter(),
        new ContrastFilter(1.2f)
    }
};

Os filtros de pré-processamento são particularmente úteis quando a aplicação alvo dispositivos Android mais antigos com sensores de câmera de baixa qualidade, ou quando os usuários provavelmente fotografarão códigos de barras em condições de iluminação subótimas, como armazéns ou ambientes externos.

Câmera Não Abre

Se a câmera falhar ao iniciar, verifique se as permissões estão corretamente declaradas em ambos AndroidManifest.xml e Info.plist. Em seguida, faça o redeploy do aplicativo a partir de uma compilação limpa em vez de um hot reload. No Android, também verifique se o dispositivo de teste usa uma configuração de câmera não padrão -- alguns dispositivos com múltiplas câmeras exigem seleção explícita da lente.

No simulador, MediaPicker.CapturePhotoAsync() não é suportado. Sempre teste os recursos da câmera em um dispositivo físico. O emulador suporta PickPhotoAsync para seleção de galeria, que você pode usar para testes básicos de interface com imagens pré-carregadas.

Precisão de Escaneamento Ruim

Se o IronBarcode não retornar resultados ou valores incorretos, tente estes ajustes:

• Aumente o Speed para ReadingSpeed.Detailed ou ExtremeDetail
• Adicione SharpenFilter e ContrastFilter ao pipeline de filtro de imagem
• Certifique-se de que a resolução da imagem capturada seja pelo menos 720p; resoluções mais baixas causam falhas de detecção em formatos densos como Data Matrix
• Verifique se o tipo de código de barras está incluído na sua máscara ExpectBarcodeTypes

O guia de solução de problemas do IronBarcode abrange etapas de diagnóstico adicionais para problemas específicos de formato.

Gerenciamento de memória

Imagens grandes de câmera consomem memória significativa quando carregadas em MemoryStream. Sempre use instruções using em todos os objetos de stream para garantir descarte. Para fluxos de trabalho de escaneamento contínuo onde os usuários escaneiam vários itens em sequência, também chame bitmap.Dispose() explicitamente após o processamento em vez de esperar pelo coletor de lixo.

Em dispositivos Android com espaço de heap limitado, considere reduzir a amostra da imagem antes de passá-la para o IronBarcode se os escaneamentos forem de códigos de barras limpos e de alto contraste que não exigem resolução total para decodificação precisa.

Comportamento Específico de Plataforma no iOS

No iOS, a primeira vez que seu aplicativo solicita permissão para a câmera, o sistema exibe um diálogo único. Se o usuário negar, chamadas subsequentes para CapturePhotoAsync lançarão um PermissionException. Lide com este caso direcionando o usuário para Configurações, o que você pode fazer com AppInfo.ShowSettingsUI().

Confirme que NSCameraUsageDescription está presente em Info.plist antes de enviar para a App Store. A ausência de strings de privacidade causa rejeição automática sem uma explicação detalhada da equipe de revisão. Revise as Diretrizes de Interface Humana da Apple para acesso à câmera para melhores práticas sobre o momento e a mensagem de solicitação de permissão.