O Sistema de Duas Chaves Explicado

A BarcodeXpress divide o licenciamento em duas camadas conceitualmente distintas:

// BarcodeXpress: two separate license keys required
using Accusoft.BarcodeXpressSdk;

// Constructor takes the path to the runtime files (e.g. ".").
var barcodeXpress = new BarcodeXpress(".");

// Step 1: SDK license (for development).
// SetSolutionName and SetSolutionKey are methods, not properties.
// SetSolutionKey takes four 32-bit integers (not a parsed long).
barcodeXpress.Licensing.SetSolutionName("YourCompanyName");
barcodeXpress.Licensing.SetSolutionKey(1, 2, 3, 4);

// Step 2: OEM/runtime license (for production — minimum 5 purchased).
try
{
    barcodeXpress.Licensing.SetOEMLicenseKey("YourOEMLicenseString");
}
catch (Exception ex)
{
    // Without a valid OEM license, the SDK runs in stamped evaluation mode.
    Console.WriteLine($"OEM license activation failed: {ex.Message}");
}

// BarcodeXpress: two separate license keys required
using Accusoft.BarcodeXpressSdk;

// Constructor takes the path to the runtime files (e.g. ".").
var barcodeXpress = new BarcodeXpress(".");

// Step 1: SDK license (for development).
// SetSolutionName and SetSolutionKey are methods, not properties.
// SetSolutionKey takes four 32-bit integers (not a parsed long).
barcodeXpress.Licensing.SetSolutionName("YourCompanyName");
barcodeXpress.Licensing.SetSolutionKey(1, 2, 3, 4);

// Step 2: OEM/runtime license (for production — minimum 5 purchased).
try
{
    barcodeXpress.Licensing.SetOEMLicenseKey("YourOEMLicenseString");
}
catch (Exception ex)
{
    // Without a valid OEM license, the SDK runs in stamped evaluation mode.
    Console.WriteLine($"OEM license activation failed: {ex.Message}");
}

Imports Accusoft.BarcodeXpressSdk

' BarcodeXpress: two separate license keys required

' Constructor takes the path to the runtime files (e.g. ".").
Dim barcodeXpress As New BarcodeXpress(".")

' Step 1: SDK license (for development).
' SetSolutionName and SetSolutionKey are methods, not properties.
' SetSolutionKey takes four 32-bit integers (not a parsed long).
barcodeXpress.Licensing.SetSolutionName("YourCompanyName")
barcodeXpress.Licensing.SetSolutionKey(1, 2, 3, 4)

' Step 2: OEM/runtime license (for production — minimum 5 purchased).
Try
    barcodeXpress.Licensing.SetOEMLicenseKey("YourOEMLicenseString")
Catch ex As Exception
    ' Without a valid OEM license, the SDK runs in stamped evaluation mode.
    Console.WriteLine($"OEM license activation failed: {ex.Message}")
End Try

O par SetSolutionKey ativa o próprio SDK. A chamada SetOEMLicenseKey ativa as capacidades de implantação em produção. Ambos devem estar presentes e válidos para que uma implantação em produção retorne valores de código de barras sem o carimbo " UNLICENSED accusoft.com ".

Na revisão de código, esse padrão gera uma pergunta previsível: 'Por que temos duas ativações de licença separadas?' A resposta — que a Accusoft trata o licenciamento SDK e o licenciamento de implantação como produtos separados com faturamento separado — nem sempre é óbvia na própria API. As equipes que fazem manutenção desse código seis meses após a configuração inicial geralmente precisam consultar a documentação para entender qual tecla corresponde a qual função.

Sem uma licença OEM válida, SetOEMLicenseKey é lançado e o SDK volta para o modo de avaliação. As equipes normalmente envolvem a ativação em try/catch para que a falha seja registrada em alto volume, em vez de produzir silenciosamente valores de códigos de barras carimbados na produção:

try
{
    barcodeXpress.Licensing.SetOEMLicenseKey(oemKey);
}
catch (Exception ex)
{
    // In evaluation mode, barcode values are stamped with
    // " UNLICENSED accusoft.com " in the output.
    throw new InvalidOperationException(
        "OEM license activation failed — barcode values will be stamped", ex);
}

