Migrating from MessagingToolkit.Barcode to IronBarcode

The Fundamental Problem

MessagingToolkit.Barcode forces a dependency on System.Drawing and an instance-based workflow that is incompatible with modern .NET:

// MessagingToolkit.Barcode: only compiles on .NET Framework 4.5 or earlier
// System.Drawing.Bitmap throws PlatformNotSupportedException on Linux/.NET 6+
using MessagingToolkit.Barcode;
using System.Drawing;

var decoder = new BarcodeDecoder();
using (var bitmap = new Bitmap("barcode.png"))  // Windows-only in .NET 6+
{
    var result = decoder.Decode(bitmap);          // Single result or null
    if (result != null)
    {
        Console.WriteLine(result.Text);
    }
}

// MessagingToolkit.Barcode: only compiles on .NET Framework 4.5 or earlier
// System.Drawing.Bitmap throws PlatformNotSupportedException on Linux/.NET 6+
using MessagingToolkit.Barcode;
using System.Drawing;

var decoder = new BarcodeDecoder();
using (var bitmap = new Bitmap("barcode.png"))  // Windows-only in .NET 6+
{
    var result = decoder.Decode(bitmap);          // Single result or null
    if (result != null)
    {
        Console.WriteLine(result.Text);
    }
}

Imports MessagingToolkit.Barcode
Imports System.Drawing

Dim decoder As New BarcodeDecoder()
Using bitmap As New Bitmap("barcode.png") ' Windows-only in .NET 6+
    Dim result = decoder.Decode(bitmap) ' Single result or Nothing
    If result IsNot Nothing Then
        Console.WriteLine(result.Text)
    End If
End Using

IronBarcode removes the System.Drawing dependency entirely and works identically on Windows, Linux, macOS, and Docker containers:

// IronBarcode: runs on .NET 6, 7, 8, 9 — Windows, Linux, macOS, Docker
using IronBarCode;

IronBarCode.License.LicenseKey = "YOUR-KEY";

var results = BarcodeReader.Read("barcode.png");  // No Bitmap, no System.Drawing
foreach (var result in results)
{
    Console.WriteLine(result.Value);
}

// IronBarcode: runs on .NET 6, 7, 8, 9 — Windows, Linux, macOS, Docker
using IronBarCode;

IronBarCode.License.LicenseKey = "YOUR-KEY";

var results = BarcodeReader.Read("barcode.png");  // No Bitmap, no System.Drawing
foreach (var result in results)
{
    Console.WriteLine(result.Value);
}

Imports IronBarCode

IronBarCode.License.LicenseKey = "YOUR-KEY"

Dim results = BarcodeReader.Read("barcode.png")  ' No Bitmap, no System.Drawing
For Each result In results
    Console.WriteLine(result.Value)
Next

Step 1: Replace NuGet Package

Remove the MessagingToolkit.Barcode package:

dotnet remove package MessagingToolkit.Barcode

dotnet remove package MessagingToolkit.Barcode

If the project references MessagingToolkit.Barcode.dll directly through a <HintPath> entry in the .csproj file, remove that reference as well.

Install IronBarcode:

dotnet add package IronBarcode

dotnet add package IronBarcode

IronBarcode supports .NET Framework 4.6.2 through .NET 9. It installs as a single package with all dependencies bundled — no separate graphics library or ZXing reference is required alongside it.

Step 2: Update Namespaces

Replace the MessagingToolkit namespace with the IronBarcode namespace in every file that references the old library:

// Remove this
using MessagingToolkit.Barcode;
using System.Drawing;  // if used only for Bitmap input to MessagingToolkit

// Add this
using IronBarCode;

// Remove this
using MessagingToolkit.Barcode;
using System.Drawing;  // if used only for Bitmap input to MessagingToolkit

// Add this
using IronBarCode;

Imports IronBarCode

