如何構建.NET MAUI條碼掃描器SDK應用程式

建立 .NET MAUI 專案

開啟 Visual Studio 並建立新的 .NET MAUI App 專案。 將項目命名為類似"條碼掃描器"這樣的描述性名稱，並選擇 .NET 8 或更高版本作為目標框架。 Visual Studio 會產生預設專案結構，其中包含 Android 和 iOS 平台特定的資料夾。

如果您面向的是 .NET 10，則相同的專案範本也適用。 更新 <TargetFrameworks> 文件中的 .csproj 屬性，根據需要包含 net10.0-android、net10.0-ios 和 net10.0-windows10.0.19041.0。 有關目標框架名稱和最低作業系統版本要求的完整列表，請參閱.NET MAUI 支援的平台文件。

安裝 IronBarcode。

使用套件管理器控制台安裝IronBarcode NuGet 套件：

Install-Package BarCode

此命令下載並安裝條碼掃描器 SDK 以及 .NET MAUI 應用程式所需的所有相依性。

設定平台權限

即使掃描的是影像檔案而不是即時相機畫面，為 .NET MAUI 條碼掃描器應用程式配置以下權限也是很好的做法。

對於 Android 系統，請將以下內容新增至 Platforms/Android/AndroidManifest.xml：

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.CAMERA" />

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.CAMERA" />

對於 iOS，請將以下條目新增至 Platforms/iOS/Info.plist:

<key>NSPhotoLibraryUsageDescription</key>
<string>Access needed to select barcode images for scanning.</string>
<key>NSCameraUsageDescription</key>
<string>Camera permission for barcode scanning.</string>

<key>NSPhotoLibraryUsageDescription</key>
<string>Access needed to select barcode images for scanning.</string>
<key>NSCameraUsageDescription</key>
<string>Camera permission for barcode scanning.</string>

初始化 SDK

在應用程式生命週期的早期階段設定您的許可證金鑰，以確保在進行任何掃描呼叫之前 IronBarcode 已完全啟動。 請將啟動碼放在 MauiProgram.cs:

using IronBarCode;

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .ConfigureFonts(fonts =>
    {
        fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
    });

// Activate IronBarcode before the app starts
License.LicenseKey = "YOUR_LICENSE_KEY_HERE";

return builder.Build();

using IronBarCode;

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .ConfigureFonts(fonts =>
    {
        fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
    });

// Activate IronBarcode before the app starts
License.LicenseKey = "YOUR_LICENSE_KEY_HERE";

return builder.Build();

Imports IronBarCode

Dim builder = MauiApp.CreateBuilder()
builder _
    .UseMauiApp(Of App)() _
    .ConfigureFonts(Sub(fonts)
        fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular")
    End Sub)

' Activate IronBarcode before the app starts
License.LicenseKey = "YOUR_LICENSE_KEY_HERE"

Return builder.Build()

IronBarcode 提供免費試用許可證，供開發和測試使用。 在啟動時設定一次金鑰；同一進程內對 BarcodeReader 和 BarcodeWriter 的所有後續呼叫均使用已啟動的授權。

如何從圖像檔案中讀取條碼？

MAUI條碼掃描器的核心功能是讀取選定影像中的條碼。 BarcodeReader.Read() 方法接受一個檔案路徑，並傳回一個 BarcodeResult 物件集合，每個偵測到的條碼對應一個物件。

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="BarcodeScanner.MainPage">
    <VerticalStackLayout Padding="20" Spacing="15">
        <Label Text=".NET MAUI Barcode Scanner" FontSize="24" HorizontalOptions="Center"/>
        <Button Text="Select Image to Scan" Clicked="OnSelectImageClicked"/>
        <Image x:Name="SelectedImageView" HeightRequest="200"/>
        <Label x:Name="ResultLabel" FontSize="16"/>
    </VerticalStackLayout>
