CaysnPrintServer 1.0.5-g8b39ac119e

CaysnPrintServer

A reliable CAYSN thermal printer server for ASP.NET Core with job queuing, print confirmation, and real-time notifications.

Features

• Job Queue — persistent print job queue backed by Entity Framework Core with automatic retry and exponential backoff
• Print Confirmation — two-phase protocol (passive listen + limited active polling) confirms physical print completion via CAYSN auto-reply
• SignalR Hub — real-time job status notifications pushed to connected clients
• REST API — endpoints for submitting jobs (template or raw ESC/POS), querying status, and health checks
• Templates — register named ESC/POS templates with placeholder substitution; render at print time
• Health Monitoring — background service that periodically checks printer reachability and exposes per-printer health status
• Webhooks — optional global webhook URL called on job completion/failure

Quick Start

1. Implement the abstractions

DbContext — your EF Core context must implement ICaysnPrintDbContext:

public class AppDbContext : DbContext, ICaysnPrintDbContext
{
    public DbSet<CaysnPrintJob> CaysnPrintJobs => Set<CaysnPrintJob>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.ApplyCaysnPrintJobConfiguration();

        // Optional: add FK to your own Printer entity
        modelBuilder.Entity<CaysnPrintJob>()
            .HasOne<Printer>()
            .WithMany()
            .HasForeignKey(e => e.PrinterId)
            .OnDelete(DeleteBehavior.Restrict);
    }
}

Printer provider — implement IPrinterProvider to supply printer connection details:

public class MyPrinterProvider : IPrinterProvider
{
    public Task<ICaysnPrinter?> GetPrinterAsync(int printerId, CancellationToken ct = default)
    {
        // Return your printer entity adapted to ICaysnPrinter
    }

    public Task<IReadOnlyList<ICaysnPrinter>> GetActivePrintersAsync(CancellationToken ct = default)
    {
        // Return all enabled printers
    }
}

2. Register services

builder.Services.AddCaysnPrintService<AppDbContext, MyPrinterProvider>(options =>
{
    options.MaxConcurrentJobs = 5;
    options.PrintConfirmationTimeoutMs = 15000;
    options.ApiPrefix = "/api/print";
    options.HubPath = "/hubs/print";

    // SQL Server uses local time; PostgreSQL uses UTC (default)
    options.UseUtcTimestamps = false; // set to false for SQL Server

    // Register ESC/POS templates
    options.RegisterTemplate("receipt", (printer, data) =>
    {
        // Build ESC/POS byte array using ESCPOS_NET
    });
});

3. Map endpoints

var app = builder.Build();

app.UseCaysnPrintService();       // Adds middleware
app.MapCaysnPrintService();       // Maps REST + SignalR endpoints

Requirements

• .NET 10 / ASP.NET Core
• Entity Framework Core (any relational provider)
• CAYSN thermal printer accessible on TCP port 9100