IRONSOFTWAREHOME
MIGRATION GUIDES

Migrating from MessagingToolkit.Barcode to IronBarcode

Curtis Chau
Curtis Chau
Updated: August 1, 2026

MessagingToolkit.Barcode published its final release - version 1.7.0.2 - in 2013 and has received no updates since. This guide covers the complete migration path to IronBarcode: why the migration is necessary, what changes in the code, and how to verify the migration is complete. The guide addresses both teams migrating barcode functionality in isolation and teams undertaking a broader .NET framework upgrade for which MessagingToolkit.Barcode is a blocking dependency.

Why Migrate from MessagingToolkit.Barcode

Framework Compatibility Blocker: MessagingToolkit.Barcode targets .NET Framework 3.5, 4.0, and 4.5. It has no .NET Standard target and no .NET Core target. When any project file that references this package is set to a modern .NET target framework - .NET 6, .NET 7, .NET 8, or .NET 9 - the NuGet restore operation fails with a framework compatibility error. The build does not proceed. This is not a warning or a runtime degradation; it is a compile-time failure that prevents the project from building at all. Removing MessagingToolkit.Barcode is a prerequisite for any .NET framework upgrade, not an optional cleanup step.

Security Exposure: Twelve years have elapsed since the last code change. Any vulnerability discovered after 2014 in the library's image parsing logic, its ZXing-derived decode implementation, or its transitive dependencies has no patch, no advisory, and no maintainer to contact. Security scanning tools flag the package as abandoned. Compliance frameworks - PCI DSS, HIPAA, SOC 2, ISO 27001 - require active patch management of third-party software. An abandoned package fails these audits on process grounds regardless of whether a specific CVE has been identified.

Discontinued Platform Targets: The NuGet package metadata lists Silverlight 3, 4, and 5 as target platforms; all three were discontinued in 2021. Windows Phone 7.0, 7.5, 7.8, and 8.0 are listed; end of support for these platforms occurred between 2014 and 2017. The library was never updated to target any platform that succeeded these discontinued environments.

Capability Gaps: MessagingToolkit.Barcode accepted only System.Drawing.Bitmap inputs, which is Windows-only in .NET 6 and later. It returned a single result per decode call, with no support for multi-barcode images. It had no PDF reading capability - applications that needed to read barcodes from PDF documents required a separate extraction step before calling the library. Output generation returned a Bitmap, requiring a System.Drawing.Imaging import and preventing cross-platform deployment.

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

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-LICENSE-KEY";

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

IronBarcode vs MessagingToolkit.Barcode: Feature Comparison

FeatureMessagingToolkit.BarcodeIronBarcode
Last updated20142026 (active)
NuGet version1.7.0.2 (final)Current, regularly updated
.NET 6 / 7 / 8 / 9 supportNoYes
.NET Framework 4.6.2+NoYes
.NET Framework 3.5-4.5YesNo
.NET Core supportNoYes
ASP.NET CoreNoYes
.NET MAUINoYes
BlazorNoYes
Cross-platform (Linux, macOS)NoYes
Docker / container supportNoYes
Barcode reading input typesBitmap onlyPath, stream, byte array, PDF
PDF barcode readingNoYes (native)
Multi-barcode per imageNoYes
Automatic format detectionNoYes
Barcode generation output formatsBitmap onlyPNG, JPEG, SVG, PDF, byte array
System.Drawing dependencyRequiredNone
Security patchesNone since 2014Regular patches
Commercial supportNoneProfessional support available
Compliance audit resultFlagged as abandonedPasses standard audits

Quick Start: MessagingToolkit.Barcode to IronBarcode Migration

Step 1: Replace NuGet Package

Remove the MessagingToolkit.Barcode package:

dotnet remove package MessagingToolkit.Barcode
SHELL

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
SHELL

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;

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-LICENSE-KEY";

Code Migration Examples

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

IronBarcode Approach:

using IronBarCode;

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

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

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

The property name changes from .Text to .Value and from .BarcodeFormat to .Format. The enum type changes from BarcodeFormat (MessagingToolkit) to BarcodeEncoding (IronBarcode), though .Format.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);
}

IronBarcode Approach:

using IronBarCode;

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

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

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

IronBarcode Approach (project file):

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

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

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

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.

MessagingToolkit.Barcode API to IronBarcode Mapping Reference

