Migrating from Spire.Barcode to IronBarcode

The Fundamental Problem

The type-guessing loop is the most visible symptom of the mandatory BarCodeType constraint. In a Spire.Barcode codebase processing documents from multiple sources, this pattern appears repeatedly:

// Spire.Barcode: growing candidate loop with silent misses
BarcodeScanner scanner = new BarcodeScanner();
var candidates = new[] { BarCodeType.Code128, BarCodeType.QRCode, BarCodeType.DataMatrix, BarCodeType.EAN13, BarCodeType.PDF417 };

string foundValue = null;
foreach (var type in candidates)
{
    string[] found = scanner.Scan("barcode.png", type);
    if (found.Length > 0)
    {
        foundValue = found[0];
        break;
    }
}

// Spire.Barcode: growing candidate loop with silent misses
BarcodeScanner scanner = new BarcodeScanner();
var candidates = new[] { BarCodeType.Code128, BarCodeType.QRCode, BarCodeType.DataMatrix, BarCodeType.EAN13, BarCodeType.PDF417 };

string foundValue = null;
foreach (var type in candidates)
{
    string[] found = scanner.Scan("barcode.png", type);
    if (found.Length > 0)
    {
        foundValue = found[0];
        break;
    }
}

Imports Spire.Barcode

Dim scanner As New BarcodeScanner()
Dim candidates = {BarCodeType.Code128, BarCodeType.QRCode, BarCodeType.DataMatrix, BarCodeType.EAN13, BarCodeType.PDF417}

Dim foundValue As String = Nothing
For Each type In candidates
    Dim found As String() = scanner.Scan("barcode.png", type)
    If found.Length > 0 Then
        foundValue = found(0)
        Exit For
    End If
Next

IronBarcode removes the loop entirely. Format detection is built into the library:

// IronBarcode: single call, all formats, type included in result
var results = BarcodeReader.Read("barcode.png");

foreach (var result in results)
{
    Console.WriteLine($"{result.BarcodeType}: {result.Value}");
}

// IronBarcode: single call, all formats, type included in result
var results = BarcodeReader.Read("barcode.png");

foreach (var result in results)
{
    Console.WriteLine($"{result.BarcodeType}: {result.Value}");
}

Imports IronBarcode

' IronBarcode: single call, all formats, type included in result
Dim results = BarcodeReader.Read("barcode.png")

For Each result In results
    Console.WriteLine($"{result.BarcodeType}: {result.Value}")
Next

Step 1: Replace NuGet Package

Remove the Spire package or packages currently in use:

# Remove whichever variant is installed
dotnet remove package FreeSpire.Barcode
# or
dotnet remove package Spire.Barcode

# If Spire.PDF was installed only for barcode extraction, remove it as well
dotnet remove package Spire.PDF

# Remove whichever variant is installed
dotnet remove package FreeSpire.Barcode
# or
dotnet remove package Spire.Barcode

# If Spire.PDF was installed only for barcode extraction, remove it as well
dotnet remove package Spire.PDF

If Spire.PDF is used for other document operations beyond barcode extraction, retain it and remove only the barcode-related code paths from it.

Install IronBarcode:

dotnet add package IronBarcode

dotnet add package IronBarcode

Step 2: Update Namespaces

Replace all Spire namespace imports with the IronBarcode namespace:

// Remove:
using Spire.Barcode;
using Spire.Pdf;

// Add:
using IronBarCode;

// Remove:
using Spire.Barcode;
using Spire.Pdf;

// Add:
using IronBarCode;

Imports IronBarCode

Step 3: Initialize License

Replace the Spire license initialization with a single IronBarcode property assignment at application startup. See the IronBarcode licensing page for key formats and deployment options:

// Remove (FreeSpire registration):
Spire.Barcode.BarcodeSettings.ApplyKey("your-free-key");

// Remove (commercial Spire license):
Spire.License.LicenseProvider.SetLicenseKey("your-commercial-key");

// Add (IronBarcode):
IronBarCode.License.LicenseKey = "YOUR-IRONBARCODE-LICENSE-KEY";

// Remove (FreeSpire registration):
Spire.Barcode.BarcodeSettings.ApplyKey("your-free-key");

// Remove (commercial Spire license):
Spire.License.LicenseProvider.SetLicenseKey("your-commercial-key");

