Architecture CameraBarcodeReaderView

Le contrôle CameraBarcodeReaderView est le composant central de ZXing.Net.MAUI. Il est déclaré en XAML et configuré via une liaison BarcodeReaderOptions. Chaque page l'utilisant doit implémenter OnAppearing et OnDisappearing pour gérer l'état 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;  // Non 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;  // Non 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 ' Non 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

Chaque page de numérisation d'une application ZXing .NET.MAUI contient ce modèle de cycle de vie. L'absence de IDisposable signifie que l'état de la caméra doit être géré manuellement via le drapeau IsDetecting plutôt que via le modèle standard Dispose.

Comparaison détaillée des fonctionnalités

Approche ZXing .NET.MAUI

ZXing.Net.MAUI est conçu autour des API de caméra plateforme pour iOS et Android. Windows MAUIprend uniquement en charge la génération des codes-barres — le balayage par caméra n'est pas implémenté et n'est pas sur une feuille de route publique. Cela reflète le choix architectural de construire la bibliothèque autour d'un contrôle de viseur de caméra en direct dont les implémentations de plateforme ont été écrites uniquement pour les systèmes d'exploitation mobiles.

Un projet MAUI ciblant net8.0-windows10.0.19041.0 n'obtiendra pas de fonctionnalité de balayage de code-barres de ZXing.Net.MAUI. Mac Catalyst est présent dans la liste des frameworks cibles, mais le balayage sur cette cible n'est pas officiellement documenté. Les équipes qui commencent un projet avec des cibles uniquement mobiles et ajoutent plus tard une exigence Windows ou macOS trouveront que ZXing.Net.MAUI ne peut pas couvrir le balayage sur ces cibles. Le support iOS lui-même comporte une mise en garde : le problème GitHub #260 documente que les appareils iPhone 15 Pro et Pro Max sont affectés par un problème d'autofocus qui empêche la détection fiable.

Approche IronBarcode

IronBarcode prend en charge tous les frameworks cibles MAUI (iOS, Android, Windows et macOS) à partir du même package et du même modèle de code. L'approche MediaPicker + BarcodeReader.Read() s'adapte naturellement à chaque plateforme : sur mobile, MediaPicker.CapturePhotoAsync() invoque la caméra de l'appareil ; Sous Windows, cela correspond au sélecteur de fichiers, ce qui est un comportement approprié pour un environnement de bureau. Aucun code spécifique à la plateforme, aucune compilation conditionnelle et aucun enregistrement de service de plateforme ne sont requis.

Le modèle de code-barres MAUI pour ordinateurs de bureau Windows et macOS est géré par le même package que celui qui gère la numérisation mobile. Le même appel BarcodeReader.Read() qui s'exécute sur un appareil Android s'exécute également dans un point de terminaison ASP.NET Core, une application de bureau WinForms ou une fonction Azure — la cible de déploiement n'affecte pas l'API.

Approche ZXing .NET.MAUI

CameraBarcodeReaderView est un contrôle de caméra persistant intégré dans la page XAML. Il commence à traiter les images de la caméra lorsque IsDetecting est réglé sur true et s'arrête lorsqu'il est réglé sur false. L'absence d'une implémentation Dispose() signifie que les ressources de la caméra ne sont pas libérées via le modèle standard IDisposable lorsque l'utilisateur se déplace. L'atténuation documentée consiste à régler IsDetecting = false dans OnDisappearing() et à le restaurer dans 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

Ce modèle doit être répété sur chaque page contenant un scanner. Les applications qui naviguent fréquemment vers et depuis des pages de balayage peuvent accumuler des ressources caméra qui n'ont pas été entièrement libérées, ce qui est suivi dans le problème GitHub #164 avec des rapports de croissance de la mémoire et d'initialisation intermittente de la caméra au retour. Le problème de mise au point automatique de l'iPhone 15 Pro (problème GitHub #260) est une préoccupation distincte dans la couche d'intégration de la caméra : la vue de la caméra rend le code-barres clairement, mais le système de mise au point automatique ne se verrouille pas suffisamment net pour la détection sur le matériel iPhone16,1 et iPhone16,2. La solution de contournement documentée est d'indiquer à l'utilisateur d'ajuster manuellement la distance entre l'appareil et le code-barres.

Approche IronBarcode