MessagingToolkit.BarcodeIronBarcodeNotes
new BarcodeDecoder()Static - BarcodeReader.Read()No instance required
barcodeReader.Decode(bitmap)BarcodeReader.Read(path)Accepts path, stream, byte array, or PDF
result.Textresult.ValueProperty renamed
result.BarcodeFormatresult.FormatProperty renamed; enum type is BarcodeEncoding
new BarcodeEncoder()Static - BarcodeWriter.CreateBarcode()No instance required
barcodeWriter.Format = BarcodeFormat.QrCodeBarcodeEncoding.QRCode (parameter)Format passed as parameter, not property
barcodeWriter.Encode("data") returns BitmapBarcodeWriter.CreateBarcode("data", BarcodeEncoding.QRCode)Returns fluent result, not Bitmap
bitmap.Save("path.png").SaveAsPng("path.png")Fluent method on result object
BarcodeFormat.QrCodeBarcodeEncoding.QRCodeEnum namespace and value renamed
BarcodeFormat.Code128BarcodeEncoding.Code128Same symbolic name, different namespace
BarcodeFormat.Ean13BarcodeEncoding.EAN13Capitalization differs
Returns null if not foundReturns empty collectionCheck .Any() or .FirstOrDefault()
Bitmap input onlyPath, stream, byte array, PDFNo System.Drawing required
.NET Framework 3.5-4.5 only.NET 4.6.2 through .NET 9Full modern .NET support

Common Migration Issues and Solutions

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" .
SHELL

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

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:

<!-- Update this line in the .csproj file -->
<TargetFramework>net8.0</TargetFramework>
XML

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

MessagingToolkit.Barcode Migration Checklist

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" .
SHELL

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-LICENSE-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.Format
  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

Key Benefits of Migrating to IronBarcode

Unblocked Framework Upgrades: Once MessagingToolkit.Barcode is removed, the project file target framework can be updated to any modern .NET version. This single change enables access to .NET 8 performance improvements, C# 12 language features, native async patterns, and the full ecosystem of NuGet packages that require .NET Standard 2.0 or later.

Cross-Platform Deployment: IronBarcode's internal image pipeline does not depend on System.Drawing, which is Windows-only in .NET 6 and later. After migration, applications can be deployed to Linux servers, macOS development environments, Docker containers, and cloud function runtimes without encountering PlatformNotSupportedException from the barcode library.

Resolved Compliance Findings: IronBarcode receives regular security updates through a documented maintenance process. Replacing an abandoned dependency with an actively maintained one resolves audit findings under PCI DSS, HIPAA, SOC 2, and similar frameworks that require active patch management of third-party libraries.

Native PDF Support: BarcodeReader.Read() accepts PDF file paths directly, eliminating the need for a separate PDF image extraction step before barcode decoding. Applications that process scanned documents or invoice batches benefit from this capability without adding new libraries or pipeline stages.

Expanded Output Options: Generated barcodes are available as PNG, JPEG, SVG, PDF, or base64-encoded strings through the fluent result object returned by BarcodeWriter.CreateBarcode(). This replaces the System.Drawing.Bitmap return type from MessagingToolkit.Barcode, removing the Windows-only output constraint and enabling direct embedding in web responses or database storage.

Please note: MessagingToolkit and ZXing.NET are registered trademarks of their respective owners. This site is not affiliated with, endorsed by, or sponsored by MessagingToolkit or ZXing.NET. All product names, logos, and brands are property of their respective owners. Comparisons are for informational purposes only and reflect publicly available information at the time of writing.
Curtis Chau
Technical Writer

Curtis Chau holds a Bachelor’s degree in Computer Science (Carleton University) and specializes in front-end development with expertise in Node.js, TypeScript, JavaScript, and React. Passionate about crafting intuitive and aesthetically pleasing user interfaces, Curtis enjoys working with modern frameworks and creating well-structured, visually appealing manuals.

...
Read More

Related Articles

Key in blue circle

Get your free 30-day Trial Key instantly.

Your trial license will be sent to your email address

No limitations. 100% unlocked. No credit card.

bullet_checkedNo credit card or account creation requiredNo limitations. 100% unlocked. No credit card.
  • Logo Aetna
  • Logo NASA
  • Logo GE
  • Logo Porsche
  • Logo USDA
  • Logo Qatar
Join Millions of Engineers who’ve tried IronPDF
Book your free Live Demo
Booking Badge

Trusted by Millions of Engineers Worldwide

Iron Software's customer logos
Get Your No-Obligation Consult
Complete the form below or email sales@ironsoftware.com
Your details will always be kept confidential.
Trusted by Millions of Engineers Worldwide
Iron Software's customer logos
Get your free 30-day Trial Key instantly.
No credit card or account creation required