// Add (IronBarcode):
IronBarCode.License.LicenseKey = "YOUR-IRONBARCODE-LICENSE-KEY";

Imports Spire.Barcode
Imports Spire.License
Imports IronBarCode

' Remove (FreeSpire registration):
BarcodeSettings.ApplyKey("your-free-key")

' Remove (commercial Spire license):
LicenseProvider.SetLicenseKey("your-commercial-key")

' Add (IronBarcode):
License.LicenseKey = "YOUR-IRONBARCODE-LICENSE-KEY"

For Docker and CI environments, the license key can be supplied from an environment variable:

IronBarCode.License.LicenseKey = Environment.GetEnvironmentVariable("IRONBARCODE_LICENSE");

IronBarCode.License.LicenseKey = Environment.GetEnvironmentVariable("IRONBARCODE_LICENSE");

Imports System

IronBarCode.License.LicenseKey = Environment.GetEnvironmentVariable("IRONBARCODE_LICENSE")

Reading a Known-Format Barcode

A single-format read in Spire.Barcode passes the type explicitly and receives a string[].

Spire.Barcode Approach:

using Spire.Barcode;

BarcodeScanner scanner = new BarcodeScanner();
string[] results = scanner.Scan("shipping-label.png", BarCodeType.Code128);

if (results.Length > 0)
{
    ProcessShipment(results[0]);
}

using Spire.Barcode;

BarcodeScanner scanner = new BarcodeScanner();
string[] results = scanner.Scan("shipping-label.png", BarCodeType.Code128);

if (results.Length > 0)
{
    ProcessShipment(results[0]);
}

Imports Spire.Barcode

Dim scanner As New BarcodeScanner()
Dim results As String() = scanner.Scan("shipping-label.png", BarCodeType.Code128)

If results.Length > 0 Then
    ProcessShipment(results(0))
End If

IronBarcode Approach:

using IronBarCode;

var results = BarcodeReader.Read("shipping-label.png");

if (results.Any())
{
    ProcessShipment(results.First().Value);
}

using IronBarCode;

var results = BarcodeReader.Read("shipping-label.png");

if (results.Any())
{
    ProcessShipment(results.First().Value);
}

Imports IronBarCode

Dim results = BarcodeReader.Read("shipping-label.png")

If results.Any() Then
    ProcessShipment(results.First().Value)
End If

The BarCodeType parameter is removed. If downstream logic needs to confirm the detected format, results.First().BarcodeType provides it without requiring a separate state variable.

Collapsing a Mixed-Format Type Loop

When a Spire.Barcode codebase handles documents that may contain any of several formats, the type-guessing loop accumulates over time as new formats enter the workflow.

Spire.Barcode Approach:

using Spire.Barcode;

BarcodeScanner scanner = new BarcodeScanner();
BarCodeType[] candidates = new[]
{
    BarCodeType.Code128,
    BarCodeType.QRCode,
    BarCodeType.DataMatrix,
    BarCodeType.EAN13,
    BarCodeType.PDF417
};

List<string> allValues = new List<string>();
foreach (BarCodeType type in candidates)
{
    string[] found = scanner.Scan("document-scan.png", type);
    allValues.AddRange(found);
}

using Spire.Barcode;

BarcodeScanner scanner = new BarcodeScanner();
BarCodeType[] candidates = new[]
{
    BarCodeType.Code128,
    BarCodeType.QRCode,
    BarCodeType.DataMatrix,
    BarCodeType.EAN13,
    BarCodeType.PDF417
};

List<string> allValues = new List<string>();
foreach (BarCodeType type in candidates)
{
    string[] found = scanner.Scan("document-scan.png", type);
    allValues.AddRange(found);
}

Imports Spire.Barcode

Dim scanner As New BarcodeScanner()
Dim candidates As BarCodeType() = {
    BarCodeType.Code128,
    BarCodeType.QRCode,
    BarCodeType.DataMatrix,
    BarCodeType.EAN13,
    BarCodeType.PDF417
}

Dim allValues As New List(Of String)()
For Each type As BarCodeType In candidates
    Dim found As String() = scanner.Scan("document-scan.png", type)
    allValues.AddRange(found)
Next

IronBarcode Approach:

using IronBarCode;

// The entire loop is replaced by a single call
var results = BarcodeReader.Read("document-scan.png");
List<string> allValues = results.Select(r => r.Value).ToList();

