IRONSOFTWAREHOME

Como Lidar com Verificação de Nulo para Operações de Código de Barras em C#

Curtis Chau
Curtis Chau
Updated: 9 de maio de 2026

IronBarcode retorna os resultados da digitalização como uma coleção BarcodeResults em C# através de BarcodeReader.Read. Este método retorna nulo se a imagem de entrada não for reconhecida, ou uma coleção vazia se nenhum código de barras for detectado. BarcodeWriter.CreateBarcode lança uma exceção se a entrada for nula, vazia ou em um formato inválido.

Fontes de leitura do mundo real, como imagens de câmeras, uploads de documentos e scanners de armazém, nem sempre fornecem um código de barras legível. Acessar propriedades de resultado ou iterar a coleção sem verificar valores nulos ou vazios pode causar uma NullReferenceException em tempo de execução. Passar strings inválidas para a API de gravação pode resultar em uma ArgumentException. O uso de cláusulas de guarda em operações de leitura e gravação ajuda a prevenir essas exceções em produção.

Este tutorial explica como lidar com resultados nulos e vazios nas operações de leitura e escrita do IronBarcode usando cláusulas de proteção, filtragem por confiança e um padrão de validador reutilizável.


Início Rápido: Lidar com Resultados Nulos em Operações de Código de Barras

Use o padrão de proteção do IronBarcode para verificar com segurança a coleção BarcodeResults antes de acessar qualquer propriedade de resultado. Comece já com esta leitura rápida e verificação simples:

  1. 1Install IronBarcode with NuGet Package Manager

    PM > Install-Package BarCode

  2. 2Copie e execute este trecho de código.

    using IronBarCode;
    
    BarcodeResults results = BarcodeReader.Read("label.png");
    
    // Guard: null or empty
    if (results is null || results.Count == 0)
    {
        Console.WriteLine("No barcodes detected.");
        return;
    }
    
    Console.WriteLine(results.First().Value);
    C#
  3. 3Implante para testar em seu ambiente de produção.

    Comece a usar IronBarcode em seu projeto hoje com uma avaliação gratuita
    arrow pointer

Como Lidar com Resultados de Código de Barras Nulos e Vazios?

Existem dois modos de falha: BarcodeResults é nulo se a entrada não for uma imagem válida, e vazio se a imagem não contiver códigos de barras. Acessar First, Value, ou iterar sem verificar ambas as condições causará uma exceção em tempo de execução.

Verifique ambas as condições antes de entrar no loop de processamento:

Entrada

Um rótulo de envio de código de barras Code128 (caminho de sucesso) e uma imagem em branco sem código de barras (caminho de falha).

Código de barras Code128 codificando SHP-20240001 usado como entrada da etiqueta de envio

shipping-label.png (caminho de sucesso)

Imagem branca em branco sem código de barras usada para acionar o caminho de resultado vazio

blank-image.png (caminho com falha, sem código de barras presente)

using IronBarCode;

// BarcodeReader.Read() returns a BarcodeResults collection, not a single result
BarcodeResults results = BarcodeReader.Read("shipping-label.png");

// Null check: image was not recognized as a valid image source
// Empty check: image was valid but contained no detectable barcodes
if (results is null || results.Count == 0)
{
    // Log, return a default, or throw a domain-specific exception
    Console.WriteLine("No barcodes found in the input image.");
    return;
}

// Collection is safe to iterate; each BarcodeResult holds one decoded barcode
foreach (BarcodeResult result in results)
{
    // Guard individual result properties; partial scans or severely
    // damaged barcodes can produce results where .Value is empty or whitespace
    if (string.IsNullOrWhiteSpace(result.Value))
    {
        Console.WriteLine($"Empty value detected for {result.BarcodeType}");
        continue;
    }

    // BarcodeType identifies the symbology (Code128, QRCode, EAN8, etc.)
    Console.WriteLine($"Type: {result.BarcodeType}, Value: {result.Value}");
}

Cada BarcodeResult fornece propriedades de string Value e Text, ambas retornando o conteúdo decodificado do código de barras. Códigos de barras severamente danificados ou leituras parciais podem produzir valores vazios ou espaços em branco. Use string.IsNullOrWhiteSpace em cada resultado para evitar que valores vazios cheguem aos sistemas de downstream.

BarcodeReaderOptions também possui uma propriedade ConfidenceThreshold (0.0 a 1.0) que descarta leituras de baixa qualidade antes que elas cheguem à coleção de resultados:

using IronBarCode;

// ConfidenceThreshold filters low-quality reads before they enter the
// BarcodeResults collection. Reads below the threshold are discarded
// during scanning, not after, so no post-filtering of the collection is needed.
var options = new BarcodeReaderOptions
{
    ConfidenceThreshold = 0.7  // range 0.0 to 1.0; lower values accept weaker signals
};

BarcodeResults results = BarcodeReader.Read("shipping-label.png", options);

// Still check for null and empty even with a threshold applied;
// an image with no barcodes returns an empty collection, not null
if (results is null || results.Count == 0)
{
    Console.WriteLine("No barcodes met the confidence threshold.");
    return;
}

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