try
{
    barcodeXpress.Licensing.SetOEMLicenseKey(oemKey);
}
catch (Exception ex)
{
    // In evaluation mode, barcode values are stamped with
    // " UNLICENSED accusoft.com " in the output.
    throw new InvalidOperationException(
        "OEM license activation failed — barcode values will be stamped", ex);
}

Try
    barcodeXpress.Licensing.SetOEMLicenseKey(oemKey)
Catch ex As Exception
    ' In evaluation mode, barcode values are stamped with
    ' " UNLICENSED accusoft.com " in the output.
    Throw New InvalidOperationException("OEM license activation failed — barcode values will be stamped", ex)
End Try

Esse guarda é o padrão que as equipes adicionam quando percebem que a saída em modo de avaliação carimba os resultados silenciosamente em vez de lançar uma exceção durante a decodificação.

Comparação Detalhada de Recursos

Abordagem BarcodeXpress

using Accusoft.BarcodeXpressSdk;

public class BarcodeService
{
    private readonly BarcodeXpress _barcodeXpress;

    public BarcodeService()
    {
        _barcodeXpress = new BarcodeXpress(".");

        // Layer 1: SDK license
        _barcodeXpress.Licensing.SetSolutionName("AcmeCorp");
        _barcodeXpress.Licensing.SetSolutionKey(1, 2, 3, 4);

        // Layer 2: OEM/runtime license — separate purchase, minimum 5
        try
        {
            _barcodeXpress.Licensing.SetOEMLicenseKey("OEMLicenseString");
        }
        catch (Exception ex)
        {
            throw new InvalidOperationException(
                "OEM license activation failed — barcode values will be stamped", ex);
        }
    }
}

using Accusoft.BarcodeXpressSdk;

public class BarcodeService
{
    private readonly BarcodeXpress _barcodeXpress;

    public BarcodeService()
    {
        _barcodeXpress = new BarcodeXpress(".");

        // Layer 1: SDK license
        _barcodeXpress.Licensing.SetSolutionName("AcmeCorp");
        _barcodeXpress.Licensing.SetSolutionKey(1, 2, 3, 4);

        // Layer 2: OEM/runtime license — separate purchase, minimum 5
        try
        {
            _barcodeXpress.Licensing.SetOEMLicenseKey("OEMLicenseString");
        }
        catch (Exception ex)
        {
            throw new InvalidOperationException(
                "OEM license activation failed — barcode values will be stamped", ex);
        }
    }
}

Imports Accusoft.BarcodeXpressSdk

Public Class BarcodeService
    Private ReadOnly _barcodeXpress As BarcodeXpress

    Public Sub New()
        _barcodeXpress = New BarcodeXpress(".")

        ' Layer 1: SDK license
        _barcodeXpress.Licensing.SetSolutionName("AcmeCorp")
        _barcodeXpress.Licensing.SetSolutionKey(1, 2, 3, 4)

        ' Layer 2: OEM/runtime license — separate purchase, minimum 5
        Try
            _barcodeXpress.Licensing.SetOEMLicenseKey("OEMLicenseString")
        Catch ex As Exception
            Throw New InvalidOperationException("OEM license activation failed — barcode values will be stamped", ex)
        End Try
    End Sub
End Class

Este construtor existe inteiramente para gerenciar duas ativações de licença separadas antes que qualquer operação de código de barras possa ocorrer. O try/catch ao redor de SetOEMLicenseKey não é opcional — sem ele, o serviço retornará silenciosamente valores carimbados em qualquer ambiente onde a chave OEM esteja faltando ou mal configurada.

Abordagem do IronBarcode

using IronBarCode;

// In Program.cs or startup configuration
IronBarCode.License.LicenseKey = "YOUR-LICENSE-KEY";

using IronBarCode;

// In Program.cs or startup configuration
IronBarCode.License.LicenseKey = "YOUR-LICENSE-KEY";

Imports IronBarCode

' In Program.vb or startup configuration
IronBarCode.License.LicenseKey = "YOUR-LICENSE-KEY"

Esse é todo o conjunto de licenciamento. Nenhum desbloqueio de tempo de execução separado, nenhum nome de solução, nenhuma chamada UnlockRuntime com dois argumentos. No Docker, isso se torna uma variável de ambiente lida na inicialização. Em um pipeline de CI/CD, é um segredo. Em um orquestrador de contêineres, trata-se de uma variável de ambiente injetada no pod.

