CameraBarcodeReaderView 아키텍처

CameraBarcodeReaderView 컨트롤은 ZXing.Net.MAUI의 중심 구성 요소입니다. XAML에서 선언되고 BarcodeReaderOptions 바인딩을 통해 구성됩니다. 해당 기능을 사용하는 모든 페이지는 OnAppearing 및 OnDisappearing 재정의를 구현하여 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;  // 아니요 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;  // 아니요 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 ' 아니요 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

ZXing .NET.MAUI 애플리케이션의 모든 스캔 페이지에는 이러한 라이프사이클 기본 코드가 포함되어 있습니다. IDisposable의 부재는 카메라 상태를 표준 Dispose 패턴 대신 IsDetecting 플래그를 통해 수동으로 관리해야 함을 의미합니다.

상세 기능 비교

ZXing .NET.MAUI 접근 방식

ZXing.Net.MAUI는 iOS 및 Android의 플랫폼 카메라 API를 중심으로 설계되었습니다. Windows MAUI는 바코드 생성만을 지원하며, 카메라 스캔은 구현되지 않았으며 공개 로드맵에 포함되어 있지 않습니다. 이는 플랫폼 구현이 모바일 운영 체제에서만 작성된 라이브 카메라 뷰파인더 컨트롤을 중심으로 라이브러리를 구축하는 아키텍처적 선택을 반영합니다.

net8.0-windows10.0.19041.0를 타겟으로 하는 MAUI 프로젝트는 ZXing.Net.MAUI에서 바코드 스캔 기능을 제공받지 않습니다. Mac Catalyst는 대상 프레임워크 목록에 존재하지만, 해당 대상에서의 스캔은 공식 문서화되어 있지 않습니다. 모바일 전용 대상을 타겟으로 프로젝트를 시작한 후 Windows 또는 macOS 요구 사항을 나중에 추가하는 팀은 ZXing.Net.MAUI가 해당 대상에서 스캔을 다룰 수 없다는 것을 발견할 것입니다. iOS 지원 자체는 경고를 수반합니다: GitHub 이슈 #260은 iPhone 15 Pro와 Pro Max 장치가 신뢰할 수 있는 감지를 방해하는 오토포커스 문제의 영향을 받는다고 문서화하고 있습니다.

IronBarcode 접근법

IronBarcode 동일한 패키지와 동일한 코드 패턴을 사용하여 모든 MAUI 대상 프레임워크(iOS, Android, Windows 및 macOS)를 지원합니다. MediaPicker + BarcodeReader.Read() 접근 방식은 각각의 플랫폼에 자연스럽게 맵핑됩니다: 모바일에서는 MediaPicker.CapturePhotoAsync()이 기기 카메라를 호출합니다; 윈도우에서는 파일 선택기에 매핑되는데, 이는 데스크톱 환경에 적합한 동작입니다. 플랫폼별 코드, 조건부 컴파일, 플랫폼 서비스 등록이 필요하지 않습니다.

Windows 및 macOS용 MAUI 데스크톱 바코드 패턴은 모바일 스캔을 처리하는 동일한 패키지에 포함되어 있습니다. 안드로이드 기기에서 실행되는 동일한 BarcodeReader.Read() 호출이 ASP.NET Core 엔드포인트, WinForms 데스크톱 응용프로그램, 또는 Azure Function에서도 실행됩니다. 배포 대상은 API에 영향을 미치지 않습니다.

ZXing .NET.MAUI 접근 방식

CameraBarcodeReaderView은 XAML 페이지에 삽입된 지속적인 카메라 컨트롤입니다. IsDetecting가 true로 설정되면 카메라 프레임을 처리하기 시작하고, false로 설정되면 중지합니다. Dispose() 구현의 부재는 사용자가 다른 페이지로 이동할 때 표준 IDisposable 패턴을 통해 카메라 리소스가 해제되지 않음을 의미합니다. 문서화된 완화 조치는 OnDisappearing()에서 IsDetecting = false를 설정하고 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

이 패턴은 스캐너가 있는 모든 페이지에서 반복되어야 합니다. 스캔 페이지를 자주 탐색하는 애플리케이션은 아직 완전히 해제되지 않은 카메라 자원을 축적할 수 있으며, 이는 GitHub issue #164에서 보고된 메모리 증가 및 다시 돌아갈 때 간헐적인 카메라 초기화와 함께 추적됩니다. iPhone 15 Pro 자동 초점 문제 (GitHub 문제 #260)는 카메라 통합 계층 내의 별도의 문제입니다: 카메라 뷰는 바코드를 명확하게 렌더링하지만, 자동 초점 시스템이 iPhone16,1 및 iPhone16,2 하드웨어에서 감지를 위한 충분히 명확한 잠금을 설정하지 않습니다. 기록된 해결책은 사용자가 기기와 바코드 사이의 거리를 수동으로 조정하라는 지시를 하는 것입니다.

IronBarcode 접근법