Como Aplicar Padrões Seguros para Nulos na Escrita de Códigos de Barras?

BarcodeWriter.CreateBarcode aceita um valor de string e uma enum BarcodeWriterEncoding ou BarcodeEncoding. Passar um valor nulo ou uma string vazia gera uma exceção imediatamente. Restrições de formato também se aplicam: EAN-8 aceita de 7 a 8 dígitos numéricos, UPC-A aceita de 11 a 12, e Code 128 possui um limite de caracteres. Validar a entrada antes da chamada evita que essas exceções entrem na etapa de codificação:

using IronBarCode;

// Input may arrive from user input, a database, or an API response
string inputValue = GetValueFromUserOrDatabase(); // Could be null

// Guard: null, empty, or whitespace input cannot produce a valid barcode
if (string.IsNullOrWhiteSpace(inputValue))
{
    Console.WriteLine("Cannot generate barcode: input value is null or empty.");
    return;
}

// Guard: format-specific constraints must be satisfied before encoding
// EAN-8 accepts exactly 7 or 8 numeric digits (the 8th is the check digit)
BarcodeWriterEncoding encoding = BarcodeWriterEncoding.EAN8;
if (encoding == BarcodeWriterEncoding.EAN8 && !System.Text.RegularExpressions.Regex.IsMatch(inputValue, @"^\d{7,8}$"))
{
    Console.WriteLine("EAN-8 requires exactly 7 or 8 numeric digits.");
    return;
}

// Input is validated; CreateBarcode will not throw for null or format mismatch
GeneratedBarcode barcode = BarcodeWriter.CreateBarcode(inputValue, encoding);
barcode.SaveAsPng("output-barcode.png");

Saída

Uma entrada válida de 7 dígitos (1234567) produz um código de barras EAN-8 escaneável. Entradas nulas, vazias ou não numéricas são detectadas pelas cláusulas de guarda e nunca chegam à etapa de codificação.

Código de barras EAN-8 gerado a partir da entrada válida de 7 dígitos: 1234567

A API de escrita também realiza sua própria validação interna: verifica os checksums, verifica as restrições de comprimento e rejeita caracteres inválidos para a codificação selecionada. As cláusulas de guarda acima detectam problemas mais cedo, dando ao chamador o controle sobre a mensagem de erro e o caminho de recuperação. Para uma lista completa de codificações suportadas e suas restrições, veja o como criar códigos de barras e o criar código de barras a partir de dados.


Como Validar Resultados Antes do Processamento Posterior?

Quando os dados do código de barras são enviados para outro sistema (uma gravação em banco de dados, uma chamada de API, uma impressora de etiquetas), é útil consolidar a contagem de resultados, a integridade dos valores e as verificações de tipo em um único método reutilizável antes de passar os dados adiante:

Entrada

Um escaneamento de armazém de código de barras Code128 usado como alvo de leitura para o validador.

O código de barras Code128 WH-SCAN-4471 foi usado como entrada de leitura no armazém para o exemplo de validação.
using IronBarCode;
using System.Collections.Generic;
using System.Linq;

// Reusable validation helper — consolidates null, empty, value, and
// expected-format checks into a single method. Returns an empty list
// (never null) so callers do not need to null-check the return value.
public static class BarcodeValidator
{
    public static List<BarcodeResult> GetValidResults(
        string imagePath,
        BarcodeEncoding? expectedType = null,
        double confidenceThreshold = 0.7)
    {
        // Apply confidence threshold at scan level via BarcodeReaderOptions
        var options = new BarcodeReaderOptions
        {
            ConfidenceThreshold = confidenceThreshold
        };

        BarcodeResults results = BarcodeReader.Read(imagePath, options);

        // Return empty list instead of null so callers never need to null-check the return value
        if (results is null || results.Count == 0)
            return new List<BarcodeResult>();

        return results
            .Where(r => !string.IsNullOrWhiteSpace(r.Value))           // skip results with empty decoded data
            .Where(r => expectedType == null || r.BarcodeType == expectedType) // null accepts any symbology
            .ToList();
    }
}

// Usage: pass the image path and the symbology you expect
var validated = BarcodeValidator.GetValidResults(
    "warehouse-scan.png",
    expectedType: BarcodeEncoding.Code128,
    confidenceThreshold: 0.7);

if (validated.Count == 0)
{
    // No valid results; log the failure and skip downstream processing
    return;
}

// All results have passed null, empty, type, and confidence checks
foreach (var barcode in validated)
{
    SendToInventorySystem(barcode.Value, barcode.BarcodeType.ToString()); // placeholder for your downstream call
}

O método retorna uma lista vazia em vez de nula, portanto, quem o chama nunca precisa verificar se o valor retornado é nulo. O parâmetro opcional expectedType filtra por simbologia, o que evita que o sistema de downstream receba formatos inesperados quando um escaneamento capta tanto um código QR quanto um Code 128 da mesma imagem.

