PrintingTools.Windows 0.1.0-alpha.1

PrintingTools

Cross-platform .NET 10 printing toolkit for applications that need consistent print dialogs, previews, pagination, and job submission across Windows, macOS, and Linux.

NuGet Packages

Primary Packages

Package	NuGet	Description
PrintingTools		Avalonia bootstrapper that wires the platform adapter at startup and exposes UsePrintingTools helpers.
PrintingTools.Core		Cross-platform contracts, pagination/rendering pipeline, diagnostics, and option models.
PrintingTools.UI		Reusable Avalonia dialogs and preview UI for page setup and print preview scenarios.
PrintingTools.Windows		Windows adapter with Win32 queue discovery, capability inspection, and XPS/PDF rendering flows.
PrintingTools.MacOS		macOS adapter with AppKit integration, Quartz PDF output, and a universal native preview bridge.
PrintingTools.Linux		Linux CUPS/GTK adapter with portal-aware dialog support and managed PDF submission.

Key Features

• Unified IPrintManager API for printer discovery, session creation, preview generation, and print submission.
• Platform adapters for Win32/XPS, macOS AppKit, and Linux CUPS/GTK with managed fallbacks for headless and CI runs.
• Built-in pagination, layout modes (standard, N-up, booklet, poster), vector/PDF export via Skia, and diagnostics hooks.
• Optional Avalonia UI components for page setup, preview windows, and macOS native preview hosting.
• Cross-platform harnesses and samples that validate output, metrics, and environment-specific behavior in CI.

Package Selection

Architecture Overview

The adapters register through PrintingToolsOptions.AdapterFactory. Configure PrintServiceRegistry once during startup, or call AppBuilder.UsePrintingTools(...) in Avalonia, and then resolve the active IPrintManager through PrintServiceRegistry.EnsureManager().

Repository Layout

Getting Started

Prerequisites

• .NET SDK 10.0.100-rc.2 with prerelease support enabled.
• Windows: Win32 spooler available and XPS support enabled.
• macOS: macOS 14+ with Xcode command line tools for building the native preview bridge.
• Linux: CUPS 2.3+, cups-client (lp, lpoptions), and GTK 3/4 libraries for native dialog integration.

Install Packages

For a typical Avalonia app:

dotnet add package PrintingTools
dotnet add package PrintingTools.UI

For direct pipeline usage without the packaged UI:

dotnet add package PrintingTools.Core
dotnet add package PrintingTools.Windows

Swap the platform package as needed for macOS or Linux.

Restore and Build

git clone https://github.com/wieslawsoltes/PrintingTools.git
cd PrintingTools
dotnet restore PrintingTool.sln
dotnet build PrintingTool.sln -c Release

Configure Printing in Your App

using PrintingTools.Core;

var options = new PrintingToolsOptions
{
    DiagnosticSink = evt => Console.WriteLine($"[{evt.Category}] {evt.Message}")
};

PrintServiceRegistry.Configure(options);
var manager = PrintServiceRegistry.EnsureManager();

Avalonia Applications

using Avalonia;
using PrintingTools;
using PrintingTools.Core;

AppBuilder.Configure<App>()
    .UsePlatformDetect()
    .UsePrintingTools(options =>
    {
        options.EnablePreview = true;
        options.DefaultTicket = PrintTicketModel.CreateDefault();
    })
    .StartWithClassicDesktopLifetime(args);

Request a Preview or Print Session

var document = PrintDocument.FromVisual(myVisual);
var request = new PrintRequest(document)
{
    Options = new PrintOptions { ShowPrintDialog = true },
    Ticket = PrintTicketModel.CreateDefault(),
    Description = "Quarterly report"
};

var session = await manager.RequestSessionAsync(request);
var preview = await manager.CreatePreviewAsync(session);

await manager.PrintAsync(session);

CreatePreviewAsync(...) returns a PrintPreviewModel that you can render in PrintingTools.UI.Controls.PrintPreviewWindow or a platform-specific preview host.

Samples and Harnesses

Documentation

• Documentation site: wieslawsoltes.github.io/PrintingTools
• API reference: docs/printing-api-reference.md
• Migration guide: docs/printing-migration-guide.md
• Platform notes: Windows, macOS, Linux
• Platform support matrix: docs/platform-support-matrix.md
• Sample walkthroughs: docs/printing-sample-walkthroughs.md
• Architecture and planning notes: phase2-architecture, feature-parity-matrix, wpf-printing-parity-plan

Build docs locally:

./build-docs.sh
./serve-docs.sh

PowerShell equivalents are available as build-docs.ps1, check-docs.ps1, and serve-docs.ps1.

Release and CI

• ci.yml runs cross-platform restore/build/test, executes the Windows/macOS/Linux harnesses, and validates that all NuGet packages can be packed.
• docs.yml builds the Lunet site and publishes it to GitHub Pages on pushes to the primary branch.
• release.yml runs on tags like v0.2.0, packs all six publishable libraries, verifies the macOS native bridge is present in the package, publishes to NuGet, and creates a GitHub release.
• Configure NUGET_API_KEY in repository secrets before using the release workflow for publishing.

License

Distributed under the terms of the MIT License.