ISL.NetFramework.QrCode.Driver 2.5.0

ISL.NetFramework.QrCode.Driver

ISL.NetFramework.QrCode.Driver is the single entrypoint package for generating QR codes and barcodes, storing them through the configured ISL file storage (Azure Blob / S3 / MinIO / FTP), and serving them back by id.

• QR codes (via QRCoder) and 1D/2D barcodes (via ZXing.Net)
• Optional logo overlay for SVG output
• Upload to the configured storage profile under a QR_Code prefix
• One injectable service (IQrCodeDriver) and optional REST endpoints

Architecture

Layered by responsibility. The Driver package is the only public entrypoint; it composes the Application, Infrastructure, and core model packages and wires them through dependency injection.

flowchart TB
    subgraph Host["Host application"]
        Caller["Internal caller<br/>(IQrCodeDriver)"]
        HTTP["HTTP client<br/>(REST endpoints)"]
    end

    subgraph Driver["ISL.NetFramework.QrCode.Driver"]
        Endpoints["QrCode endpoints<br/>(minimal API handlers)"]
        DI["AddIslQrCodeDriver /<br/>MapIslQrCodeEndpoints"]
    end

    subgraph Application["ISL.NetFramework.QrCode.Application"]
        Generator["QrCodeGenerator<br/>(IQrCodeDriver)"]
        Validator["QrCodeGenerateRequestValidator<br/>(FluentValidation)"]
    end

    subgraph Infrastructure["ISL.NetFramework.QrCode.Infrastructure"]
        Renderers["IQrCodeRenderer<br/>QRCoder (QR) / ZXing (barcode)"]
        Compositors["ILogoCompositor<br/>SvgLogoCompositor"]
        FileStore["QrCodeFileStore<br/>(write-ahead saga)"]
    end

    subgraph External["Framework services"]
        Storage["IStorageProvider<br/>Azure Blob / S3 / MinIO / FTP"]
        Repo["IRepository&lt;FileUpload&gt; +<br/>ITransactionalUnitOfWork (LinqToDB)"]
    end

    HTTP --> Endpoints
    Endpoints --> Generator
    Caller --> Generator
    Generator --> Validator
    Generator --> Renderers
    Generator --> Compositors
    Generator --> FileStore
    FileStore --> Storage
    FileStore --> Repo

Generate flow (write-ahead saga)

QrCodeFileStore.SaveAsync commits the DB row Pending before the upload, so a crash never leaves an orphan blob with no record. On upload success the row flips to Completed; on failure it flips to Failed and the blob is deleted best-effort.

sequenceDiagram
    participant C as Caller
    participant G as QrCodeGenerator
    participant V as Validator
    participant R as Renderer
    participant S as QrCodeFileStore
    participant DB as FileUpload (DB)
    participant B as Blob storage

    C->>G: GenerateAsync(request)
    G->>V: validate (limits, colors, size)
    V-->>G: ok
    G->>R: Render(payload, style)
    R-->>G: image bytes
    G->>S: SaveAsync(image)
    S->>DB: insert row (Pending)
    S->>B: upload blob
    alt upload ok
        S->>DB: update row (Completed)
        S-->>G: StoredQr(url)
        G-->>C: Result.Success(url)
    else upload fails
        S->>B: delete blob (best-effort)
        S->>DB: update row (Failed)
        S-->>G: throw
        G-->>C: Result.Failure(qr_upload_failed)
    end

Registration

services.AddIslQrCodeDriver(configuration);

The driver persists a FileUpload row per generated code, so it requires the LinqToDB persistence and generic repositories:

services.AddIslLinqToDbPersistence(configuration);
services.AddIslLinqToDbGenericRepositories();

File storage is registered for you by AddIslQrCodeDriver.

Usage

public sealed class TicketService
{
    private readonly IQrCodeDriver _driver;

    public TicketService(IQrCodeDriver driver)
    {
        _driver = driver;
    }

    public async Task<string> CreateTicketQrAsync(string payload, CancellationToken cancellationToken)
    {
        var result = await _driver.GenerateAsync(
            new QrCodeGenerateRequest(payload),
            cancellationToken: cancellationToken);

        return result.IsSuccess
            ? result.Value!.Url
            : throw new InvalidOperationException(result.ErrorMessage);
    }
}

IQrCodeDriver exposes:

• GenerateAsync(QrCodeGenerateRequest, SecurityContext?, CancellationToken) — render, store, return the URL.
• GetAsync(Guid fileId, SecurityContext?, CancellationToken) — resolve a stored code by id.
• DeleteAsync(Guid fileId, SecurityContext?, CancellationToken) — soft-delete a stored code.

All three return Result / Result<T> from ISL.NetFramework.Abstractions.

REST endpoints (optional)

app.MapIslQrCodeEndpoints();

Mounts, under the configured route prefix (default api/v1/qr-codes):

• POST / — generate a code (JSON body; logo supplied as base64), returns 201 Created.
• GET /{fileId:guid} — get a stored code.
• DELETE /{fileId:guid} — delete a stored code.

Endpoints require authentication by default and can be toggled individually via options.

Configuration

Bound from the Framework:QrCode section:

{
  "Framework": {
    "QrCode": {
      "Enabled": true,
      "DefaultStorageProfile": null,
      "PathPrefix": "QR_Code",
      "DefaultFormat": "Png",
      "DefaultErrorCorrection": "Quartile",
      "DefaultSizePixels": 512,
      "PublicUrls": false,
      "PublicBaseUrl": null,
      "ReadUrlLifetimeMinutes": 15,
      "Limits": {
        "MaxPayloadBytes": 4096,
        "MaxMetadataBytes": 8192,
        "MaxLogoBytes": 262144,
        "MinSizePixels": 32,
        "MaxSizePixels": 4096,
        "MaxMarginModules": 64,
        "AllowedLogoMimeTypes": [ "image/png", "image/jpeg" ]
      },
      "Endpoint": {
        "Enabled": true,
        "RoutePrefix": "api/v1/qr-codes",
        "Endpoints": { "Generate": true, "Get": true, "Delete": true }
      },
      "Auth": {
        "RequireAuthentication": true,
        "PolicyName": null,
        "Roles": []
      }
    }
  }
}

Supported symbologies and formats

Raster (PNG) logo overlay and raster barcodes are intentionally deferred; unsupported combinations return a typed failure rather than throwing.