Files that imported System.Drawing solely for the Bitmap type used with MessagingToolkit.Barcode may have that import removed once IronBarcode is in place.

Step 3: Initialize License

Add license initialization once at application startup — in Program.cs, Startup.cs, or the equivalent entry point. A license key is required for production use; the library operates in trial mode without one.

// Add once at application startup
IronBarCode.License.LicenseKey = "YOUR-IRONBARCODE-KEY";

// Add once at application startup
IronBarCode.License.LicenseKey = "YOUR-IRONBARCODE-KEY";

' Add once at application startup
IronBarCode.License.LicenseKey = "YOUR-IRONBARCODE-KEY"

Reading Barcodes from Image Files

The old approach required constructing a Bitmap from the file path and passing it to a BarcodeDecoder instance. IronBarcode accepts the file path directly.

MessagingToolkit.Barcode Approach:

using MessagingToolkit.Barcode;
using System.Drawing;

public string ReadBarcodeValue(string imagePath)
{
    var decoder = new BarcodeDecoder();
    using (var bitmap = new Bitmap(imagePath))
    {
        var result = decoder.Decode(bitmap);
        return result?.Text;
    }
}

using MessagingToolkit.Barcode;
using System.Drawing;

public string ReadBarcodeValue(string imagePath)
{
    var decoder = new BarcodeDecoder();
    using (var bitmap = new Bitmap(imagePath))
    {
        var result = decoder.Decode(bitmap);
        return result?.Text;
    }
}

Imports MessagingToolkit.Barcode
Imports System.Drawing

Public Function ReadBarcodeValue(imagePath As String) As String
    Dim decoder As New BarcodeDecoder()
    Using bitmap As New Bitmap(imagePath)
        Dim result = decoder.Decode(bitmap)
        Return If(result IsNot Nothing, result.Text, Nothing)
    End Using
End Function

IronBarcode Approach:

using IronBarCode;

public string ReadBarcodeValue(string imagePath)
{
    var results = BarcodeReader.Read(imagePath);
    return results.FirstOrDefault()?.Value;
}

using IronBarCode;

public string ReadBarcodeValue(string imagePath)
{
    var results = BarcodeReader.Read(imagePath);
    return results.FirstOrDefault()?.Value;
}

Imports IronBarCode

Public Function ReadBarcodeValue(imagePath As String) As String
    Dim results = BarcodeReader.Read(imagePath)
    Return results.FirstOrDefault()?.Value
End Function

The IronBarcode version removes the Bitmap construction and the null-conditional pattern on a single object. BarcodeReader.Read() returns a collection — an empty collection when nothing is found — so .FirstOrDefault() replaces the null check on the old single-result return value.

Accessing Format Information from Results

MessagingToolkit.Barcode exposed the detected format through result.BarcodeFormat. IronBarcode exposes it through result.BarcodeType. Both are enum values on the result object, with different enum type names.

MessagingToolkit.Barcode Approach:

using MessagingToolkit.Barcode;
using System.Drawing;

var decoder = new BarcodeDecoder();
using (var bitmap = new Bitmap("barcode.png"))
{
    var result = decoder.Decode(bitmap);
    if (result != null)
    {
        Console.WriteLine($"Value: {result.Text}");
        Console.WriteLine($"Format: {result.BarcodeFormat}");
    }
}

using MessagingToolkit.Barcode;
using System.Drawing;

var decoder = new BarcodeDecoder();
using (var bitmap = new Bitmap("barcode.png"))
{
    var result = decoder.Decode(bitmap);
    if (result != null)
    {
        Console.WriteLine($"Value: {result.Text}");
        Console.WriteLine($"Format: {result.BarcodeFormat}");
    }
}

Imports MessagingToolkit.Barcode
Imports System.Drawing

Dim decoder As New BarcodeDecoder()
Using bitmap As New Bitmap("barcode.png")
    Dim result = decoder.Decode(bitmap)
    If result IsNot Nothing Then
        Console.WriteLine($"Value: {result.Text}")
        Console.WriteLine($"Format: {result.BarcodeFormat}")
    End If