Abordagem BarcodeXpress

A leitura com BarcodeXpress requer carregar a imagem em um System.Drawing.Bitmap, atribuindo o conjunto de simbologia a reader.BarcodeTypes como um System.Array de valores BarcodeType, e chamando Analyze(bitmap) para recuperar os resultados. O SDK não lê PDFs diretamente — os formatos de entrada documentados são TIFF, JPEG, PNG e BMP:

using Accusoft.BarcodeXpressSdk;
using System.Drawing;

public IEnumerable<string> ReadAllBarcodes(string imagePath)
{
    var barcodeXpress = new BarcodeXpress(".");
    barcodeXpress.Licensing.SetSolutionName("AcmeCorp");
    barcodeXpress.Licensing.SetSolutionKey(1, 2, 3, 4);
    barcodeXpress.Licensing.SetOEMLicenseKey("OEMLicenseString");

    using var bitmap = new Bitmap(imagePath);

    // BarcodeTypes is a System.Array of BarcodeType values (not a [Flags]
    // enum). Pass Enum.GetValues to scan for everything, or assign a
    // narrower array to restrict the search space.
    barcodeXpress.reader.BarcodeTypes = new[]
    {
        BarcodeType.Code128Barcode,
        BarcodeType.DataMatrixBarcode,
        BarcodeType.QRCodeBarcode
    };

    Result[] results = barcodeXpress.reader.Analyze(bitmap);
    return results.Select(r => r.BarcodeValue);
}

using Accusoft.BarcodeXpressSdk;
using System.Drawing;

public IEnumerable<string> ReadAllBarcodes(string imagePath)
{
    var barcodeXpress = new BarcodeXpress(".");
    barcodeXpress.Licensing.SetSolutionName("AcmeCorp");
    barcodeXpress.Licensing.SetSolutionKey(1, 2, 3, 4);
    barcodeXpress.Licensing.SetOEMLicenseKey("OEMLicenseString");

    using var bitmap = new Bitmap(imagePath);

    // BarcodeTypes is a System.Array of BarcodeType values (not a [Flags]
    // enum). Pass Enum.GetValues to scan for everything, or assign a
    // narrower array to restrict the search space.
    barcodeXpress.reader.BarcodeTypes = new[]
    {
        BarcodeType.Code128Barcode,
        BarcodeType.DataMatrixBarcode,
        BarcodeType.QRCodeBarcode
    };

    Result[] results = barcodeXpress.reader.Analyze(bitmap);
    return results.Select(r => r.BarcodeValue);
}

Imports Accusoft.BarcodeXpressSdk
Imports System.Drawing

Public Function ReadAllBarcodes(imagePath As String) As IEnumerable(Of String)
    Dim barcodeXpress = New BarcodeXpress(".")
    barcodeXpress.Licensing.SetSolutionName("AcmeCorp")
    barcodeXpress.Licensing.SetSolutionKey(1, 2, 3, 4)
    barcodeXpress.Licensing.SetOEMLicenseKey("OEMLicenseString")

    Using bitmap As New Bitmap(imagePath)
        ' BarcodeTypes is a System.Array of BarcodeType values (not a [Flags]
        ' enum). Pass Enum.GetValues to scan for everything, or assign a
        ' narrower array to restrict the search space.
        barcodeXpress.Reader.BarcodeTypes = New BarcodeType() {
            BarcodeType.Code128Barcode,
            BarcodeType.DataMatrixBarcode,
            BarcodeType.QRCodeBarcode
        }

        Dim results As Result() = barcodeXpress.Reader.Analyze(bitmap)
        Return results.Select(Function(r) r.BarcodeValue)
    End Using
End Function

Analyze recebe um Bitmap e retorna um Result[]. Se um documento contém um formato não presente no array BarcodeTypes, ele não será encontrado. Isso se torna um custo adicional de manutenção quando as fontes de documentos mudam. Os PDFs exigem pré-renderização para imagens com uma biblioteca separada antes de serem alimentados em Analyze.

Abordagem do IronBarcode