Para leitura em lote de vários arquivos, aplique o mesmo padrão para cada arquivo e agregue os resultados. A opção ExpectBarcodeTypes em BarcodeReaderOptions reduz a digitalização para simbologias esperadas de antemão, então menos resultados indesejados chegam ao validador.


Leitura complementar

Veja as opções de licenciamento quando o pipeline estiver pronto para produção.

Perguntas frequentes

O que é checagem de nulo em operações de código de barras?

A verificação de nulo em operações de código de barras envolve verificar se um resultado ou entrada de código de barras é nulo para prevenir erros de execução e garantir um processamento de código de barras suave.

Por que a verificação de nulo é importante em operações de código de barras em C#?

A verificação de nulo é crucial em operações de código de barras em C# para evitar exceções e garantir que o aplicativo possa lidar graciosamente com casos em que os dados de código de barras possam estar ausentes ou inválidos.

Como o IronBarcode pode ajudar com a verificação de nulo?

O IronBarcode fornece métodos embutidos para lidar facilmente com verificações de nulo, permitindo que os desenvolvedores gerenciem com segurança os dados de código de barras sem implementar manualmente lógica complexa de validação.

Quais são algumas das melhores práticas para verificação de nulo no IronBarcode?

As melhores práticas incluem verificar valores nulos em BarcodeResults, validar entradas antes do processamento e usar filtros de confiança para garantir resultados confiáveis de leitura de códigos de barras.

O IronBarcode pode filtrar resultados por confiança para evitar saídas nulas?

Sim, o IronBarcode permite filtrar resultados de código de barras por níveis de confiança, o que ajuda a reduzir saídas nulas e garante alta precisão na leitura de códigos de barras.

Existe uma maneira de validar entradas de escrita usando IronBarcode?

O IronBarcode permite a validação de entradas de escrita para garantir que os dados sendo codificados nos códigos de barras estejam corretos e completos, prevenindo problemas durante a geração de código de barras.

O que acontece se um resultado nulo de código de barras não for tratado?

Se um resultado nulo de código de barras não for tratado, ele pode levar a exceções de execução e interromper o fluxo do aplicativo, causando possíveis falhas ou operações incorretas.

How does IronBarcode's reusable validator pattern work?

IronBarcode's reusable validator pattern consolidates null checks, empty checks, value integrity, and expected format validation into a single method, simplifying the validation process before results are used downstream.

What are some constraints that BarcodeWriterEncoding handles during barcode creation?

BarcodeWriterEncoding imposes constraints like string length and character validity based on the barcode type. For example, EAN-8 must have 7 or 8 numeric digits. Correctly formatted input avoids exceptions during encoding.

How does IronBarcode ensure the quality of scanned barcodes?

IronBarcode uses properties such as ConfidenceThreshold in BarcodeReaderOptions to ensure only high-quality barcodes are included in results. This pre-scanning filter means low-quality reads are discarded before further processing.

Curtis Chau
Redator Técnico

Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais bem estruturados e visualmente atraentes.

...
Leia mais

Pronto para começar?

Nuget Downloads 2,422,100Versão:2026.9recém-lançado

Obtenha sua chave de avaliação gratuita de 30 dias instantaneamente.
Não é necessário cartão de crédito nem criação de conta.
Biblioteca NuGet C# para PDF
Instalar com NuGet

Versão: 2026.9

PM > Install-Package BarCode
nuget.org/packages/BarCode/
  1. No Solution Explorer, clique com o botão direito do mouse em Referências e selecione Gerenciar Pacotes NuGet.
  2. Selecione Procurar e pesquise "IronBarCode".
  3. Selecione o pacote e instale.
DLL de PDF em C#
Baixar DLL

Versão: 2026.9

  1. Baixe e descompacte o IronBarCode em um local como ~/Libs dentro do diretório da sua solução.
  2. No Solution Explorer do Visual Studio, clique com o botão direito do mouse em Referências. Selecione Procurar e digite "IronBarCode.dll".

Licenças a partir de US$ 749

Key in blue circle

Obtenha sua chave de avaliação gratuita de 30 dias instantaneamente.

Your trial license will be sent to your email address

Sem limitações. 100% desbloqueado. Sem cartão de crédito.

bullet_checkedNão é necessário cartão de crédito nem criação de conta.Sem limitações. 100% desbloqueado. Sem cartão de crédito.
  • Logo Aetna
  • Logo NASA
  • Logo GE
  • Logo Porsche
  • Logo USDA
  • Logo Qatar
Join Millions of Engineers who’ve tried IronPDF
Agende sua demonstração ao vivo gratuita.
Booking Badge

Aprovado por milhões de engenheiros em todo o mundo.

Logotipos dos clientes da Iron Software
Agende sua consulta sem compromisso.
Preencha o formulário abaixo ou envie um e-mail para sales@ironsoftware.com
Os seus dados serão sempre mantidos em sigilo.
Aprovado por milhões de engenheiros em todo o mundo.
Logotipos dos clientes da Iron Software
Obtenha sua chave de avaliação gratuita de 30 dias instantaneamente.
Não é necessário cartão de crédito nem criação de conta.