CaysnPrintServer 1.1.0-gd40aadc4f2

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