using IronBarCode;

public IEnumerable<string> ReadAllBarcodes(string imagePath)
{
    var results = BarcodeReader.Read(imagePath);
    return results.Select(r => r.Value);
}

using IronBarCode;

public IEnumerable<string> ReadAllBarcodes(string imagePath)
{
    var results = BarcodeReader.Read(imagePath);
    return results.Select(r => r.Value);
}

Imports IronBarCode

Public Function ReadAllBarcodes(imagePath As String) As IEnumerable(Of String)
    Dim results = BarcodeReader.Read(imagePath)
    Return results.Select(Function(r) r.Value)
End Function

O IronBarcode detecta automaticamente o formato em todas as simbologias suportadas. Se a imagem contiver um código 128, um código QR e um DataMatrix, os três serão retornados na coleção de resultados sem qualquer alteração de configuração. Para maior controle sobre o comportamento de leitura, a classe BarcodeReaderOptions expõe configurações de velocidade, número de threads e múltiplos códigos de barras.

A leitura nativa de PDFs também está disponível pelo mesmo método:

using IronBarCode;

// Nativo PDF support — no separate library needed
var results = BarcodeReader.Read("invoice-batch.pdf");

foreach (var result in results)
{
    Console.WriteLine($"Page {result.PageNumber}: [{result.Format}] {result.Value}");
}

using IronBarCode;

// Nativo PDF support — no separate library needed
var results = BarcodeReader.Read("invoice-batch.pdf");

foreach (var result in results)
{
    Console.WriteLine($"Page {result.PageNumber}: [{result.Format}] {result.Value}");
}

Imports IronBarCode

' Nativo PDF support — no separate library needed
Dim results = BarcodeReader.Read("invoice-batch.pdf")

For Each result In results
    Console.WriteLine($"Page {result.PageNumber}: [{result.Format}] {result.Value}")
Next

O BarcodeXpress não lê PDFs nativamente. Primeiro, você precisa renderizar cada página como uma imagem, usando uma biblioteca separada, e depois passar essas imagens para o leitor BarcodeXpress. Isso adiciona uma dependência, uma etapa de conversão e outro custo de licenciamento, dependendo da biblioteca de PDF escolhida.

Abordagem BarcodeXpress

BarcodeXpress é baseado em instância e seu objeto reader é stateful. O processamento paralelo requer uma instância por thread, com a inicialização completa da licença de duas camadas repetida em cada contexto de thread:

using Accusoft.BarcodeXpressSdk;
using System.Collections.Generic;
using System.Drawing;

public Dictionary<string, string> ProcessBatch(IEnumerable<string> imagePaths)
{
    var results = new Dictionary<string, string>();

    foreach (var path in imagePaths)
    {
        using var bitmap = new Bitmap(path);

        _barcodeXpress.reader.BarcodeTypes = new[]
        {
            BarcodeType.Code128Barcode,
            BarcodeType.QRCodeBarcode
        };

        var barcodes = _barcodeXpress.reader.Analyze(bitmap);
        if (barcodes.Length > 0)
            results[path] = barcodes[0].BarcodeValue;
    }

    return results;
}

using Accusoft.BarcodeXpressSdk;
using System.Collections.Generic;
using System.Drawing;

public Dictionary<string, string> ProcessBatch(IEnumerable<string> imagePaths)
{
    var results = new Dictionary<string, string>();

    foreach (var path in imagePaths)
    {
        using var bitmap = new Bitmap(path);

        _barcodeXpress.reader.BarcodeTypes = new[]
        {
            BarcodeType.Code128Barcode,
            BarcodeType.QRCodeBarcode
        };

        var barcodes = _barcodeXpress.reader.Analyze(bitmap);
        if (barcodes.Length > 0)
            results[path] = barcodes[0].BarcodeValue;
    }

    return results;
}

Imports Accusoft.BarcodeXpressSdk
Imports System.Collections.Generic
Imports System.Drawing