IronBarcode n'intègre pas de contrôle de caméra dans la mise en page XAML. Au lieu de cela, l'appel MediaPicker.CapturePhotoAsync() ouvre l'interface utilisateur de la caméra du système lorsque l'utilisateur appuie sur un bouton. Le système de caméra gère la mise au point, l'exposition et l'autofocus indépendamment. Lorsque l'utilisateur confirme la capture, l'image résultante est transmise à BarcodeReader.Read() sous forme de tableau d'octets :

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

// Non 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}");
}

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

Imports IronBarCode
Imports System.IO

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

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

Le tutoriel sur le lecteur de codes-barres .NET MAUI couvre la configuration complète du projet pour ce modèle, y compris la configuration des autorisations pour iOS et Android. Puisqu'il n'y a pas de vue caméra persistante, il n'y a pas de ressource à libérer, pas d'état à basculer et pas de code de cycle de vie à maintenir d'une page à l'autre.

Approche ZXing .NET.MAUI

ZXing .NET.MAUI hérite des exigences de spécification de format de ZXing .NET . Avant le début du balayage, le développeur doit remplir BarcodeReaderOptions.Formats avec un masque binaire des valeurs enum BarcodeFormats qui doivent être détectées. Les formats non inclus dans cette liste ne seront pas détectés — silencieusement, sans erreur ni avertissement :

// 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 utilisateur pointe la caméra sur un GS1 DataBar, un code Aztec, un MaxiCode, ou tout format qui n'a pas été déclaré dans les options, le balayage ne renvoie aucun résultat sans émettre d'erreur. La caméra rend le code-barres et aucun résultat n'est renvoyé à l'application. Dans un environnement contrôlé — un entrepôt où chaque article porte une étiquette Code128 —, cela est gérable. Dans les déploiements où les formats de code-barres sont déterminés par des fournisseurs externes, des clients, ou des systèmes tiers, l'absence d'un chemin de secours devient un problème de support récurrent.

Approche IronBarcode

IronBarcode effectue une détection automatique du format pour tous les formats pris en charge, sans aucune préconfiguration. BarcodeReader.Read() analyse l'image et renvoie les résultats pour chaque code-barres qu'il identifie, quel que soit le format. Aucune liste BarcodeReaderOptions n'est requise :

// 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 un réglage des performances est nécessaire dans un scénario contrôlé où un seul format est attendu, des indications de format peuvent être transmises en option, mais elles ne sont jamais requises pour une détection correcte. Un code-barres dont le format n'a pas été prévu par le développeur sera tout de même détecté et renvoyé.

Approche ZXing .NET.MAUI

ZXing .NET.MAUI est une bibliothèque de contrôle de caméra. Il ne dispose d'aucune API pour la lecture des codes-barres à partir des chemins de fichiers, des tableaux d'octets transmis directement depuis le stockage ou des documents PDF. Le contrôle CameraBarcodeReaderView nécessite un flux de caméra en direct ; Il n'existe pas de méthode statique qui accepte un chemin de fichier et renvoie des résultats de code-barres. Les équipes qui doivent lire les codes-barres à partir de fichiers PDF téléchargés, de systèmes de gestion de documents ou de files d'attente de traitement d'images par lots ne peuvent pas utiliser ZXing .NET.MAUI pour ces scénarios et doivent introduire une bibliothèque distincte.

Approche IronBarcode

IronBarcode lit les codes-barres à partir de n'importe quelle source via la même méthode BarcodeReader.Read(). Il accepte les chemins de fichiers, les tableaux d'octets, les flux et les documents PDF. L'analyse des PDF est native — Code-barres IronBarcode traite directement les pages PDF sans étape de rastérisation intermédiaire :

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

Le flux de travail complet de lecture des codes-barres PDF, y compris les documents multipages et les formats de codes-barres mixtes sur plusieurs pages, est documenté dans le guide de lecture des codes-barres à partir de PDF . Cela couvre les factures d'expédition, les billets numériques, les flux de travail de gestion de documents et les scénarios de traitement par lots que l'architecture uniquement basée sur la caméra de ZXing .NET.MAUI ne peut pas prendre en charge.

Configuration requise pour Windows MAUI

Le déclencheur le plus courant d'une réévaluation est l'ajout d'une cible Windows MAUIà un projet qui a débuté uniquement pour iOS et Android. Les équipes MAUI commencent souvent par des versions optimisées pour les mobiles et étendent ensuite leur utilisation aux ordinateurs de bureau à mesure que les besoins évoluent. Lorsque cette expansion aura lieu, ZXing .NET.MAUI ne propose aucune solution de rechange : la plateforme Windows n'est pas implémentée et ne figure pas dans la feuille de route publique. L'équipe doit soit accepter que la lecture de codes-barres ne soit pas disponible sous Windows, soit remplacer la bibliothèque. Étant donné que le remplacement implique de toute façon une modification structurelle du schéma de numérisation, les équipes effectuent généralement le changement simultanément sur toutes les plateformes.