</ContentPage>

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="BarcodeScanner.MainPage">
    <VerticalStackLayout Padding="20" Spacing="15">
        <Label Text=".NET MAUI Barcode Scanner" FontSize="24" HorizontalOptions="Center"/>
        <Button Text="Select Image to Scan" Clicked="OnSelectImageClicked"/>
        <Image x:Name="SelectedImageView" HeightRequest="200"/>
        <Label x:Name="ResultLabel" FontSize="16"/>
    </VerticalStackLayout>
</ContentPage>

using IronBarCode;

public partial class MainPage : ContentPage
{
    public MainPage()
    {
        InitializeComponent();
    }

    private async void OnSelectImageClicked(object sender, EventArgs e)
    {
        var result = await FilePicker.PickAsync(new PickOptions
        {
            FileTypes = FilePickerFileType.Images,
            PickerTitle = "Select a barcode image"
        });

        if (result != null)
        {
            // Display the selected image
            SelectedImageView.Source = ImageSource.FromFile(result.FullPath);

            // Read barcodes from the image file
            var barcodes = BarcodeReader.Read(result.FullPath);

            ResultLabel.Text = barcodes.Any()
                ? $"Found: {barcodes.First().Value}"
                : "No barcodes detected in selected image.";
        }
    }
}

using IronBarCode;

public partial class MainPage : ContentPage
{
    public MainPage()
    {
        InitializeComponent();
    }

    private async void OnSelectImageClicked(object sender, EventArgs e)
    {
        var result = await FilePicker.PickAsync(new PickOptions
        {
            FileTypes = FilePickerFileType.Images,
            PickerTitle = "Select a barcode image"
        });

        if (result != null)
        {
            // Display the selected image
            SelectedImageView.Source = ImageSource.FromFile(result.FullPath);

            // Read barcodes from the image file
            var barcodes = BarcodeReader.Read(result.FullPath);

            ResultLabel.Text = barcodes.Any()
                ? $"Found: {barcodes.First().Value}"
                : "No barcodes detected in selected image.";
        }
    }
}

Imports IronBarCode

Public Partial Class MainPage
    Inherits ContentPage

    Public Sub New()
        InitializeComponent()
    End Sub

    Private Async Sub OnSelectImageClicked(sender As Object, e As EventArgs)
        Dim result = Await FilePicker.PickAsync(New PickOptions With {
            .FileTypes = FilePickerFileType.Images,
            .PickerTitle = "Select a barcode image"
        })

        If result IsNot Nothing Then
            ' Display the selected image
            SelectedImageView.Source = ImageSource.FromFile(result.FullPath)

            ' Read barcodes from the image file
            Dim barcodes = BarcodeReader.Read(result.FullPath)

            ResultLabel.Text = If(barcodes.Any(), $"Found: {barcodes.First().Value}", "No barcodes detected in selected image.")
        End If
    End Sub
End Class

using IronBarCode;

private async void OnSelectPdfClicked(object sender, EventArgs e)
{
    var result = await FilePicker.PickAsync(new PickOptions
    {
        PickerTitle = "Select a PDF with barcodes"
    });

    if (result != null)
    {
        // Read barcodes from every page of the PDF
        var barcodes = BarcodeReader.ReadPdf(result.FullPath);

        var output = string.Join("\n", barcodes.Select(b =>
            $"Page {b.PageNumber}: [{b.BarcodeType}] {b.Value}"));

        await DisplayAlert("Scan Results", output.Length > 0 ? output : "No barcodes found.", "OK");
    }
}

using IronBarCode;

private async void OnSelectPdfClicked(object sender, EventArgs e)
{
    var result = await FilePicker.PickAsync(new PickOptions
    {
        PickerTitle = "Select a PDF with barcodes"
    });

    if (result != null)
    {
        // Read barcodes from every page of the PDF
        var barcodes = BarcodeReader.ReadPdf(result.FullPath);

        var output = string.Join("\n", barcodes.Select(b =>
            $"Page {b.PageNumber}: [{b.BarcodeType}] {b.Value}"));

        await DisplayAlert("Scan Results", output.Length > 0 ? output : "No barcodes found.", "OK");
    }
}

