Basic Usage Examples

This guide provides practical examples for the most common barcode generation scenarios using the BarcodeGenerator library.

Simple Barcode Generation

Minimal Example

The simplest way to generate a barcode with default settings:

using SkiaSharp;
using TyKonKet.BarcodeGenerator;

// Generate EAN-8 barcode (default type)
using var barcode = new Barcode();
string result = barcode.Encode("1234567");  // Returns: "12345670" (with check digit)
barcode.Export("simple-barcode.png");

What this does:

Creates a barcode with all default settings
Uses EAN-8 format (default type)
Automatically calculates and adds the check digit
Exports as PNG image

Specific Barcode Type

Generate a specific barcode type:

// EAN-13 barcode
using var ean13 = new Barcode(options => options.Type = BarcodeTypes.Ean13);
string result = ean13.Encode("123456789012");  // Returns: "1234567890128"
ean13.Export("ean13-barcode.png");

Configuration Examples

Basic Configuration

Set the most common options:

using var barcode = new Barcode(options =>
{
    options.Type = BarcodeTypes.Ean13;
    options.Height = 50;        // Bar height in pixels
    options.Scaling = 3;        // Scale factor (3x larger)
    options.RenderText = true;  // Show text below bars
});

string result = barcode.Encode("123456789012");
barcode.Export("configured-barcode.png");

Configuration breakdown:

Setting	Value	Effect
`Type`	`BarcodeTypes.Ean13`	Uses EAN-13 format
`Height`	`50`	Makes bars 50 pixels tall
`Scaling`	`3`	Enlarges entire barcode 3x
`RenderText`	`true`	Shows numbers below bars

Complete Configuration

All available options configured for maximum control:

using var barcode = new Barcode(options =>
{
    // Barcode type and dimensions
    options.Type = BarcodeTypes.Code93;
    options.Height = 60;
    options.Scaling = 4;
    options.Margins = 10;
    
    // Colors
    options.BackgroundColor = SKColors.White;
    options.ForegroundColor = SKColors.Black;
    
    // Text rendering
    options.RenderText = true;
    options.UseTypeface("Arial", SKFontStyle.Normal);
});

string result = barcode.Encode("PRODUCT-001");
barcode.Export("complete-barcode.png");

Advanced Options:

Category	Options	Purpose
Dimensions	Height, Scaling, Margins	Control size and spacing
Colors	Background, Foreground	Visual appearance
Text	RenderText, Typeface	Human readability

Different Barcode Types

EAN-13 (Retail Products)

Best for: International retail products, grocery items

using var ean13 = new Barcode(options =>
{
    options.Type = BarcodeTypes.Ean13;
    options.Height = 50;
    options.Scaling = 2;
});

// 12 digits input, check digit added automatically
string result = ean13.Encode("123456789012");  // Returns: "1234567890128"
ean13.Export("product-{barcode}.png");         // Saves as: product-1234567890128.png

UPC-A (North American Retail)

Best for: US and Canadian retail products

using var upca = new Barcode(options =>
{
    options.Type = BarcodeTypes.Upca;
    options.Height = 45;
    options.Scaling = 2;
});

// 11 digits input, check digit added automatically
string result = upca.Encode("12345678901");  // Returns: "123456789012"
upca.Export("upc-{barcode}.png");

ISBN-13 (Books)

using var isbn = new Barcode(options =>
{
    options.Type = BarcodeTypes.Isbn13;
    options.Height = 40;
    options.Scaling = 2;
    options.UseTypeface("Times New Roman");  // Professional font for books
});

// ISBN without check digit
string result = isbn.Encode("978012345678");  // Returns: "9780123456786"
isbn.Export("book-isbn-{barcode}.png");

EAN-8 (Small Packages)

using var ean8 = new Barcode(options =>
{
    options.Type = BarcodeTypes.Ean8;
    options.Height = 35;    // Smaller height for compact packages
    options.Scaling = 3;    // Higher scaling to maintain readability
});

// 7 digits input, check digit added automatically
string result = ean8.Encode("1234567");  // Returns: "12345670"
ean8.Export("small-package-{barcode}.png");