End Using

IronBarcode Approach:

using IronBarCode;

var results = BarcodeReader.Read("barcode.png");
var first = results.FirstOrDefault();
if (first != null)
{
    Console.WriteLine($"Value: {first.Value}");
    Console.WriteLine($"Format: {first.BarcodeType}");
}

using IronBarCode;

var results = BarcodeReader.Read("barcode.png");
var first = results.FirstOrDefault();
if (first != null)
{
    Console.WriteLine($"Value: {first.Value}");
    Console.WriteLine($"Format: {first.BarcodeType}");
}

Imports IronBarCode

Dim results = BarcodeReader.Read("barcode.png")
Dim first = results.FirstOrDefault()
If first IsNot Nothing Then
    Console.WriteLine($"Value: {first.Value}")
    Console.WriteLine($"Format: {first.BarcodeType}")
End If

The property name changes from .Text to .Value and from .BarcodeFormat to .BarcodeType. The enum type changes from BarcodeFormat (MessagingToolkit) to BarcodeEncoding (IronBarcode), though .BarcodeType.ToString() produces a comparable human-readable string for display or logging purposes.

Generating Barcodes

MessagingToolkit.Barcode used an instance-based BarcodeEncoder with a property-set format before calling .Encode(). IronBarcode uses a static method with the encoding type as a parameter.

MessagingToolkit.Barcode Approach:

using MessagingToolkit.Barcode;

public void GenerateQrCode(string data, string outputPath)
{
    var encoder = new BarcodeEncoder();
    encoder.Format = BarcodeFormat.QrCode;
    var bitmap = encoder.Encode(data);
    bitmap.Save(outputPath);
}

using MessagingToolkit.Barcode;

public void GenerateQrCode(string data, string outputPath)
{
    var encoder = new BarcodeEncoder();
    encoder.Format = BarcodeFormat.QrCode;
    var bitmap = encoder.Encode(data);
    bitmap.Save(outputPath);
}

Imports MessagingToolkit.Barcode

Public Sub GenerateQrCode(data As String, outputPath As String)
    Dim encoder As New BarcodeEncoder()
    encoder.Format = BarcodeFormat.QrCode
    Dim bitmap = encoder.Encode(data)
    bitmap.Save(outputPath)
End Sub

IronBarcode Approach:

using IronBarCode;

public void GenerateQrCode(string data, string outputPath)
{
    BarcodeWriter.CreateBarcode(data, BarcodeEncoding.QRCode)
        .SaveAsPng(outputPath);
}

using IronBarCode;

public void GenerateQrCode(string data, string outputPath)
{
    BarcodeWriter.CreateBarcode(data, BarcodeEncoding.QRCode)
        .SaveAsPng(outputPath);
}

Imports IronBarCode

Public Sub GenerateQrCode(data As String, outputPath As String)
    BarcodeWriter.CreateBarcode(data, BarcodeEncoding.QRCode) _
        .SaveAsPng(outputPath)
End Sub

For creating Code 128 and other 1D barcodes, the same static pattern applies with a different encoding constant:

// Code 128
BarcodeWriter.CreateBarcode("PRODUCT-12345", BarcodeEncoding.Code128)
    .SaveAsPng("code128.png");

// EAN-13
BarcodeWriter.CreateBarcode("5901234123457", BarcodeEncoding.EAN13)
    .SaveAsPng("ean13.png");

// Code 128
BarcodeWriter.CreateBarcode("PRODUCT-12345", BarcodeEncoding.Code128)
    .SaveAsPng("code128.png");

// EAN-13
BarcodeWriter.CreateBarcode("5901234123457", BarcodeEncoding.EAN13)
    .SaveAsPng("ean13.png");

