BSynchro.Printout.Public 8.1.1

dotnet add package BSynchro.Printout.Public --version 8.1.1
                    
NuGet\Install-Package BSynchro.Printout.Public -Version 8.1.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="BSynchro.Printout.Public" Version="8.1.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="BSynchro.Printout.Public" Version="8.1.1" />
                    
Directory.Packages.props
<PackageReference Include="BSynchro.Printout.Public" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add BSynchro.Printout.Public --version 8.1.1
                    
#r "nuget: BSynchro.Printout.Public, 8.1.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package BSynchro.Printout.Public@8.1.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=BSynchro.Printout.Public&version=8.1.1
                    
Install as a Cake Addin
#tool nuget:?package=BSynchro.Printout.Public&version=8.1.1
                    
Install as a Cake Tool

BSynchro.Printout.Public

Html-to-pdf printouts for ASP.NET Core (net8.0). A host service references this package and keeps its own Razor templates under wwwroot; the package renders a template with the posted model and returns a pdf.

Two pdf engines:

Engine Endpoint Needs on the server
wkhtmltopdf (default) POST api/Printout/GeneratePrintout nothing (native library embedded, Windows)
Chromium (Playwright, opt-in) POST api/Printout/GeneratePlaywrightPrintout the Playwright driver in the output + Chromium installed once per server

Getting started

using BSynchro.Printout.Public;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddPrintOut();
var app = builder.Build();
app.UsePrintOut();   // CORS (any origin/header/method) + MVC
app.Run();

Templates go under wwwroot; the request's TemplateFolder is an absolute path or a path relative to wwwroot (e.g. printouts\MyDocument). Images, stylesheets and fonts are resolved relative to the template folder.

Endpoints

Method Route Description
POST api/Printout/GeneratePrintout wkhtmltopdf engine, returns application/pdf
POST api/Printout/GeneratePrintoutEncrypted same, JWE-encrypted request body; needs services.AddHttpJoseSecurityEncryption(configuration)
POST api/Printout/GeneratePlaywrightPrintout Chromium engine
GET api/Printout/Health converts a tiny pdf through the wkhtmltopdf queue; 200, or 503 with the queue state after Printout:HealthCheckTimeoutSeconds
GET api/Printout/PlaywrightHealth launches Chromium if needed and renders a tiny pdf; 200, or 503
GET api/Printout/justdoit liveness only, returns hello (does not touch the pdf engines)

Point monitoring / recycle scripts at the health endpoints, not at a liveness endpoint.

Request body

{
  "Title": "My document",                     // document title and file name (Title.pdf)
  "LanguageId": 1,
  "Model": { },                               // anything: the templates read it as Model.Model
  "TemplateFolder": "printouts\\MyDocument",
  "BodyTemplateFileName": "BodyTemplate.cshtml",
  "HeaderTemplateFileName": "HeaderTemplate.cshtml",   // optional
  "FooterTemplateFileName": "FooterTemplate.cshtml",   // optional
  "Options": { "web.enableIntelligentShrinking": "false" },  // optional, raw converter options
  "MarginOptions": {                          // optional, both engines
    "PaperSize": "A4",
    "Orientation": "Portrait",                // Portrait | Landscape
    "TopMargin": "28.0", "BottomMargin": "22.0", "LeftMargin": "4.0", "RightMargin": "5.0"
  },
  "ObjectOptions": {                          // optional, wkhtmltopdf only
    "HeaderSpacing": "10.0", "FooterSpacing": "10.0"
  }
}

Settings

Setting Default Effect
Printout:HealthCheckTimeoutSeconds 90 health endpoints answer 503 when the test pdf is not back in time
Printout:SlowConversionSeconds 60 a printout slower than this (wait + conversion) is logged as a Warning
EnableDefualtFooter false adds "Page [page] of [toPage]" at the bottom right (historical spelling)
AppSettings:DeleteTempFolderWhenDoneWithPrintout true deletes the temporary html files after each printout
Playwright:MaxConcurrentPages 4 Chromium pages converted at the same time
Playwright:ConversionTimeoutSeconds 60 per Chromium conversion
ConverterGlobalOptions / ConverterObjectOptions (DI singletons) spacing 10.0 service-wide wkhtmltopdf options, used when the request has none

Logging

Categories: BSynchro.Printout.Converter (wkhtmltopdf queue), BSynchro.PrintoutsRuntime.PdfConversion.PlaywrightPdfConverter (Chromium), BSynchro.Printout.Public.*Controller (requests, health).

  • wkhtmltopdf: a start line before the native call, an end line with the queue wait and the conversion time, and a Warning every 15 s while a conversion runs past SlowConversionSeconds (with the process CPU and memory).
  • Chromium: the wait for a free page and the render time.
  • A request whose caller disconnected before its turn is skipped and logged.

Keep BSynchro.Printout* at Information, and write it to a non-buffered target so the last line before a crash is kept.

wkhtmltopdf: what to know

All wkhtmltopdf conversions of a process run one at a time on one thread (the library requires it). wkhtmltopdf keeps native memory after large documents; after many large conversions it can stop responding or end the process, and a restart clears it. Monitor api/Printout/Health and recycle on 503; a memory-based recycle limit on the host avoids reaching that state.

Chromium engine (opt-in)

  1. csproj: copy the Playwright driver to the build and publish output:

    <PropertyGroup>
      <PrintoutChromiumEngine>true</PrintoutChromiumEngine>
    </PropertyGroup>
    
  2. Optional, Program.cs: launch Chromium at startup so the first printout does not wait for it: builder.Services.AddPlaywrightWarmUp();

  3. Install Chromium once per server (from the published service folder): .\.playwright\node\win32_x64\node.exe .\.playwright\package\cli.js install chromium, and give the app pool identity read access to the browsers folder (PLAYWRIGHT_BROWSERS_PATH).

  4. Check: GET api/Printout/PlaywrightHealth returns 200.

Without the opt-in, GeneratePlaywrightPrintout fails (500) and PlaywrightHealth returns 503; the wkhtmltopdf endpoints work as usual.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
8.1.1 120 10/26/2026
8.1.0 368 10/13/2026
8.0.1 342 10/21/2025
8.0.0 407 5/29/2025
6.0.4 295 10/16/2025
6.0.3 396 9/8/2023
6.0.2 486 3/10/2023
6.0.1 558 12/23/2022
6.0.0 562 11/30/2022