CODE-93 (Logistics and Inventory)

using var code93 = new Barcode(options =>
{
    options.Type = BarcodeTypes.Code93;
    options.Height = 55;
    options.Scaling = 3;
    options.UseTypeface("Consolas");  // Monospace font for technical use
});

// Alphanumeric input
string result = code93.Encode("ITEM-001");    // Returns: "ITEM-001"
code93.Export("inventory-{barcode}.png");

// Can contain various characters
code93.Encode("PART+123");
code93.Encode("REF/456");
code93.Encode("QTY$789");

Export Examples

Different Image Formats

using var barcode = new Barcode(options => options.Type = BarcodeTypes.Ean13);
string result = barcode.Encode("123456789012");

// PNG (default, best quality)
barcode.Export("barcode.png", SKEncodedImageFormat.Png, 100);

// JPEG (smaller file size)
barcode.Export("barcode.jpg", SKEncodedImageFormat.Jpeg, 90);

// WEBP (modern format)
barcode.Export("barcode.webp", SKEncodedImageFormat.Webp, 85);

Quality Settings

// Maximum quality (larger file)
barcode.Export("high-quality.jpg", SKEncodedImageFormat.Jpeg, 100);

// Balanced quality/size
barcode.Export("medium-quality.jpg", SKEncodedImageFormat.Jpeg, 85);

// Compressed (smaller file)
barcode.Export("compressed.jpg", SKEncodedImageFormat.Jpeg, 60);

File Naming with Keywords

barcode.Encode("123456789012");

// Use all available keywords
barcode.Export("output/{barcode}_q{quality}.{format}", 
    SKEncodedImageFormat.Png, 100);
// Result: output/1234567890128_q100.png

// Custom naming pattern
barcode.Export("products/product_{barcode}_high.{format}", 
    SKEncodedImageFormat.Png, 100);
// Result: products/product_1234567890128_high.png

Stream Export Examples

Memory Stream

using var barcode = new Barcode(options => options.Type = BarcodeTypes.Ean13);
barcode.Encode("123456789012");

using var memoryStream = new MemoryStream();
barcode.Export(memoryStream, SKEncodedImageFormat.Png, 100);

// Get image as byte array
byte[] imageBytes = memoryStream.ToArray();
Console.WriteLine($"Image size: {imageBytes.Length} bytes");

// Save byte array to file
File.WriteAllBytes("from-stream.png", imageBytes);

File Stream

using var fileStream = new FileStream("output.png", FileMode.Create);
barcode.Export(fileStream, SKEncodedImageFormat.Png, 100);
// File is automatically written and closed

HTTP Response Stream (ASP.NET Core)

[HttpGet("barcode/{code}")]
public IActionResult GenerateBarcode(string code)
{
    using var barcode = new Barcode(options =>
    {
        options.Type = BarcodeTypes.Ean13;
        options.Height = 50;
        options.Scaling = 2;
    });
    
    try
    {
        string validatedCode = barcode.Encode(code);
        
        var stream = new MemoryStream();
        barcode.Export(stream, SKEncodedImageFormat.Png, 100);
        stream.Position = 0;
        
        return File(stream, "image/png", $"{validatedCode}.png");
    }
    catch (InvalidOperationException)
    {
        return BadRequest("Barcode configuration error");
    }
    catch (ArgumentNullException)
    {
        return BadRequest("Invalid barcode input");
    }
    catch (FormatException)
    {
        return BadRequest("Invalid barcode format");
    }
    catch (ArgumentOutOfRangeException)
    {
        return BadRequest("Barcode value out of range");
    }
    catch (IOException)
    {
        return StatusCode(500, "Export error");
    }
}

Error Handling Examples

Basic Error Handling

