Wzór skanowania na żywo z kamery

Cały wzorzec API BarcodeScanning.Native.Maui to kontrolka XAML połączona z procedurą obsługi zdarzeń w języku 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

Ten element sterujący zapewnia użytkownikom podgląd w czasie rzeczywistym osadzony na stronie MAUI. Wykrywanie kodów kreskowych odbywa się ciągle, gdy strumień kamery jest aktywny. UX jest dobrze dostosowany do aplikacji konsumenckich, gdzie "celuj i skanuj" jest główną interakcją. Ograniczenie to, że jest to jedyna interakcja, którą biblioteka obsługuje — wymagania, które wykraczają poza wykrywanie kodów kreskowych z transmisji na żywo w kontekście MAUI, wykraczają poza jej zakres.

Szczegółowe porównanie funkcji

Podejście BarcodeScanning.MAUI

BarcodeScanning.Native.Maui wykorzystuje natywny proces wykrywania aparatu na każdej platformie. Na Androidzie ML Kit przetwarza klatki; na iOS i macOS, ramy Apple'a Vision przetwarzają klatki; na Windows ZXingCpp przetwarza klatki. Biblioteka udostepnia to jako kontrole MAUI CameraView ze zdarzeniem OnDetectionFinished. Kod aplikacji nigdy nie obsługuje bezpośrednio bajtów obrazu — obsługuje jedynie wykryte wartości BARCODE, które pojawiają się w zdarzeniu.

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

Konsekwencją tego projektu jest brak innego punktu wejścia. Kamera nie jest opcjonalna — jest to jedyne źródło danych, jakie biblioteka rozpoznaje. Serwer, plik, PDF lub jakikolwiek host bez MAUI nie ma ścieżki dostępu do biblioteki.

Podejście IronBarcode

IronBarcode otrzymuje dane obrazu przez swoja statyczna metode BarcodeReader.Read(). Użytkownik dostarcza dane — z dowolnego źródła — a biblioteka je dekoduje. Na MAUI, dane pochodza z MediaPicker; na serwerze, pochodzi z przesłania formularza; w aplikacji desktopowej pochodzi z okna dialogowego plików.

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

Ten kod działa identycznie we wszystkich celach MAUI, które mogą przechwycić obraz. Dla uzytku po stronie serwera ta sama metoda BarcodeReader.Read() akceptuje tablice bajtowa przeslanego pliku lub sciezke do PDF. Dokumentacja IronBarcode obejmuje wszystkie obsługiwane typy danych wejściowych.

Podejście BarcodeScanning.MAUI

BarcodeScanning.Native.Maui wspiera wszystkie cztery cele MAUI (iOS, Android, Windows od wersji 3.0.1 i macOS Catalyst), ale każdy cel używa innego silnika rozpoznawania: Apple Vision na iOS i macOS, Google ML Kit na Androidzie i ZXingCpp na Windows. Zakres symbologii i zachowanie dekodowania różnią się w zależności od trzech silników, co oznacza, że kod kreskowy, który niezawodnie dekoduje się na jednej platformie, może zachowywać się inaczej na innej. Poza MAUI - ASP.NET, konsola, WPF, WinForms, Blazor Server, Azure Functions - biblioteka nie ma implementacji. Zespoły, które potrzebują logiki kodów kreskowych zarówno w aplikacji MAUI, jak i usłudze backendu, muszą używać innej biblioteki dla kodu poza MAUI.

Podejście IronBarcode

Wywolanie BarcodeReader.Read() w IronBarcode wykorzystuje ten sam zarzadzany silnik na kazdym wspieranym celu, wiec zachowanie jest spójne w calym Windows, Linux, macOS, ASP.NET i dowolnym celu MAUI, ktory moze zarejestrowac obraz i przekazac go do czytnika. Nie ma blokow #if WINDOWS, ladowania warunkowego zaleznosci czy potrzebnych implementacji szkieletowych. W przypadku plików i dokumentów PDF wzór jest również spójny:

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")

Przewodnik integracji IronBarcode MAUI zawiera kompletne instrukcje konfiguracji dla wszystkich celów MAUI.IronBarcode obsługuje również wdrażanie po stronie serwera w środowiskach ASP.NET, Docker, Azure Functions i AWS Lambda, gdzie BarcodeScanning.Native.Maui nie ma żadnej ścieżki.

Podejście BarcodeScanning.MAUI