IronBarcode XAML 레이아웃에 카메라 컨트롤을 포함하지 않습니다. 대신, 사용자 버튼을 탭하면 MediaPicker.CapturePhotoAsync() 호출이 시스템 카메라 UI를 엽니다. 시스템 카메라는 초점, 노출 및 자동 초점을 독립적으로 처리합니다. 사용자가 캡처를 확인하면, 결과 이미지는 바이트 배열로 BarcodeReader.Read()에 전달됩니다:

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

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

// 아니요 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

' 아니요 OnAppearing or OnDisappearing needed — no camera state to manage

.NET MAUI 바코드 스캐너 튜토리얼은 iOS 및 Android 모두에 대한 권한 구성을 포함하여 이 패턴에 대한 전체 프로젝트 설정 방법을 다룹니다. 카메라 뷰가 고정되어 있지 않기 때문에 해제해야 할 리소스도 없고, 상태를 전환해야 할 필요도 없으며, 페이지 간에 유지 관리해야 할 수명 주기 관련 코드가 없습니다.

ZXing .NET.MAUI 접근 방식

ZXing .NET.MAUI는 ZXing .NET 형식 사양 요구 사항을 상속합니다. 스캔을 시작하기 전에, 개발자는 탐지해야 할 BarcodeFormats 열거형 값의 비트마스크로 BarcodeReaderOptions.Formats을 채워야 합니다. 이 목록에 포함되지 않은 형식은 감지되지 않습니다. 오류나 경고 없이 조용히 감지됩니다.

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

사용자가 카메라를 GS1 데이터바, Aztec 코드, MaxiCode, 또는 옵션에 선언되지 않은 형식으로 포인팅하면, 스캔은 오류를 발생시키지 않고 결과를 반환하지 않습니다. 카메라는 바코드를 렌더링 하지만 애플리케이션으로 결과가 반환되지 않습니다. 통제된 환경, 즉 모든 품목에 Code128 라벨이 부착된 창고에서는 이러한 문제를 관리할 수 있습니다. 바코드 형식이 외부 공급업체, 고객 또는 제3자 시스템에 의해 결정되는 배포에서는, 후방 대체 경로의 부재가 반복적인 지원 문제가 됩니다.

IronBarcode 접근법

IronBarcode 사전 설정 없이 지원되는 모든 형식에 대해 자동 형식 감지를 수행합니다. BarcodeReader.Read()은 이미지를 분석하고 형식에 관계없이 식별한 모든 바코드에 대한 결과를 반환합니다. BarcodeReaderOptions 목록은 필요하지 않습니다:

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

특정 형식만 예상되는 제어된 시나리오에서 성능 조정이 필요한 경우 형식 힌트를 선택적으로 전달할 수 있지만, 정확한 감지를 위해 형식 힌트가 필수적인 것은 아닙니다. 개발자가 예상하지 못한 형식의 바코드라도 감지되어 반환됩니다.

ZXing .NET.MAUI 접근 방식

ZXing .NET.MAUI는 카메라 제어 라이브러리입니다. 이 소프트웨어는 파일 경로, 저장소에서 직접 전달된 바이트 배열 또는 PDF 문서에서 바코드를 읽는 API를 제공하지 않습니다. CameraBarcodeReaderView 컨트롤은 실시간 카메라 피드를 필요로 합니다; 파일 경로를 인수로 받아 바코드 결과를 반환하는 정적 메서드는 없습니다. 업로드된 PDF, 문서 관리 시스템 또는 일괄 이미지 처리 대기열에서 바코드를 읽어야 하는 팀은 이러한 시나리오에서 ZXing .NET.MAUI를 사용할 수 없으며 별도의 라이브러리를 도입해야 합니다.

IronBarcode 접근법

IronBarcode는 동일한 BarcodeReader.Read() 메서드를 통해 모든 출처로부터 바코드를 읽습니다. 파일 경로, 바이트 배열, 스트림 및 PDF 문서를 허용합니다. PDF 파싱은 기본적으로 지원됩니다.IronBarcode중간 래스터화 단계 없이 PDF 페이지를 직접 처리합니다.

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

여러 페이지로 구성된 문서와 페이지 간에 혼합된 바코드 형식을 포함한 전체 PDF 바코드 판독 워크플로는 "PDF에서 바코드 읽기" 가이드 에 설명되어 있습니다. 이는 ZXing .NET.MAUI의 카메라 전용 아키텍처로는 처리할 수 없는 배송 송장, 디지털 티켓, 문서 관리 워크플로 및 일괄 처리 시나리오를 포함합니다.

윈도우 MAUI 요구 사항