Public Function ProcessBatch(imagePaths As IEnumerable(Of String)) As Dictionary(Of String, String)
    Dim results As New Dictionary(Of String, String)()

    For Each path In imagePaths
        Using bitmap As New Bitmap(path)
            _barcodeXpress.reader.BarcodeTypes = New BarcodeType() {
                BarcodeType.Code128Barcode,
                BarcodeType.QRCodeBarcode
            }

            Dim barcodes = _barcodeXpress.reader.Analyze(bitmap)
            If barcodes.Length > 0 Then
                results(path) = barcodes(0).BarcodeValue
            End If
        End Using
    Next

    Return results
End Function

A Edição Padrão também impõe um limite máximo de 40 páginas por minuto. Um lote de 100.000 documentos a 40 PPM leva aproximadamente 41 horas para ser concluído. A Edição Professional remove esse limite, mas a um custo mais elevado por desenvolvedor — além das licenças de tempo de execução já adquiridas.

Abordagem do IronBarcode

using IronBarCode;
using System.Collections.Concurrent;
using System.Threading.Tasks;

//IronBarcode— parallel batch with thread-safe static API
var files = Directory.GetFiles("/incoming/scans", "*.png");
var allResults = new ConcurrentBag<string>();

Parallel.ForEach(files, file =>
{
    var r = BarcodeReader.Read(file);
    foreach (var barcode in r)
        allResults.Add($"{file}: {barcode.Value}");
});

using IronBarCode;
using System.Collections.Concurrent;
using System.Threading.Tasks;

//IronBarcode— parallel batch with thread-safe static API
var files = Directory.GetFiles("/incoming/scans", "*.png");
var allResults = new ConcurrentBag<string>();

Parallel.ForEach(files, file =>
{
    var r = BarcodeReader.Read(file);
    foreach (var barcode in r)
        allResults.Add($"{file}: {barcode.Value}");
});

Imports IronBarCode
Imports System.Collections.Concurrent
Imports System.Threading.Tasks

'IronBarcode— parallel batch with thread-safe static API
Dim files = Directory.GetFiles("/incoming/scans", "*.png")
Dim allResults = New ConcurrentBag(Of String)()

Parallel.ForEach(files, Sub(file)
    Dim r = BarcodeReader.Read(file)
    For Each barcode In r
        allResults.Add($"{file}: {barcode.Value}")
    Next
End Sub)

Como os métodos estáticos de IronBarcode não têm estado, Parallel.ForEach sobre eles é seguro sem exigir isolamento de instância. A IronBarcode não impõe limite de produção em nenhum nível de preço. Para ajustar o desempenho de leitura, a classe BarcodeReaderOptions fornece configurações ReadingSpeed e MaxParallelThreads:

using IronBarCode;

var options = new BarcodeReaderOptions
{
    Speed = ReadingSpeed.Balanced,
    ExpectMultipleBarcodes = true,
    MaxParallelThreads = 4
};

var results = BarcodeReader.Read("warehouse-scan.png", options);

using IronBarCode;

var options = new BarcodeReaderOptions
{
    Speed = ReadingSpeed.Balanced,
    ExpectMultipleBarcodes = true,
    MaxParallelThreads = 4
};

var results = BarcodeReader.Read("warehouse-scan.png", options);

Imports IronBarCode

Dim options As New BarcodeReaderOptions With {
    .Speed = ReadingSpeed.Balanced,
    .ExpectMultipleBarcodes = True,
    .MaxParallelThreads = 4
}

Dim results = BarcodeReader.Read("warehouse-scan.png", options)

ReadingSpeed.Balanced é o padrão. Use ReadingSpeed.Faster para pipelines de alta vazão onde os códigos de barra estão limpos, ou ReadingSpeed.Detailed para imagens danificadas ou de baixo contraste.

Superando a barreira dos 40 PPM

O limite da Edição Padrão de 40 páginas por minuto parece generoso até que uma equipe comercial decida executar um processamento em lote no final do dia em um ano inteiro de faturas arquivadas. Um lote de 100.000 documentos, nesse ritmo, leva aproximadamente 41 horas para ser concluído. A migração para a Edição Professional remove o limite, mas com um custo mais elevado por licença de desenvolvedor — além das licenças de tempo de execução já adquiridas. As equipes que descobrem o limite de produção após a assinatura de um pedido de compra frequentemente constatam que o custo total para removê-lo excede substancialmente as estimativas iniciais.

Complexidade do licenciamento do pipeline CI/CD