using IronBarCode;

// The entire loop is replaced by a single call
var results = BarcodeReader.Read("document-scan.png");
List<string> allValues = results.Select(r => r.Value).ToList();

Imports IronBarCode

' The entire loop is replaced by a single call
Dim results = BarcodeReader.Read("document-scan.png")
Dim allValues As List(Of String) = results.Select(Function(r) r.Value).ToList()

IronBarcode's image reading handles all 50+ symbologies in a single pass. When reading speed needs to be tuned for high-volume batch processing, BarcodeReaderOptions provides that control without adding format-specific branches:

var options = new BarcodeReaderOptions
{
    Speed = ReadingSpeed.Balanced,
    ExpectMultipleBarcodes = true
};
var results = BarcodeReader.Read("document-scan.png", options);

var options = new BarcodeReaderOptions
{
    Speed = ReadingSpeed.Balanced,
    ExpectMultipleBarcodes = true
};
var results = BarcodeReader.Read("document-scan.png", options);

Dim options As New BarcodeReaderOptions With {
    .Speed = ReadingSpeed.Balanced,
    .ExpectMultipleBarcodes = True
}
Dim results = BarcodeReader.Read("document-scan.png", options)

For guidance on selecting the appropriate ReadingSpeed value, see the reading speed options documentation.

Generating a Barcode

Spire.Barcode generation requires instantiating a BarcodeSettings object, assigning each property individually, passing the settings to a BarCodeGenerator, and then calling GenerateImage() before any file is written.

Spire.Barcode Approach:

using Spire.Barcode;

BarcodeSettings settings = new BarcodeSettings();
settings.Type = BarCodeType.Code128;
settings.Data = "SHIP-9842-XZ";
settings.ShowText = true;
settings.TextMargin = 5;
settings.BarHeight = 60;
settings.Unit = GraphicsUnit.Pixel;

BarCodeGenerator generator = new BarCodeGenerator(settings);
Image barcodeImage = generator.GenerateImage();
barcodeImage.Save("shipping-label.png", ImageFormat.Png);

using Spire.Barcode;

BarcodeSettings settings = new BarcodeSettings();
settings.Type = BarCodeType.Code128;
settings.Data = "SHIP-9842-XZ";
settings.ShowText = true;
settings.TextMargin = 5;
settings.BarHeight = 60;
settings.Unit = GraphicsUnit.Pixel;

BarCodeGenerator generator = new BarCodeGenerator(settings);
Image barcodeImage = generator.GenerateImage();
barcodeImage.Save("shipping-label.png", ImageFormat.Png);

Imports Spire.Barcode
Imports System.Drawing
Imports System.Drawing.Imaging

Dim settings As New BarcodeSettings()
settings.Type = BarCodeType.Code128
settings.Data = "SHIP-9842-XZ"
settings.ShowText = True
settings.TextMargin = 5
settings.BarHeight = 60
settings.Unit = GraphicsUnit.Pixel

Dim generator As New BarCodeGenerator(settings)
Dim barcodeImage As Image = generator.GenerateImage()
barcodeImage.Save("shipping-label.png", ImageFormat.Png)

IronBarcode Approach:

using IronBarCode;

BarcodeWriter.CreateBarcode("SHIP-9842-XZ", BarcodeEncoding.Code128)
    .ResizeTo(400, 100)
    .SaveAsPng("shipping-label.png");

using IronBarCode;

BarcodeWriter.CreateBarcode("SHIP-9842-XZ", BarcodeEncoding.Code128)
    .ResizeTo(400, 100)
    .SaveAsPng("shipping-label.png");

Imports IronBarCode

BarcodeWriter.CreateBarcode("SHIP-9842-XZ", BarcodeEncoding.Code128) _
    .ResizeTo(400, 100) _
    .SaveAsPng("shipping-label.png")

The mutable BarcodeSettings object and the separate BarCodeGenerator instance are replaced by a single static factory call with a fluent chain. There is no risk of settings being accidentally shared across concurrent calls because each CreateBarcode() invocation is independent.

Reading Barcodes from a PDF Document

Spire.Barcode cannot read PDFs directly. The Spire-based approach requires the separate Spire.PDF package to open the file, iterate its pages, extract raster images from each page, and then pass those images one at a time to the barcode scanner.