' Code 128
BarcodeWriter.CreateBarcode("PRODUCT-12345", BarcodeEncoding.Code128) _
    .SaveAsPng("code128.png")

' EAN-13
BarcodeWriter.CreateBarcode("5901234123457", BarcodeEncoding.EAN13) _
    .SaveAsPng("ean13.png")

Updating the Target Framework

Once MessagingToolkit.Barcode is removed and all references are replaced, the project file target framework can be updated. This change was blocked by the old dependency and becomes possible after removal:

MessagingToolkit.Barcode Approach (project file):

<PropertyGroup>
  <TargetFramework>net472</TargetFramework>
</PropertyGroup>

<PropertyGroup>
  <TargetFramework>net472</TargetFramework>
</PropertyGroup>

IronBarcode Approach (project file):

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
</PropertyGroup>

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
</PropertyGroup>

IronBarcode supports .NET Framework 4.6.2 through .NET 9, so it can be installed before the framework upgrade is finalized. This allows the migration to be staged: install IronBarcode alongside MessagingToolkit.Barcode, replace all usages, verify the new code, remove the old package, and then change the target framework as a final step.

Reading Barcodes from PDF Documents

MessagingToolkit.Barcode had no PDF support. Reading barcodes from a PDF required extracting images from each page through a separate library before calling the barcode decoder. IronBarcode reads PDF files directly through the same method used for images.

MessagingToolkit.Barcode Approach:

// Not supported — required external PDF page extraction before decode
// No equivalent exists in MessagingToolkit.Barcode

// Not supported — required external PDF page extraction before decode
// No equivalent exists in MessagingToolkit.Barcode

' Not supported — required external PDF page extraction before decode
' No equivalent exists in MessagingToolkit.Barcode

IronBarcode Approach:

using IronBarCode;

// Read all barcodes from every page of a PDF document
var results = BarcodeReader.Read("invoice.pdf");
foreach (var barcode in results)
{
    Console.WriteLine($"Page {barcode.PageNumber}: {barcode.Value} ({barcode.BarcodeType})");
}

using IronBarCode;

// Read all barcodes from every page of a PDF document
var results = BarcodeReader.Read("invoice.pdf");
foreach (var barcode in results)
{
    Console.WriteLine($"Page {barcode.PageNumber}: {barcode.Value} ({barcode.BarcodeType})");
}

Imports IronBarCode

' Read all barcodes from every page of a PDF document
Dim results = BarcodeReader.Read("invoice.pdf")
For Each barcode In results
    Console.WriteLine($"Page {barcode.PageNumber}: {barcode.Value} ({barcode.BarcodeType})")
Next

Applications that process scanned documents, shipping manifests, or multi-page invoice batches gain this capability as part of the migration without any additional library or configuration.

Issue 1: Namespace Not Found After Package Update

Problem: After removing MessagingToolkit.Barcode and adding IronBarcode, compilation fails with CS0246: The type or namespace name 'BarcodeDecoder' could not be found.

Solution: The old namespace using MessagingToolkit.Barcode; must be replaced with using IronBarCode; (note the capital C) in every file that references the old library. A project-wide search for the old namespace string will locate all affected files:

grep -r "using MessagingToolkit.Barcode" --include="*.cs" .
grep -r "BarcodeDecoder\|BarcodeEncoder" --include="*.cs" .

grep -r "using MessagingToolkit.Barcode" --include="*.cs" .
grep -r "BarcodeDecoder\|BarcodeEncoder" --include="*.cs" .

Issue 2: BarcodeReader Ambiguity Between Namespaces

Problem: If a project references both MessagingToolkit.Barcode and IronBarcode during a staged migration, BarcodeReader may be ambiguous between the two namespaces.

Solution: Qualify the reference explicitly during the transition period:

// Use the fully qualified name while both packages are installed
var results = IronBarCode.BarcodeReader.Read("barcode.png");

// Use the fully qualified name while both packages are installed
var results = IronBarCode.BarcodeReader.Read("barcode.png");