Uma configuração típica de CI/CD executa builds em contêineres efêmeros. Com o BarcodeXpress, cada ambiente de compilação precisa ter disponíveis tanto o par de chaves do SDK quanto as chaves de desbloqueio em tempo de execução, gerenciadas como segredos separados. Se a chave de tempo de execução estiver ausente ou mal configurada, a compilação pode ser bem-sucedida, mas os testes de integração retornarão valores ocultos — um modo de falha silencioso que é fácil de passar despercebido em um pipeline de testes se as asserções de teste não forem escritas cuidadosamente em relação ao conteúdo real do código de barras.

Requisitos de implantação em ambiente isolado e seguro

Alguns ambientes — como sistemas de saúde que processam registros de pacientes, fluxos de trabalho de documentos governamentais e processamento administrativo de instituições financeiras — não podem ter a validação de licenças para fazer chamadas de rede de saída. O sistema de licenciamento de tempo de execução do BarcodeXpress envolve a infraestrutura de licenciamento da Accusoft, o que pode representar um problema de conformidade em ambientes com restrições rigorosas de saída de rede. As equipes que operam nesses ambientes geralmente optam por bibliotecas cuja validação de licença é inteiramente local.

Implantação de contêineres e Docker

Normalmente, o BarcodeXpress no Docker exige que o contêiner monte um arquivo de licença em um caminho conhecido ou que configure um servidor de licenças e direcione o contêiner para ele. Ambas as abordagens aumentam a complexidade de implementação — os arquivos de licença precisam ser distribuídos e mantidos sincronizados, e um servidor de licenças é uma peça adicional de infraestrutura que precisa ser mantida. Equipes que migram para arquiteturas de microsserviços ou padrões de implantação sem servidor descobrem que a abordagem de arquivo de configuração não se traduz facilmente em imagens de contêiner imutáveis.

Requisitos de precisão da avaliação

Equipes que precisam validar a precisão de leitura em seus próprios documentos antes de efetuar uma compra consideram o modo de avaliação do BarcodeXpress fundamentalmente limitante. Os testes com base em digitalizações de documentos reais — verificando se a biblioteca lida bem com códigos de barras de baixo contraste, imagens distorcidas ou páginas com vários códigos de barras — exigem valores decodificados completos. A saída parcialmente oculta revela apenas que a biblioteca encontrou um código de barras, não se o leu corretamente.

Gerenciamento de instâncias para chamadas estáticas

BarcodeXpress exige que uma instância BarcodeXpress seja criada e licenciada antes de qualquer operação. Os métodos estáticos do IronBarcode não precisam de instância. As equipes que migram tipicamente têm uma classe BarcodeService cujo construtor é em grande parte um boilerplate de licenciamento — após a migração, esse construtor pode ser removido inteiramente ou reduzido a uma única atribuição de chave de licença.

Remoção da enumeração de tipos de código de barras

Toda operação de leitura do BarcodeXpress requer a atribuição da Array BarcodeTypes para enumerar quais simbologias procurar. Por padrão, o IronBarcode detecta automaticamente todos os formatos suportados. Durante a migração, todas as atribuições reader.BarcodeTypes = ... podem ser excluídas sem substituição. Se houver um motivo de desempenho para restringir o espaço de pesquisa, BarcodeReaderOptions suporta filtragem de formato como opt-in explícito em vez de um padrão obrigatório.

Alterações no nome da propriedade de resultado

Duas renomeações de propriedades afetam todo o código de processamento de resultados: result.BarcodeValue se torna result.Value, e result.BarcodeType se torna result.Format. Uma função de busca e substituição em toda a solução resolve ambos os problemas. Os resultados do IronBarcode também expõem result.Confidence e result.PageNumber, que não têm equivalente no BarcodeXpress e podem ser usados para filtragem adicional sem alterações no código de manipulação de resultados existentes.

Configuração de licença do Docker

As implementações do BarcodeXpress em Docker normalmente usam um arquivo de configuração de licença montado. O IronBarcode usa uma variável de ambiente. A migração envolve remover a instrução COPY do arquivo de configuração e adicionar uma única atribuição de variável de ambiente. No Kubernetes, a chave de licença se torna uma referência secreta na especificação do pod, em vez de um volume montado.