Spire.Barcode Approach:

using Spire.Pdf;
using Spire.Barcode;

var pdf = new PdfDocument();
pdf.LoadFromFile("invoices.pdf");

var scanner = new BarcodeScanner();
var extractedValues = new List<string>();

foreach (PdfPageBase page in pdf.Pages)
{
    Image[] images = page.ExtractImages();
    foreach (Image image in images)
    {
        string[] found = scanner.Scan(image, BarCodeType.QRCode);
        extractedValues.AddRange(found);
    }
}

using Spire.Pdf;
using Spire.Barcode;

var pdf = new PdfDocument();
pdf.LoadFromFile("invoices.pdf");

var scanner = new BarcodeScanner();
var extractedValues = new List<string>();

foreach (PdfPageBase page in pdf.Pages)
{
    Image[] images = page.ExtractImages();
    foreach (Image image in images)
    {
        string[] found = scanner.Scan(image, BarCodeType.QRCode);
        extractedValues.AddRange(found);
    }
}

Imports Spire.Pdf
Imports Spire.Barcode

Dim pdf As New PdfDocument()
pdf.LoadFromFile("invoices.pdf")

Dim scanner As New BarcodeScanner()
Dim extractedValues As New List(Of String)()

For Each page As PdfPageBase In pdf.Pages
    Dim images() As Image = page.ExtractImages()
    For Each image As Image In images
        Dim found() As String = scanner.Scan(image, BarCodeType.QRCode)
        extractedValues.AddRange(found)
    Next
Next

IronBarcode Approach:

using IronBarCode;

var results = BarcodeReader.Read("invoices.pdf");

foreach (var barcode in results)
{
    Console.WriteLine($"Page {barcode.PageNumber}: {barcode.BarcodeType} = {barcode.Value}");
}

using IronBarCode;

var results = BarcodeReader.Read("invoices.pdf");

foreach (var barcode in results)
{
    Console.WriteLine($"Page {barcode.PageNumber}: {barcode.BarcodeType} = {barcode.Value}");
}

Imports IronBarCode

Dim results = BarcodeReader.Read("invoices.pdf")

For Each barcode In results
    Console.WriteLine($"Page {barcode.PageNumber}: {barcode.BarcodeType} = {barcode.Value}")
Next

IronBarcode reads PDF documents directly without requiring Spire.PDF or any manual page management. The page number from which each barcode was extracted is available in the result object. Once the PDF reading code is replaced, the Spire.PDF package reference and all using Spire.Pdf; imports can be removed from the project.

Issue 1: BarCodeType Parameter Removal

Spire.Barcode: scanner.Scan(path, BarCodeType.Code128) — the type argument is required by the method signature. Removing it causes a compile error.

Solution: Replace the entire call with BarcodeReader.Read(path). Search the codebase for BarCodeType. to locate every occurrence. Type-guessing loops (foreach blocks iterating over a BarCodeType[] candidate array) can be deleted in their entirety; a single BarcodeReader.Read() call replaces the loop.

Issue 2: string[] Return Type

Spire.Barcode: Scan() returns string[]. Downstream code that assigns this to a string[] variable or passes it to a method expecting string[] will fail to compile after migration.

Solution: Update call sites to work with BarcodeResults. To obtain a plain string array, use .Select(r => r.Value).ToArray(). To access the first result, use .First()?.Value. If the detected format is needed downstream, it is available on the result object via .BarcodeType — no separate state variable is required.

// If a plain string array is needed:
string[] texts = BarcodeReader.Read("barcode.png")
    .Select(r => r.Value)
    .ToArray();

// If only the first value is needed:
string first = BarcodeReader.Read("barcode.png").First()?.Value;

// If a plain string array is needed:
string[] texts = BarcodeReader.Read("barcode.png")
    .Select(r => r.Value)
    .ToArray();

// If only the first value is needed:
string first = BarcodeReader.Read("barcode.png").First()?.Value;

Imports System.Linq

' If a plain string array is needed:
Dim texts As String() = BarcodeReader.Read("barcode.png") _
    .Select(Function(r) r.Value) _
    .ToArray()

' If only the first value is needed:
Dim first As String = BarcodeReader.Read("barcode.png").FirstOrDefault()?.Value

Issue 3: Spire.PDF Package Cleanup