Na iOS BarcodeScanning.Native.Maui opiera się na wykrywaniu (Apple Vision), które może zwrócić 13 cyfr dla kodów kreskowych UPC-A. UPC-A to format 12-cyfrowy; dodatkowa zerowa cyfra na początku odpowiada kodowaniu EAN-13. Biblioteka przekazuje tę surową wartość i aplikacje normalizują ją w razie potrzeby. Aplikacje, które przechowują wartości UPC-A w bazie danych bez normalizacji, mogą gromadzić rekordy z wiodącym zerem.

Opisana poprawka sprawdza format i przycina wartość:

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

Sprawdzenie formatu jest konieczne, aby wartości EAN-13 zaczynające się od 0 nie były obcinane przez pomyłkę. PDF417 jest oddzielnie opisany w problemach na GitHubie jako 'bardzo problematyczny — większość skanów nigdy nie występuje' w silnikach iOS/Android, co jest istotne dla etykiet wysyłkowych, praw jazdy i kart pokładowych.

Podejście IronBarcode

IronBarcode zwraca standardową 12-cyfrową wartość UPC-A przez swój zarządzany silnik. PDF417 jest obsługiwanym formatem. Funkcja generowania jest również dostępna za pośrednictwem API 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")

Dla aplikacji, w których dokładność danych kodów kreskowych bezpośrednio wpływa na wyszukiwania w magazynie, transakcje w punktach sprzedaży lub integracje łańcucha dostaw, spójna obsługa formatu przez IronBarcode zmniejsza potrzebę platformowo-specyficznej normalizacji. Dokumentacja dotycząca odczytu kodów kreskowych IronBarcode szczegółowo opisuje zachowanie w zależności od formatu.

Spójność silnika międzyplatformowego staje się wymogiem

Aplikacje MAUI, które celują w iOS, Android, Windows i macOS, korzystają z trzech różnych silników rozpoznawania, gdy używają BarcodeScanning.Native.Maui: Apple Vision (iOS/macOS), Google ML Kit (Android), i ZXingCpp (Windows). Każdy silnik ma własny zakres symbologii i zachowanie dekodowania, więc ten sam kod kreskowy może dekodować się inaczej na różnych platformach — a aplikacje na ogół dodają warstwy normalizacji, aby pokryć różnice. Kiedy nakład pracy nad utrzymaniem rośnie, lub kiedy QA zgłasza regresje międzyplatformowe związane z różnicami w silnikach, zespoły czasami migrują warstwę kodów kreskowych do pojedynczego zarządzanego silnika, który zachowuje się w ten sam sposób na wszystkich celach.

Dodano wymagania dotyczące przesyłania plików lub przetwarzania plików PDF

Aplikacje mobilne często zaczynają od skanowania na żywo za pomocą kamery jako jedynej metody wprowadzania danych, a później rozszerzają się, aby akceptować przesłane obrazy lub dokumenty. Gdy użytkownik potrzebuje zeskanować kod kreskowy z zdjęcia w swojej galerii, z obrazu otrzymanego przez email lub z pliku PDF zawierającego manifesty przesyłek lub bilety pokładowe, BarcodeScanning.Native.Maui nie ma ścieżki kodu dla tych wejść. Zespoły, które stają przed tą granicą wymogu, muszą dokonać wyboru: dodać drugą bibliotekę kodów kreskowych obok BarcodeScanning.Native.Maui dla plików i wejść PDF, lub przejść na jedną bibliotekę, która obsługuje wszystkie typy wejść. Zarządzanie dwoma pakietami kodów kreskowych z różnymi API i typami wyników dodaje długoterminową złożoność, której unika rozwiązanie z jednym pakietem.

Wprowadzenie przetwarzania BarCodes po stronie serwera

Aplikacje skanujące kody kreskowe na urządzeniach mobilnych często wykorzystują komponent po stronie serwera — punkt końcowy API ASP.NET, który weryfikuje kody kreskowe, zadanie w tle przetwarzające pliki PDF lub funkcję w chmurze, która wyodrębnia numery śledzenia z przesłanych dokumentów. BarcodeScanning.Native.Maui jest biblioteką kontrolki UI MAUI; nie ma implementacji po stronie serwera. Zespół, który potrzebuje tej samej logiki odczytu BarCode'ów zarówno na urządzeniach mobilnych, jak i na serwerze, musi użyć innej biblioteki po stronie serwera. Kiedy pojawia się wymóg po stronie serwera, zespoły często oceniają, czy konsolidacja do jednej biblioteki, która obejmuje zarówno urządzenia mobilne, jak i serwer, jest lepszym rozwiązaniem niż utrzymywanie dwóch oddzielnych implementacji.