재평가를 촉발하는 가장 일반적인 요인은 iOS 및 Android 전용으로 시작한 프로젝트에 윈도우 MAUI 타겟이 추가되는 경우입니다. MAUI 팀은 일반적으로 모바일 우선 빌드로 시작하여 요구 사항이 발전함에 따라 데스크톱 대상으로 확장합니다. 그러한 확장이 이루어질 경우, ZXing .NET.MAUI는 해결책을 제시하지 못합니다. Windows 플랫폼은 구현되지 않았으며 공개 로드맵에도 포함되어 있지 않습니다. 따라서 개발팀은 Windows에서 바코드 스캔 기능을 사용할 수 없다는 사실을 받아들이거나 라이브러리를 교체해야 합니다. 교체 작업에는 스캔 패턴의 구조적 변경이 수반되므로, 일반적으로 팀은 모든 플랫폼에 대해 동시에 변경 작업을 진행합니다.

현세대 하드웨어 호환성

iPhone 15 Pro 오토포커스 문제 (GitHub issue #260)는 iOS 사용자에게 프로덕션 바코드 스캐너를 배포하는 팀에게 중요한 고려 사항입니다. iPhone 15 Pro와 Pro Max는 세련된 애플리케이션 경험을 기대하는 소비자 부문에서 일반적이며, 사용자가 바코드와의 거리를 조절하라는 해결책은 이전 아이폰 하드웨어에 비해 눈에 띄게 UX가 저하된 것입니다. QA에서 이 문제를 발견하거나 iPhone 15 Pro 사용자로부터 지원 보고서를 받는 팀은 현재 사용 가능한 해결책이 없는 라이브러리에 남아 있거나 카메라 뷰 포커스 모델에 영향을 받지 않는 접근 방식을 채택할지 선택하는 상황에 처하게 됩니다.

파일 및 문서 처리

바코드 스캔 요구사항은 실시간 카메라 캡처에만 국한되는 경우가 드뭅니다. 재고 스캐너로 시작된 애플리케이션은 업로드된 PDF에서 바코드를 읽거나, 배송 송장을 처리하거나, 이메일 첨부 파일에서 디지털 티켓을 처리하는 기능까지 확장되는 경우가 많습니다. ZXing .NET.MAUI는 이러한 시나리오에 대한 API를 제공하지 않습니다. 제품 요구 사항 중 파일이나 문서에서 바코드를 읽는 작업이 백로그에 추가되면 ZXing .NET.MAUI를 사용하는 팀은 이를 처리하기 위한 별도의 라이브러리를 도입해야 합니다. 팀에서 이미 파일 기반 시나리오에IronBarcode사용하고 있다면, MAUI 카메라 스캔 기능을 동일한 라이브러리에 통합하는 것이 자연스러운 다음 단계가 됩니다.

생산 안정성 요구 사항

v0.7.4에서의 1.0 이전 명시는 패키지 자체가 안정적인 NuGet 릴리스임에도 소프트웨어 구성 분석, 종속성 감사 또는 내부 승인 절차를 받는 팀에게 함축적인 영향을 미칩니다. 일부 기업 환경에서는 프로덕션 종속성이 1.0 이상의 안정 릴리스, 상업적 지원 계약, 또는 두 가지 모두를 요구합니다. ZXing.Net.MAUI는 커뮤니티에 의해 유지 관리되며, 1.0 이전이며, 내부 도구 및 프로토타입에는 적합하나, 바코드 스캐너가 주요 워크플로우인 고객 대상 애플리케이션에는 추가적인 검토 단계가 필요합니다. 유료 지원 계층의 부재는 중요한 버그가 커뮤니티 유지 관리자의 가용성에 의존한다는 의미입니다.

CameraBarcodeReaderView를 MediaPicker로 변환하는 패턴

CameraBarcodeReaderView XAML 컨트롤 및 xmlns:zxing 네임스페이스 선언이 완전히 제거됩니다. 스캐너 보기를 포함하고 있던 각 XAML 파일에서는, MediaPicker.CapturePhotoAsync()를 호출하는 Clicked 핸들러를 가진 Button 컨트롤로 대체됩니다. BarcodesDetected를 통해 결과가 도착하는 이벤트 중심 모델은 비동기 핸들러에서 BarcodeReader.Read()의 반환 값을 직접 읽는 것으로 대체됩니다.

수명주기 제거 감지

단순히 CameraView.IsDetecting를 전환하기 위한 OnAppearing 및 OnDisappearing 오버라이드는 모두 삭제할 수 있습니다. 해당 오버라이드에 다른 페이지 라이프사이클 논리가 포함되어 있는 경우, IsDetecting 라인은 제거되고 남은 논리는 보존됩니다. 페이지 탐색 간에 관리할 지속적인 카메라 상태가 없기 때문에 IsDetecting에 해당하는 IronBarcode가 없습니다.

UseBarcodeReader() 등록 제거

ZXing.Net.MAUI는 플랫폼 카메라 서비스를 등록하기 위해 MauiProgram.cs에서 1회 builder.UseBarcodeReader() 호출을 필요로 합니다. IronBarcode는 MauiProgram.cs 등록을 필요로 하지 않습니다. UseBarcodeReader() 라인은 삭제되며, 이를 지원하는 using ZXing.Net.Maui; 네임스페이스 가져오기가 패키지 삭제와 함께 제거됩니다.