Spire.Barcode: PDF reading workflows depend on Spire.PDF for page access and image extraction. The project references the package and contains using Spire.Pdf; imports and PdfDocument / PdfPageBase usage spread across multiple files.

Solution: After replacing all PDF barcode extraction code with BarcodeReader.Read("file.pdf"), run a grep audit to confirm no remaining Spire.Pdf references exist before removing the package:

grep -r "using Spire.Pdf" --include="*.cs" .
grep -r "Spire\.Pdf\|PdfPageBase\|ExtractImages" --include="*.cs" .

grep -r "using Spire.Pdf" --include="*.cs" .
grep -r "Spire\.Pdf\|PdfPageBase\|ExtractImages" --include="*.cs" .

Remove the package only when all references are cleared:

dotnet remove package Spire.PDF

dotnet remove package Spire.PDF

Issue 4: Namespace Changes

Spire.Barcode: The Spire.Barcode namespace contains BarcodeScanner, BarcodeSettings, BarCodeGenerator, and BarCodeType. The IronBarCode namespace contains BarcodeReader, BarcodeWriter, BarcodeEncoding, and BarcodeReaderOptions.

Solution: Replace using Spire.Barcode; with using IronBarCode; globally. The BarCodeType enum used in generation is replaced by BarcodeEncoding. The BarCodeType enum used in reading has no IronBarcode equivalent — it is simply removed, as format detection is automatic.

Pre-Migration Tasks

Audit the codebase to identify all Spire.Barcode usage before making changes:

grep -r "using Spire.Barcode" --include="*.cs" .
grep -r "using Spire.Pdf" --include="*.cs" .
grep -r "BarcodeScanner\|BarcodeSettings\|BarCodeGenerator\|BarCodeType\." --include="*.cs" .
grep -r "ApplyKey\|SetLicenseKey" --include="*.cs" .
grep -r "ExtractImages\|PdfPageBase" --include="*.cs" .

grep -r "using Spire.Barcode" --include="*.cs" .
grep -r "using Spire.Pdf" --include="*.cs" .
grep -r "BarcodeScanner\|BarcodeSettings\|BarCodeGenerator\|BarCodeType\." --include="*.cs" .
grep -r "ApplyKey\|SetLicenseKey" --include="*.cs" .
grep -r "ExtractImages\|PdfPageBase" --include="*.cs" .

• Document all files containing BarCodeType candidate arrays (type-guessing loops to be removed)
• Identify any string[] variables that receive results from Scan() and will need type updates
• Confirm whether Spire.PDF is used for operations other than barcode extraction

Code Update Tasks

1. Remove FreeSpire.Barcode or Spire.Barcode NuGet package
2. Remove Spire.PDF NuGet package if barcode extraction was its only use
3. Install IronBarcode NuGet package
4. Replace all using Spire.Barcode; with using IronBarCode;
5. Remove all using Spire.Pdf; imports where no longer needed
6. Replace license initialization: ApplyKey() or SetLicenseKey() with IronBarCode.License.LicenseKey = "key"
7. Remove all new BarcodeScanner() instantiations
8. Replace all scanner.Scan(path, BarCodeType.X) calls with BarcodeReader.Read(path)
9. Delete type-guessing foreach loops; replace each with a single BarcodeReader.Read() call
10. Remove PDF page iteration and image extraction blocks; replace with BarcodeReader.Read("file.pdf")
11. Update string[] result assignments to use .Value or .Select(r => r.Value).ToArray()
12. Replace new BarcodeSettings() blocks with BarcodeWriter.CreateBarcode(data, encoding) chains
13. Remove new BarCodeGenerator(settings) instantiations
14. Replace .GenerateImage() + image.Save() with .SaveAsPng() or .SaveAsJpeg()
15. Replace BarCodeType.X enum values in generation with BarcodeEncoding.X

Post-Migration Testing

• Confirm all formats previously scanned via the candidate loop are detected correctly by BarcodeReader.Read()
• Measure batch processing throughput and confirm it meets production requirements
• Verify PDF barcode extraction produces correct values and page numbers
• Confirm generated barcode output quality and scanability with a physical or software scanner
• Check that the license key is correctly loaded in all deployment environments (local, staging, production, CI/CD)
• Run the grep audit commands from Pre-Migration Tasks to confirm no Spire references remain