Compatibilité matérielle de génération actuelle

Le problème de mise au point automatique de l'iPhone 15 Pro (problème GitHub #260) est une réelle considération pour toute équipe qui expédie un scanner de code-barres en production aux utilisateurs iOS. Les iPhone 15 Pro et Pro Max sont courants dans le segment des consommateurs qui s'attendent à une expérience d'application raffinée, et une solution de contournement demandant aux utilisateurs d'ajuster leur distance par rapport à un code-barres est une régression UX notable par rapport aux anciens matériels iPhone. Les équipes qui rencontrent ce problème en QA, ou reçoivent des rapports de support des utilisateurs iPhone 15 Pro, font face à un choix entre rester sur une bibliothèque où aucune solution n'est actuellement disponible ou migrer vers une approche qui n'est pas affectée par le modèle de mise au point de vue de la caméra.

Traitement des fichiers et des documents

Les exigences en matière de lecture de codes-barres se limitent rarement à la capture vidéo en direct. Les applications qui débutent comme scanners d'inventaire s'étendent fréquemment pour inclure la lecture de codes-barres à partir de fichiers PDF téléchargés, le traitement des factures d'expédition ou la gestion des billets numériques provenant de pièces jointes aux courriels. ZXing .NET.MAUI ne dispose d'aucune API pour aucun de ces scénarios. Lorsqu'une exigence produit est ajoutée au backlog et implique la lecture d'un code-barres à partir d'un fichier ou d'un document, les équipes utilisant ZXing .NET.MAUI doivent introduire une bibliothèque distincte pour la gérer. Si l'équipe utilise déjà Code-barres IronBarcode pour l'un de ces scénarios basés sur des fichiers, l'intégration de la numérisation par caméra MAUI dans la même bibliothèque devient la prochaine étape naturelle.

Exigences de stabilité de la production

La désignation pré-1.0 à la version v0.7.4 — bien que le package lui-même soit une version NuGet stable — a des implications pour les équipes soumises à l'analyse de la composition logicielle, aux audits de dépendance, ou aux processus d'approbation internes. Certains environnements d'entreprise exigent que les dépendances de production portent une version stable 1.0+, un contrat de support commercial, ou les deux. ZXing.Net.MAUI est maintenu par la communauté et pré-1.0, ce qui est adapté aux outils internes et aux prototypes mais ajoute des étapes de révision dans les applications destinées aux clients où le scanner de code-barres est un flux de travail principal. L'absence de niveau de support payant signifie que tout bug critique dépend de la disponibilité du mainteneur communautaire.

Modèle CameraBarcodeReaderView vers MediaPicker

Le contrôle XAML CameraBarcodeReaderView et sa déclaration de namespace xmlns:zxing sont entièrement supprimés. Dans chaque fichier XAML contenant une vue de scan, le remplacement est un contrôle Button qui invoque MediaPicker.CapturePhotoAsync() dans son gestionnaire Clicked. Le modèle orienté événement — où les résultats arrivent via BarcodesDetected — est remplacé par la lecture de la valeur de retour de BarcodeReader.Read() directement dans le gestionnaire asynchrone.

Détection de la suppression du cycle de vie

Chaque OnAppearing et OnDisappearing substitution qui existe uniquement pour basculer CameraView.IsDetecting peut être supprimée. Si ces substitutions contiennent d'autres logiques de cycle de vie de la page, les lignes IsDetecting sont supprimées et la logique restante est préservée. Il n'y a pas d'équivalent Code-barres IronBarcode à IsDetecting car il n'y a pas d'état de caméra persistant à gérer entre les navigations de pages.

Suppression de l'enregistrement UseBarcodeReader()

ZXing.Net.MAUI nécessite un appel builder.UseBarcodeReader() unique dans MauiProgram.cs pour enregistrer ses services de caméra de plateforme. Code-barres IronBarcode ne nécessite aucun enregistrement MauiProgram.cs. La ligne UseBarcodeReader() est supprimée, et l'importation de namespace using ZXing.Net.Maui; qui la prend en charge est également supprimée avec la désinstallation du package.