Introduction of `QRCodeImageBuilder` and Deprecation of `QrCode` class

[guitarrapc]

Summary

Starting 0.9.0, We've introduced a new high-level API QRCodeImageBuilder for easier QR code generation, and marked the old QrCode class as obsolete. QrCode will be removed on 1.0.0.

New API: QRCodeImageBuilder

The QRCodeImageBuilder provides two ways to generate QR codes:

1. Static Methods (Simple & Quick)

For basic use cases, use static methods:

// Generate PNG with default settings
var pngBytes = QRCodeImageBuilder.GetPngBytes("https://example.com");
File.WriteAllBytes("qr.png", pngBytes);

// Generate with custom format
var jpegBytes = QRCodeImageBuilder.GetImageBytes(
    "https://example.com", 
    SKEncodedImageFormat.Jpeg, 
    ECCLevel.H, 
    size: 1024, 
    quality: 90);

// Save directly to stream
using var stream = File.OpenWrite("qr.png");
QRCodeImageBuilder.SavePng("https://example.com", stream);

2. Fluent API (Advanced Customization)

For advanced customization, use the builder pattern:

var qrCode = new QRCodeImageBuilder("https://example.com")
    .WithSize(1024, 1024)
    .WithErrorCorrection(ECCLevel.H)
    .WithColors(SKColors.Navy, SKColors.LightYellow)
    .WithModuleShape(CircleModuleShape.Default, 0.95f)
    .WithGradient(new GradientOptions(
        new[] { SKColors.Blue, SKColors.Purple },
        GradientDirection.TopLeftToBottomRight))
    .WithIcon(new IconData 
    { 
        Icon = logoBitmap, 
        IconSizePercent = 15 
    })
    .ToByteArray();

File.WriteAllBytes("qr.png", qrCode);

Deprecated: QrCode class

The old QrCode class is now marked as obsolete. Please migrate to one of the following APIs:

Old API	New API	Use Case
QrCode.Encode()	QRCodeImageBuilder.GetPngBytes()	Simple PNG generation
QrCode.Encode()	new QRCodeImageBuilder().ToByteArray()	Custom configuration
QrCode.Encode()	QRCodeGenerator + QRCodeRenderer	Low-level control

Migration example:

// Before (obsolete)
var qrCode = new QrCode(content, new Vector2Slim(512, 512), SKEncodedImageFormat.Png);
var bytes = qrCode.Encode();

// After (recommended)
var bytes = QRCodeImageBuilder.GetPngBytes(content, size: 512);

// Or with builder pattern
var bytes = new QRCodeImageBuilder(content)
    .WithSize(512, 512)
    .WithFormat(SKEncodedImageFormat.Png)
    .ToByteArray();

Benefits

• Simpler API: Static methods for common use cases
• Better discoverability: IntelliSense-friendly fluent API
• More flexible: Easy to customize colors, shapes, gradients, and icons
• Performance: Support for IBufferWriter<byte> for zero-allocation scenarios
• Type-safe: Compile-time validation of parameters

Low-Level APIs (Still Available)

For maximum control, you can still use the low-level APIs:

// Generate QR data
var qrData = QRCodeGenerator.CreateQrCode("content", ECCLevel.H);

// Render manually
var info = new SKImageInfo(512, 512);
using var surface = SKSurface.Create(info);
var canvas = surface.Canvas;

QRCodeRenderer.Render(canvas, SKRect.Create(0, 0, 512, 512), qrData);

// Or use extension method
canvas.Render(qrData, 512, 512);

Documentation

For more examples, see the samples/ConsoleApp which demonstrates:

• Pattern 1-12: Various usage patterns from simple to advanced
• Pattern 13-14: Instagram-style profile QR codes with gradients and custom frames

Breaking Changes

The old QrCode class still works but is marked as obsolete. You'll see compiler warnings encouraging migration to the new API. QrCode class will be delete on v1.0 release.

Feedback

Please try the new API and share your feedback!

Effective

Since 0.9.0