Imports IronBarCode

Private Async Sub OnSelectPdfClicked(sender As Object, e As EventArgs)
    Dim result = Await FilePicker.PickAsync(New PickOptions With {
        .PickerTitle = "Select a PDF with barcodes"
    })

    If result IsNot Nothing Then
        ' Read barcodes from every page of the PDF
        Dim barcodes = BarcodeReader.ReadPdf(result.FullPath)

        Dim output = String.Join(vbLf, barcodes.Select(Function(b) $"Page {b.PageNumber}: [{b.BarcodeType}] {b.Value}"))

        Await DisplayAlert("Scan Results", If(output.Length > 0, output, "No barcodes found."), "OK")
    End If
End Sub

using IronBarCode;

// Configure the reader for multi-barcode detection with type filtering
var options = new BarcodeReaderOptions
{
    ExpectMultipleBarcodes = true,
    ExpectBarcodeTypes = BarcodeEncoding.QRCode | BarcodeEncoding.Code128,
    Speed = ReadingSpeed.Balanced
};

var barcodes = BarcodeReader.Read(imagePath, options);

foreach (var barcode in barcodes)
{
    Console.WriteLine($"Type: {barcode.BarcodeType}, Value: {barcode.Value}");
}

using IronBarCode;

// Configure the reader for multi-barcode detection with type filtering
var options = new BarcodeReaderOptions
{
    ExpectMultipleBarcodes = true,
    ExpectBarcodeTypes = BarcodeEncoding.QRCode | BarcodeEncoding.Code128,
    Speed = ReadingSpeed.Balanced
};

var barcodes = BarcodeReader.Read(imagePath, options);

foreach (var barcode in barcodes)
{
    Console.WriteLine($"Type: {barcode.BarcodeType}, Value: {barcode.Value}");
}

Imports IronBarCode

' Configure the reader for multi-barcode detection with type filtering
Dim options As New BarcodeReaderOptions With {
    .ExpectMultipleBarcodes = True,
    .ExpectBarcodeTypes = BarcodeEncoding.QRCode Or BarcodeEncoding.Code128,
    .Speed = ReadingSpeed.Balanced
}

Dim barcodes = BarcodeReader.Read(imagePath, options)

For Each barcode In barcodes
    Console.WriteLine($"Type: {barcode.BarcodeType}, Value: {barcode.Value}")
Next

如何從記憶體流讀取條碼？

檔案路徑在大多數情況下都能很好地運作，但某些 .NET MAUI 工作流程會透過記憶體傳遞影像資料——從相機預覽擷取的畫面、從 REST API 下載的位元組或進程內產生的影像資料。 IronBarcode 支援在 BarcodeReader.Read() 重載直接輸入 System.IO.Stream：

using IronBarCode;
using System.IO;

// Read a barcode from a MemoryStream (e.g., an in-memory image buffer)
private BarcodeResult[] ReadFromStream(Stream imageStream)
{
    return BarcodeReader.Read(imageStream);
}

// Example: download an image and scan without writing to disk
private async Task<string> ScanDownloadedBarcode(string imageUrl)
{
    using var httpClient = new HttpClient();
    using var stream = await httpClient.GetStreamAsync(imageUrl);
    using var memoryStream = new MemoryStream();

    await stream.CopyToAsync(memoryStream);
    memoryStream.Position = 0;

    var barcodes = BarcodeReader.Read(memoryStream);
    return barcodes.Any() ? barcodes.First().Value : string.Empty;
}

using IronBarCode;
using System.IO;

// Read a barcode from a MemoryStream (e.g., an in-memory image buffer)
private BarcodeResult[] ReadFromStream(Stream imageStream)
{
    return BarcodeReader.Read(imageStream);
}