Imports IronBarCode

Dim results = BarcodeReader.Read("barcode.png")

Once all references to MessagingToolkit.Barcode have been replaced and the old package is removed, the qualifier can be dropped and the using IronBarCode; directive is sufficient.

Issue 3: Target Framework Still Set to net472 After Package Removal

Problem: After removing MessagingToolkit.Barcode and installing IronBarcode, the project file still targets net472. Build warnings indicate that modern .NET APIs are unavailable.

Solution: Update the <TargetFramework> element in the .csproj file once the dependency has been removed. IronBarcode supports both net472 (via .NET Framework 4.6.2 compatibility) and modern targets. Changing to net8.0 requires verifying that no other legacy dependencies remain in the project:

<TargetFramework>net8.0</TargetFramework>

<TargetFramework>net8.0</TargetFramework>

Run dotnet build after the change to identify any remaining legacy dependencies that need to be addressed.

Pre-Migration Tasks

Audit the codebase to identify all locations that reference MessagingToolkit.Barcode:

# Find all using statements
grep -r "using MessagingToolkit.Barcode" --include="*.cs" .

# Find decoder instantiations
grep -r "BarcodeDecoder" --include="*.cs" .

# Find encoder instantiations
grep -r "BarcodeEncoder" --include="*.cs" .

# Find decode calls
grep -r "\.Decode(" --include="*.cs" .

# Find encode calls
grep -r "\.Encode(" --include="*.cs" .

# Find project file references
grep -r "MessagingToolkit" --include="*.csproj" .
grep -r "MessagingToolkit" --include="packages.config" .

# Find all using statements
grep -r "using MessagingToolkit.Barcode" --include="*.cs" .

# Find decoder instantiations
grep -r "BarcodeDecoder" --include="*.cs" .

# Find encoder instantiations
grep -r "BarcodeEncoder" --include="*.cs" .

# Find decode calls
grep -r "\.Decode(" --include="*.cs" .

# Find encode calls
grep -r "\.Encode(" --include="*.cs" .

# Find project file references
grep -r "MessagingToolkit" --include="*.csproj" .
grep -r "MessagingToolkit" --include="packages.config" .

Document all files that require changes. Note any locations where System.Drawing.Bitmap is used as input to the decoder — those usages will also need to be updated.

Code Update Tasks

1. Run dotnet remove package MessagingToolkit.Barcode to remove the package
2. Run dotnet add package IronBarcode to install IronBarcode
3. Add IronBarCode.License.LicenseKey = "YOUR-KEY"; at application startup
4. Replace all using MessagingToolkit.Barcode; statements with using IronBarCode;
5. Replace all new BarcodeDecoder() patterns with BarcodeReader.Read() static calls
6. Replace all new BarcodeEncoder() patterns with BarcodeWriter.CreateBarcode() static calls
7. Update all result.Text references to result.Value
8. Update all result.BarcodeFormat references to result.BarcodeType
9. Update all barcodeWriter.Format = BarcodeFormat.X patterns to pass encoding as parameter
10. Replace bitmap.Save() with .SaveAsPng() or the appropriate output method on the IronBarcode result
11. Remove using System.Drawing; imports where they were used only for Bitmap input to MessagingToolkit
12. Update <TargetFramework> in the project file if a framework upgrade is part of the migration

Post-Migration Testing

• Verify that dotnet build completes with zero errors and zero references to MessagingToolkit
• Run grep -r "MessagingToolkit" --include="*.cs" . and confirm zero results
• Test barcode reading with real barcode images from your application and confirm .Value returns the expected string
• Test barcode reading with multi-barcode images and confirm all barcodes in the collection are returned
• Test barcode generation and verify the output file matches the expected format and encoding
• If PDF reading is used, test with a representative PDF document and verify page number metadata is correct
• If the target framework was changed, run the full test suite on the new runtime to identify any other compatibility issues