public void GenerateBarcodeWithErrorHandling(string input)
{
    try
    {
        using var barcode = new Barcode(options => options.Type = BarcodeTypes.Ean13);
        string result = barcode.Encode(input);
        barcode.Export($"output/{result}.png");
        Console.WriteLine($"Successfully generated: {result}");
    }
    catch (InvalidOperationException ex)
    {
        Console.WriteLine($"Configuration error: {ex.Message}");
    }
    catch (ArgumentNullException ex)
    {
        Console.WriteLine($"Null input provided: {ex.Message}");
    }
    catch (FormatException ex)
    {
        Console.WriteLine($"Invalid format '{input}': {ex.Message}");
    }
    catch (ArgumentOutOfRangeException ex)
    {
        Console.WriteLine($"Value out of range '{input}': {ex.Message}");
    }
    catch (DirectoryNotFoundException ex)
    {
        Console.WriteLine($"Output directory error: {ex.Message}");
    }
    catch (IOException ex)
    {
        Console.WriteLine($"Export error: {ex.Message}");
    }
}

Validation Before Encoding

public bool TryGenerateBarcode(string input, BarcodeTypes type, out string result)
{
    result = null;
    
    // Pre-validate input
    if (!IsValidInput(input, type))
    {
        return false;
    }
    
    try
    {
        using var barcode = new Barcode(options => options.Type = type);
        result = barcode.Encode(input);
        barcode.Export($"output/{result}.png");
        return true;
    }
    catch
    {
        return false;
    }
}

private bool IsValidInput(string input, BarcodeTypes type)
{
    if (string.IsNullOrEmpty(input)) return false;
    
    return type switch
    {
        BarcodeTypes.Ean13 => input.Length == 12 && input.All(char.IsDigit),
        BarcodeTypes.Upca => input.Length == 11 && input.All(char.IsDigit),
        BarcodeTypes.Isbn13 => input.Length == 12 && input.All(char.IsDigit),
        BarcodeTypes.Ean8 => input.Length == 7 && input.All(char.IsDigit),
        BarcodeTypes.Code93 => IsValidCode93(input),
        _ => false
    };
}

private bool IsValidCode93(string input)
{
    const string validChars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 $%+-./ ";
    return input.All(c => validChars.Contains(c));
}

Batch Processing Examples

Process Multiple Barcodes

public void GenerateMultipleBarcodes()
{
    var productCodes = new[]
    {
        "123456789012",
        "987654321098", 
        "456789012345",
        "789012345678"
    };
    
    using var barcode = new Barcode(options =>
    {
        options.Type = BarcodeTypes.Ean13;
        options.Height = 50;
        options.Scaling = 2;
    });
    
    foreach (string code in productCodes)
    {
        try
        {
            string result = barcode.Encode(code);
            barcode.Export($"products/product_{result}.png");
            Console.WriteLine($"Generated: {result}");
        }
        catch (FormatException ex)
        {
            Console.WriteLine($"Failed to generate barcode for '{code}': {ex.Message}");
        }
        catch (ArgumentOutOfRangeException ex)
        {
            Console.WriteLine($"Value out of range for '{code}': {ex.Message}");
        }
    }
}

Different Types in Batch

public void GenerateMixedBarcodes()
{
    var barcodeData = new[]
    {
        ("123456789012", BarcodeTypes.Ean13, "product"),
        ("12345678901", BarcodeTypes.Upca, "upc"),
        ("978123456789", BarcodeTypes.Isbn13, "book"),
        ("1234567", BarcodeTypes.Ean8, "small"),
        ("ITEM-001", BarcodeTypes.Code93, "inventory")
    };
    
    // Create a cache of Barcode instances by type for performance
    var barcodeCache = new Dictionary<BarcodeTypes, Barcode>();
    
    try
    {
        foreach (var (data, type, category) in barcodeData)
        {
            // Get or create barcode instance for this type
            if (!barcodeCache.TryGetValue(type, out var barcode))
            {
                barcode = new Barcode(options =>
                {
                    options.Type = type;
                    options.Height = 50;
                    options.Scaling = 2;
                });
                barcodeCache[type] = barcode;
            }
            
            try
            {
                string result = barcode.Encode(data);
                barcode.Export($"{category}/{result}.png");
            }
            catch (FormatException ex)
            {
                Console.WriteLine($"Format error processing {data}: {ex.Message}");
            }
            catch (ArgumentOutOfRangeException ex)
            {
                Console.WriteLine($"Range error processing {data}: {ex.Message}");
            }
        }
    }
    finally
    {
        // Dispose all cached instances
        foreach (var barcode in barcodeCache.Values)
        {
            barcode.Dispose();
        }
    }
}