// Example: download an image and scan without writing to disk
private async Task<string> ScanDownloadedBarcode(string imageUrl)
{
    using var httpClient = new HttpClient();
    using var stream = await httpClient.GetStreamAsync(imageUrl);
    using var memoryStream = new MemoryStream();

    await stream.CopyToAsync(memoryStream);
    memoryStream.Position = 0;

    var barcodes = BarcodeReader.Read(memoryStream);
    return barcodes.Any() ? barcodes.First().Value : string.Empty;
}

Imports IronBarCode
Imports System.IO
Imports System.Net.Http
Imports System.Threading.Tasks

' Read a barcode from a MemoryStream (e.g., an in-memory image buffer)
Private Function ReadFromStream(imageStream As Stream) As BarcodeResult()
    Return BarcodeReader.Read(imageStream)
End Function

' Example: download an image and scan without writing to disk
Private Async Function ScanDownloadedBarcode(imageUrl As String) As Task(Of String)
    Using httpClient As New HttpClient()
        Using stream As Stream = Await httpClient.GetStreamAsync(imageUrl)
            Using memoryStream As New MemoryStream()
                Await stream.CopyToAsync(memoryStream)
                memoryStream.Position = 0

                Dim barcodes = BarcodeReader.Read(memoryStream)
                Return If(barcodes.Any(), barcodes.First().Value, String.Empty)
            End Using
        End Using
    End Using
End Function

流重載接受任何 Stream 子類，包括 MemoryStream、FileStream 和網路流。 該庫內部會處理格式檢測，因此在呼叫之前無需指定圖像類型。

如何在MAUI應用程式中產生條碼？

IronBarcode既能產生條碼，也能讀取條碼。 BarcodeWriter 類別產生條碼，作為映像檔、Bitmap 物件或 Stream 實例，您可以在 MAUI 視圖中內嵌顯示這些條碼。 這對於需要列印或共享條碼以及具備掃描功能的庫存管理應用程式非常有用：

using IronBarCode;

// Generate a QR code and display it in a MAUI Image control
private async void OnGenerateQrClicked(object sender, EventArgs e)
{
    // Create a QR code barcode
    var qrCode = QRCodeWriter.CreateQrCode(
        value: "https://ironsoftware.com/csharp/barcode/",
        qrCodeSize: 500,
        errorCorrection: QRCodeWriter.QrErrorCorrectionLevel.Medium
    );

    // Save to a temporary file and display
    var tempPath = Path.Combine(FileSystem.CacheDirectory, "generated-qr.png");
    qrCode.SaveAsPng(tempPath);

    GeneratedImageView.Source = ImageSource.FromFile(tempPath);
}

using IronBarCode;

// Generate a QR code and display it in a MAUI Image control
private async void OnGenerateQrClicked(object sender, EventArgs e)
{
    // Create a QR code barcode
    var qrCode = QRCodeWriter.CreateQrCode(
        value: "https://ironsoftware.com/csharp/barcode/",
        qrCodeSize: 500,
        errorCorrection: QRCodeWriter.QrErrorCorrectionLevel.Medium
    );

    // Save to a temporary file and display
    var tempPath = Path.Combine(FileSystem.CacheDirectory, "generated-qr.png");
    qrCode.SaveAsPng(tempPath);

    GeneratedImageView.Source = ImageSource.FromFile(tempPath);
}

Imports IronBarCode

' Generate a QR code and display it in a MAUI Image control
Private Async Sub OnGenerateQrClicked(sender As Object, e As EventArgs)
    ' Create a QR code barcode
    Dim qrCode = QRCodeWriter.CreateQrCode(
        value:="https://ironsoftware.com/csharp/barcode/",
        qrCodeSize:=500,
        errorCorrection:=QRCodeWriter.QrErrorCorrectionLevel.Medium
    )

    ' Save to a temporary file and display
    Dim tempPath = Path.Combine(FileSystem.CacheDirectory, "generated-qr.png")
    qrCode.SaveAsPng(tempPath)

    GeneratedImageView.Source = ImageSource.FromFile(tempPath)