Normalizacja danych UPC-A staje się problemem

Zachowanie 13-cyfrowego kodu UPC-A w systemie iOS nie zawsze jest wykrywane podczas tworzenia oprogramowania. Kody kreskowe UPC-A skanowane podczas tworzenia mogą wydawać się działać poprawnie, ale wiodące zero z ram Apple'a Vision może pojawić się w bazie danych, gdy normalizacja brakuje. Zespoły, które odkrywają 13-cyfrowe wartości UPC-A w rekordach inwentarza, systemach punktów sprzedaży lub integracjach łańcucha dostaw, mogą potrzebować zarówno poprawki kodu, jak i kroku korekty danych. Dodanie opisanej normalizacji obsługuje nowe skany; migracja do biblioteki z spójnym wyjściem UPC-A jest czasami preferowana jako długoterminowe rozwiązanie.

Wymagane skanowanie dokumentów PDF417

PDF417 to format BARCODE stosowany w etykietach wysyłkowych, prawach jazdy i kartach pokładowych w Ameryce Północnej. Są to typowe cele skanowania w aplikacjach logistycznych, do weryfikacji tożsamości i aplikacjach turystycznych. GitHub issue tracker BarcodeScanning.Native.Maui dokumentuje PDF417 jako 'bardzo problematyczny — większość skanów nigdy nie występuje' w silnikach iOS/Android. Dla aplikacji, w których niezawodność PDF417 stanowi wymóg funkcjonalny, zespoły często oceniają alternatywne biblioteki.

Zdarzenie kamery do MediaPicker i odczyt statyczny

Podstawowa zmiana strukturalna w migracji polega na zastapieniu wzorca ciaglego zdarzenia kamery przez MediaPicker z przechwyceniem nastepowanym przez BarcodeReader.Read(). Obsluga zdarzen OnDetectionFinished, kontrolka XAML CameraView, oraz deklaracja przestrzeni nazw XML scanner: sa usuwane. Zamiast tego, przycisk wyzwala MediaPicker.CapturePhotoAsync(), a uzyskane bajty zdjecia sa przekazywane do BarcodeReader.Read(). Zmienia to wrażenia użytkownika z podglądu na żywo na ekran aparatu systemowego — odpowiedni dla większości zastosowań biznesowych.

Zmiany w marshalingu wątków

BarcodeScanning.Native.Maui uruchamia OnDetectionFinished na watku w tle, wiec wszystkie istniejace obslugi ktore aktualizuja elementy interfejsu, owijaja swoje aktualizacje w MainThread.BeginInvokeOnMainThread(). Za pomoca wzorca MediaPicker + async uzywanego przez IronBarcode, kontynuacja po await zwraca sie w kontekscie wywolujacym, ktory jest zazwyczaj glownym watkiem. W wiekszosci przypadków owiniecia MainThread.BeginInvokeOnMainThread() moga byc usuniete, upraszczajac kod obslugi zdarzen.

Usuwanie normalizacji UPC-A

Kazda baza kodowa ktora obslugiwala zachowanie 13-cyfrowego iOS UPC-A w BarcodeScanning.Native.Maui bedzie miala kod, ktory sprawdza BarcodeFormats.Upca i wywoluje Substring(1) aby usunac wiodace zero. Ten kod powinien zostać usunięty po migracji —IronBarcode zwraca standardową 12-cyfrową wartość, a pozostawienie normalizacji w miejscu nieprawidłowo usunąłoby pierwszą cyfrę z prawidłowych odczytów UPC-A.

Uprawnienia MAUI

BarcodeScanning.Native.Maui dodaje uprawnienia kamery do manifestow Androida i iOS automatycznie jako czesc ustawienia pakietu. Z IronBarcode uzywajac MediaPicker, wymagane sa standardowe uprawnienia kamery MAUI w AndroidManifest.xml i Info.plist — te same uprawnienia, ktore potrzebuje dowolna aplikacja MAUI dla MediaPicker.CapturePhotoAsync(). Uprawnienia te są zazwyczaj już obecne w projektach MAUI, które wykorzystują kamerę w dowolnym celu.