Reusable Configuration

Configuration Helper Methods

public static void ConfigureForPrint(BarcodeOptions options)
{
    options.Height = 80;
    options.Scaling = 4;
    options.Margins = 15;
    options.BackgroundColor = SKColors.White;
    options.ForegroundColor = SKColors.Black;
    options.UseTypeface("Arial", SKFontStyle.Normal);
}

public static void ConfigureForWeb(BarcodeOptions options)
{
    options.Height = 40;
    options.Scaling = 2;
    options.Margins = 5;
    options.BackgroundColor = SKColors.Transparent;
    options.ForegroundColor = SKColors.Black;
    options.UseTypeface("Verdana", SKFontStyle.Normal);
}

// Usage
using var printBarcode = new Barcode(ConfigureForPrint);
using var webBarcode = new Barcode(ConfigureForWeb);

Configuration Classes

public static class BarcodeConfigurations
{
    public static readonly Action<BarcodeOptions> HighQuality = options =>
    {
        options.Height = 100;
        options.Scaling = 6;
        options.Margins = 20;
        options.UseTypeface("Arial", SKFontStyle.Normal);
    };
    
    public static readonly Action<BarcodeOptions> Compact = options =>
    {
        options.Height = 25;
        options.Scaling = 1;
        options.Margins = 2;
        options.RenderText = false;
    };
    
    public static readonly Action<BarcodeOptions> Professional = options =>
    {
        options.Height = 60;
        options.Scaling = 3;
        options.Margins = 10;
        options.UseTypeface("Times New Roman", SKFontStyle.Normal);
        options.ForegroundColor = SKColor.Parse("#2C3E50");
    };
}

// Usage
using var barcode = new Barcode(BarcodeConfigurations.Professional);

Next Steps

Now that you understand the basic usage patterns, explore more advanced topics:

🎨 Styling & Customization:

Customization Examples - Advanced styling and appearance options
Export Formats - Detailed export options and file handling

📋 Type-Specific Documentation:

Supported Types - Comprehensive examples for each barcode type

🔧 Advanced Features:

Custom Fonts - Loading and using custom fonts
Validation - Input validation and error handling

📚 API Reference:

Barcode Class - Complete API documentation
BarcodeOptions - All configuration options

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Basic Usage Examples

Simple Barcode Generation

Minimal Example

Specific Barcode Type

Configuration Examples

Basic Configuration

Complete Configuration

Different Barcode Types

EAN-13 (Retail Products)

UPC-A (North American Retail)

ISBN-13 (Books)

EAN-8 (Small Packages)

CODE-93 (Logistics and Inventory)

Export Examples

Different Image Formats

Quality Settings

File Naming with Keywords

Stream Export Examples

Memory Stream

File Stream

HTTP Response Stream (ASP.NET Core)

Error Handling Examples

Basic Error Handling

Validation Before Encoding

Batch Processing Examples

Process Multiple Barcodes

Different Types in Batch

Reusable Configuration

Configuration Helper Methods

Configuration Classes

Next Steps

FilesExpand file tree

basic-usage.md

Latest commit

History

basic-usage.md

File metadata and controls

Basic Usage Examples

Simple Barcode Generation

Minimal Example

Specific Barcode Type

Configuration Examples

Basic Configuration

Complete Configuration

Different Barcode Types

EAN-13 (Retail Products)

UPC-A (North American Retail)

ISBN-13 (Books)

EAN-8 (Small Packages)

CODE-93 (Logistics and Inventory)

Export Examples

Different Image Formats

Quality Settings

File Naming with Keywords

Stream Export Examples

Memory Stream

File Stream

HTTP Response Stream (ASP.NET Core)

Error Handling Examples

Basic Error Handling

Validation Before Encoding

Batch Processing Examples

Process Multiple Barcodes

Different Types in Batch

Reusable Configuration

Configuration Helper Methods

Configuration Classes

Next Steps