End Sub

QRCodeWriter 類別支援所有四個 QR 錯誤錯誤等級（低、中、四分位數、高）、自訂尺寸和樣式選項，包括前景色/背景色控制。 對於非 QR 碼符號，請使用 BarcodeWriter.CreateBarcode() 和對應的 BarcodeEncoding 值。 條碼產生 API 參考文件記錄了所有支援的輸出格式。

該條碼掃描器庫的主要功能有哪些？

IronBarcode 為 .NET MAUI 條碼掃描專案提供了幾個優勢，使其區別於 ZXing.Net.MAUI 等開源替代方案：

在 .NET MAUI 專案中，"不依賴原生 SDK"這一點很重要，因為特定於平台的原生程式庫需要為每個目標單獨進行連結步驟。 IronBarcode 完全避免了這種複雜性，這意味著同一個 NuGet 參考可以產生適用於所有三個受支援平台的可用二進位文件，而無需額外的配置。

有關支援的條碼格式的完整列表，請參閱IronBarcode 支援的格式文件。 有關生產部署的定價和授權條款，請查看IronBarcode 授權頁面。

生產中條碼掃描的最佳實務是什麼？

將條碼掃描器部署到生產環境中，除了基本的讀取呼叫之外，還需要注意一些其他方面。 以下指南針對 .NET MAUI 條碼應用程式中最常見的故障點。

選擇合適的讀取速度。 ReadingSpeed.Balanced 可以正確處理大多數實際影像。 預留 ReadingSpeed.ExtraSlow 用於掃描使用者無法重新擷取的列印文件或影像。 對於高容量工作流程，請避免使用 ReadingSpeed.ExtraSlow，因為每次掃描所需時間都相當長。

按預期類型篩選。如果應用程式僅處理二維碼，請設定 ExpectBarcodeTypes = BarcodeEncoding.QRCode。 限制搜尋空間可以減少處理時間，並消除背景圖形中存在的其他符號系統所造成的誤報。

僅在需要時使用 ExpectMultipleBarcodes。將其設為 true 始終會導致讀取器執行額外的掃描操作。 對於單一條碼輸入，保留預設值（false），以便掃描在找到第一個有效代碼後立即返回。

優雅地處理空結果。當未偵測到條碼時，BarcodeReader.Read() 傳回一個空數組，而不是拋出例外。 在造訪 First() 之前，請檢查 .Any()，並向使用者顯示明確的訊息。 帶有指導的重試提示（"確保條碼光線充足且居中"）比通用錯誤提示更能改善使用者體驗。

快取選項物件。每次掃描都建立一個 BarcodeReaderOptions 實例會增加記憶體分配。 在類別層級建構一次選項，並在多個呼叫中重複使用。

有關診斷掃描故障和最佳化效能的更多指導，請參閱IronBarcode 故障排除指南和條碼閱讀器教學。

下一步計劃是什麼？

使用 IronBarcode 建立 .NET MAUI 條碼掃描器需要安裝一個 NuGet 包，配置平台權限，並使用檔案路徑或流呼叫 BarcodeReader.Read()。 同一個 API 可以同時支援 Android、iOS 和 Windows 系統，沒有針對特定平台的程式碼分支。

若要進一步擴展應用程式的功能，請參考以下資源：

IronBarcode完整功能清單－所有掃描和產生功能的目錄 條碼讀取器 API 參考-- 完整的方法和屬性文檔 MAUI條碼閱讀器逐步教學－涵蓋攝影機整合的詳細講解 MAUI 文件掃描器指南－文件掃描用例

立即開始免費試用，取得開發許可證金鑰，或了解生產部署的授權選項。