PrinterHelper for .NET: A Complete Guide to Installation and Usage
What is PrinterHelper for .NET?
PrinterHelper for .NET is a lightweight library that simplifies common printing tasks in .NET applications (Windows Forms, WPF, and console). It wraps native printing APIs and offers a higher-level, developer-friendly interface for sending documents, images, and raw printer commands.
Supported scenarios
- Print plain text, formatted text, images (PNG/JPEG/BMP), and PDFs (via installed PDF reader or conversion).
- Send raw printer commands (ESC/POS, ZPL) to thermal and label printers.
- Select printers and configure page settings programmatically.
- Handle print previews and print job status callbacks.
Installation
-
NuGet (recommended)
- In Visual Studio, open Package Manager Console and run:
powershell
Install-Package PrinterHelper.Net- Or add the package via the NuGet UI by searching “PrinterHelper.Net”.
-
Manual DLL reference
- Download the library DLL from the project release page.
- Add a reference: Right-click References → Add Reference → Browse → select the DLL.
-
.NET SDK / CLI
bash
dotnet add package PrinterHelper.Net
Basic usage examples
- Initialize and print plain text (synchronous):
csharp
using PrinterHelper; var printer = new Printer(); printer.SelectPrinter(“Microsoft Print to PDF”); printer.PrintText(“Hello from PrinterHelper!”);
- Print an image:
csharp
var printer = new Printer(); printer.SelectPrinter(“HP LaserJet”); printer.PrintImage(@“C:\images\invoice.png”);
- Print with page settings:
csharp
var settings = new PrintSettings { PaperSize = PaperSize.A4, Orientation = Orientation.Portrait, Copies = 2, Margins = new Margins(50,50,50,50) // 0.5 inch }; var printer = new Printer(); printer.SelectPrinter(“Brother”); printer.PrintText(“Report”, settings);
- Send raw ESC/POS bytes to a receipt printer:
csharp
byte[] escPos = new byte[] { 0x1B, 0x40 }; // Initialize printer var rawPrinter = new RawPrinter(); rawPrinter.SelectPrinter(“EPSON_TMT20”); rawPrinter.SendRaw(escPos); rawPrinter.SendRaw(Encoding.ASCII.GetBytes(“Thank you!\n\n\n”)); rawPrinter.Cut();
Asynchronous printing and progress
Use async methods to avoid blocking the UI:
csharp
await printer.PrintTextAsync(“Background print job”); printer.PrintProgress += (s,e) => Console.WriteLine($“Progress: {e.Percent}%”); printer.PrintCompleted += (s,e) => Console.WriteLine(“Print finished”);
Print preview
Show a built-in preview control in WinForms/WPF:
csharp
var preview = new PrintPreviewControl(printer); preview.ShowDialog();
Error handling and troubleshooting
- Printer not found: Ensure the exact printer name matches installed printers. Use Printer.GetInstalledPrinters() to list them.
- Permissions: On restricted environments (services, IIS), run under an account with printer access and set appropriate session 0 handling.
- PDF printing quirks: Printing PDFs relies on a registered handler; for reliable server-side PDF printing, convert PDFs to image pages or use a headless PDF renderer.
- Encoding issues: Match text encoding (UTF-8/ANSI) to printer capabilities; use image rendering for complex scripts.
Deployment considerations
- Include the PrinterHelper DLL with your application or add NuGet package to the project.
- For server-side printing, prefer printers accessible on the server (network/shared), and ensure the application has rights.
- Test on target OS versions; printer drivers and supported features can vary.
Best practices
- Use print previews for user-facing apps to reduce accidental prints.
- For receipts/labels, use raw command mode to leverage printer features and speed.
- Batch jobs: queue multiple documents and run on a background worker to avoid UI freezes.
- Log printer names and error responses for easier troubleshooting.
Example: Small console app that prints a file
csharp
using PrinterHelper; using System.Threading.Tasks; class Program { static async Task Main(string[] args) { var printer = new Printer(); printer.SelectPrinter(“Microsoft Print to PDF”); await printer.PrintFileAsync(@“C:\temp\sample.txt”); Console.WriteLine(“Sent to printer”); } }
Further resources
- Official NuGet page for installation and release notes.
- Library documentation for advanced APIs (callbacks, custom rendering, plugin points).
- Printer driver and manufacturer guides for raw command sets (ESC/POS, ZPL).
Leave a Reply