Using IronPrint with AI Coding Assistants
IronPrint is Iron Software's printing library for .NET. It sends PDF files and images from C# code to a printer, either silently or through the system print dialog, on Windows, macOS, iOS, and Android.
Printing is the last step of many document features, and a difficult step to test, because its output leaves the machine. Without IronPrint's documentation, an assistant cannot tell which members exist. Provide the documentation before the first request.
Every assistant needs the same four steps. Add the package, read the key from the environment, give the assistant IronPrint's machine-readable documentation, and inspect what each job contains before closing the task. The same steps cover silent printing, choosing a printer by name, print settings, and dialog printing.
How to Use IronPrint with an AI Coding Assistant
- Download the C# printing library from NuGet
- Target an OS-specific framework such as
net9.0-windows - Assign
IronPrint.License.LicenseKeyfromIRONPRINT_LICENSE_KEYbefore the first job - Give the assistant IronPrint's llms.txt index before any code is written
- Save the IronPrint rules in the file your assistant loads each session
- Check every printer name against
Printer.GetPrinterNamesand confirm what each job sends
Can't My AI Assistant Handle Printing on Its Own?
The silent printing guide describes the System.Drawing.Printing route as a PrintDocument with a page event handler for every document type and no built-in PDF rendering.
IronPrint's API centers on two classes, Printer and PrintSettings, and Step 3 lists the machine-readable documentation that describes them.
Three points apply before an assistant writes the first print call.
- Improvised print code costs tokens: each attempt to rebuild a missing setting from raw
System.Drawing.Printingcalls spends tokens, and that code throws a TypeInitializationException on macOS. - The package name matters: the NuGet package and the namespace are both
IronPrint. Slopsquatting is the registration of package names that language models produce for nonexistent packages, so the prompt should name the package exactly. - Licensing has no recurring fee: IronPrint licenses are perpetual. Each tier on the licensing page sets its own developer, location, and project allowance.
Step 1: Install IronPrint
Ask the assistant to add the package and name the version it resolved.
Add IronPrint version 2026.10.1 from NuGet to this project and restore packages.
Then tell me which IronPrint version the restore resolved.The .NET CLI command pins the same release.
dotnet add package IronPrint --version 2026.10.1The target framework determines which print path the package uses. A net9.0-windows build loads IronPrint's WPF printing path, and a plain net9.0 build on Windows loads a path built on System.Drawing.Printing. The two paths report different tray names for the same printer. For Adobe PDF, the WPF path returned AutoSelect, while the plain build returned Automatically Select and OnlyOne. macOS requires the net9.0-macos or net9.0-maccatalyst target with the matching workload, and Linux is not a supported print platform.
Step 2: Apply Your License Key
Without a key, a program can still list printers and their trays, but PrintAsync throws IronSoftware.Exceptions.LicensingException with the message Production License Required before a job is created. Print throws the same exception wrapped in System.AggregateException. With an invalid key, the message is License Key Not Recognized instead. An unlicensed program therefore produces no output at all, watermarked or otherwise. The form below issues a free trial key.
Start using IronPrint in your project today with a free trial.
Set the key once when the application starts, ahead of the first IronPrint call. The key comes from an environment variable, so no commit contains it.
IronPrint.License.LicenseKey = Environment.GetEnvironmentVariable("IRONPRINT_LICENSE_KEY");Once a valid key is assigned, IronPrint.License.IsLicensed returns true. IronPrint.License.IsValidLicense tests any key string. The library never reads IRONPRINT_LICENSE_KEY on its own, and in this article's probe, setting the variable without the assignment left IsLicensed false.
Step 3: Point Your Assistant at IronPrint's LLM Documentation
- llms.txt indexes 43 pages, one line each. Include it in every new session.
- llms-full.txt holds an abstract of each of the 33 documentation pages in one file.
- llms-full-catalog.txt is the index with the blog articles included.
- The object reference gives the signature of every member.
- Tools that read skill files can load skill.md. Its sections cover installation, licensing, printing recipes, platform deployment, and fixes for known failures.
- The AI Product Fact Sheet lists the supported platforms and the main use cases.
If a task relies on a specific guide, direct the assistant to that page.
Send the index with an instruction to stay inside it.
Read https://ironsoftware.com/print/csharp/llms.txt first, before writing any IronPrint code.
Work only from what those pages document.
IronPrint's API is small, and it fits together like this:
- Printer is static, with Print, PrintAsync, ShowPrintDialog, GetPrinterNames, and GetPrinterTrays.
- PrintSettings holds the printer name, PaperSize, PaperOrientation, PaperMargins, Dpi, and copies.
- It also has the grayscale switch.
- There's no document object to build. You pass a file path or the file's bytes.
Look up any member those pages don't show.
The API reference is https://ironsoftware.com/print/csharp/object-reference/api/.
Compile once to confirm the call exists.
If it's still doubtful, tell me instead of guessing.
Then check this project's IronPrint calls against the docs and list any they don't cover.The line about doubtful members lets the assistant report a gap instead of inventing a member.
Step 4: Add IronPrint Context to Your Project
Chat instructions end with the session, so the IronPrint rules go in a project file that the tool reads each time. Claude Code loads CLAUDE.md, ChatGPT Codex loads AGENTS.md, and the GitHub Copilot file is .github/copilot-instructions.md. Cursor loads .mdc rules from .cursor/rules/ as well as AGENTS.md, and Google Antigravity loads AGENTS.md or GEMINI.md. The same text works in each file, with MDC frontmatter added for a Cursor rule. Start from this block.
All printing in this project goes through IronPrint.
`IronPrint` is the name of both the NuGet package and the namespace.
Follow these rules in all printing code:
- Read the documentation index first at https://ironsoftware.com/print/csharp/llms.txt.
- Tools that accept skill files load https://ironsoftware.com/print/csharp/skill.md.
- Target an OS framework such as `net9.0-windows`, not plain `net9.0`.
- Set `IronPrint.License.LicenseKey` from IRONPRINT_LICENSE_KEY at startup.
- The key never goes to output, logs, or source control.
- Take printer names from `Printer.GetPrinterNames` and match them exactly.
- Refuse any other name. IronPrint sends an unknown name's job to the default printer.
- Use `Printer.PrintAsync` in UI code. `Printer.Print` blocks the thread that calls it.
- Print PDF, PNG, JPG, BMP, or TIFF. GIF and HTML files throw an unsupported file type error.
- Leave `PaperOrientation` on `Automatic` for mixed pages.
- `Portrait` shrinks a landscape page onto a portrait sheet.
- Read tray names in the build that prints. They differ between framework targets.
- Do not add a second printing library. If IronPrint cannot do something, say so.The skill file's single-file example still pins IronPrint 2026.8.1, two releases older than the 2026.10.1 package tested here.
Step 5: One-Shot Setup Prompt
This prompt combines Steps 1 to 4 into one message, sent when a project or session begins.
Get this project ready for printing with IronPrint, under these rules:
- Reference the IronPrint NuGet package at version 2026.10.1.
- Target net9.0-windows or another OS-specific framework, not plain net9.0.
- Assign IronPrint.License.LicenseKey from the IRONPRINT_LICENSE_KEY environment variable.
- Do that at startup, before any other IronPrint call.
- Keep the key out of the console, the logs, and anything committed.
- Read https://ironsoftware.com/print/csharp/llms.txt before coding, and stay within it.
- For members it doesn't cover, search https://ironsoftware.com/print/csharp/object-reference/api/.
- Build before you rely on a member you found there.
- Where the tool takes skill files, load https://ironsoftware.com/print/csharp/skill.md.
- Trust the compiler over the skill file when they disagree.
- Only pass a printer name that Printer.GetPrinterNames returned.
Save these rules in the instructions file that later sessions read.
Then name the file you wrote, and any other change you made.Step 6: Prompt Patterns That Produce Working Code
Say where the printer name comes from, which file type prints, and every print setting.
Vague Print the invoice with IronPrint.
Better Take the printer name from configuration, confirm it appears in
Printer.GetPrinterNames, and print invoice.pdf withPrintSettingsset to A4, automatic orientation, grayscale, and two copies.
Name the IronPrint release and the target framework the code is for.
Better Use IronPrint 2026.10.1 on net9.0-windows, and assign the key from IRONPRINT_LICENSE_KEY before the first job.
Ask for whole files. A fragment can leave out the using IronPrint; directive and the line that assigns the key.
Better Return all of Program.cs with every using directive and the license assignment in it, so it builds without edits.
Step 7: Verify What You Get Back
Probes with 2026.10.1 measured the behavior behind each mistake below.
- Unchecked printer names: a name that matches no installed printer raises no error. In our test,
PrintAsyncreturned after 7.9 seconds and the job went to the default printer, Microsoft Print to PDF. Accept only names thatPrinter.GetPrinterNamesreturned. Printon a UI thread: the synchronous call blocks the thread that calls it, which freezes WPF and WinForms interfaces, as the hang troubleshooting page explains. UsePrintAsync.- A test printer that prompts: two jobs sent to Microsoft Print to PDF completed only after a person typed a file name. An unattended test needs a printer that completes on its own, or the capture method in the next section.
ShowPrintDialogon a plain target: the troubleshooting page says the call can raise an AggregateException on a plain .NET target. On Windows, a plainnet9.0build did not throw. The call opened a real print dialog and returned only when the dialog closed, after 10.1 seconds. Keep dialog calls out of unattended code.
Let the Agent Verify Its Own Work
Ask the assistant to run these checks and report the evidence.
Rebuild in Release and run the app again.
If it has a capture or dry-run mode, use that and send nothing to a real printer.
When it finishes, give me proof:
- List every IronPrint type and member in the code, each with the docs page that covers it.
- Give the value of IronPrint.License.IsLicensed.
- Show where the printer name is checked against Printer.GetPrinterNames.
- For each document, give the printer, the settings sent, and the result.
Say whether the settings each job carried match the settings the code asked for.Silent print jobs with IronPrint
On Windows, IronPrint 2026.10.1 passes each job to WPF's print dialog class without showing it, with a print ticket that holds the settings. A test patch intercepted that call and saved each job as an XPS file, so the figures in this section were measured without paper.
- Each PDF page is rendered as an image at the
Dpisetting. An A4 page became a 1240 by 1753 pixel image at 150 DPI in the run below, and a 2479 by 3508 pixel image at 300 DPI in our probe. PaperSize.A4produced 210 by 297 mm pages, andPaperSize.Letterproduced 215.9 by 279.4 mm pages.- With
PaperOrientation.Automatic, a landscape page printed as a landscape page. WithPortrait, the same page was shrunk to fit a portrait sheet and filled only its upper part. - A color PDF page arrived as a gray image when
Grayscalewas on. Red text in a PNG stayed red, and only the print ticket requested monochrome output for it. NumberOfCopiesset the ticket's copy count, and the job still held one set of pages.
The print settings guide says the printer can limit the DPI and that some platforms ignore the copy count, so both values are requests to the driver.
File formats with IronPrint
In 2026.10.1, PDF, PNG, JPG, BMP, and TIFF files print. GIF and HTML files throw System.IO.InvalidDataException with the message Unsupported file type before a job is created, although the silent printing guide lists both formats. The skill file lists the five formats that work. Render HTML to PDF first, for example with IronPDF.
An image prints as a single page, scaled to the page width. A 1200 by 800 pixel PNG printed on a landscape A4 page with Automatic orientation, and on the upper part of a portrait page with Portrait.
A Result You Can Reproduce
The test is a single prompt, and all of the code comes from the assistant. Create an empty folder, open a new session in it, paste the prompt, and check the result against the list under What passes.
IRONPRINT_LICENSE_KEY, and the name of an installed printer in PRINTER_NAME. The prompt captures every job to an XPS file, so that printer receives nothing.The prompt
Since the app writes its own test set, the six files from the test run are joined below in print order. Its four PDFs are unchanged, and the PNG and GIF each appear on a page of their own pixel size.
Build a .NET 9 Windows console app that silently prints a batch of documents with IronPrint.
Start in an empty directory and keep deliverables there.
If it holds a project or source files, tell me and stop.
Work alone and note each choice you make.
Work in this order:
1. Pin IronPrint at 2026.10.1 from NuGet and target net9.0-windows with WPF on, for step 4.
2. Read https://ironsoftware.com/print/csharp/llms.txt, mainly its silent printing guide.
3. Follow these code rules:
- Call only IronPrint members that the linked pages document.
- At startup, assign IRONPRINT_LICENSE_KEY to IronPrint.License.LicenseKey. You never need the key.
- Never show the key, list environment variables, or write the key to any file.
- When IronPrint.License.IsLicensed is false, report it and stop.
- Check PRINTER_NAME against Printer.GetPrinterNames before the first job.
- If the list lacks it, stop with a clear message and print nothing.
- Pass IronPrint only printer names from that list.
- Record its trays from Printer.GetPrinterTrays.
4. Send no job to a real print queue. Capture each one to XPS instead:
- IronPrint hands each Windows job to WPF's PrintDialog.PrintDocument.
- Patch it with Lib.Harmony 2.3.6 so your code runs instead.
- Save the paginator and PrintTicket to capture/<name of the file being printed>.xps.
- Note the queue and ticket settings.
- Before the first job, prove the patch with a null paginator that sends nothing.
- That self-test writes no file. Stop if it fails.
- Never clear capture/ at startup.
5. Generate testset/ with your own code and no added package:
- invoice-01.pdf and invoice-02.pdf, one A4 portrait page each.
- report-03.pdf, three A4 portrait pages, and chart-04.pdf, one A4 landscape page.
- label-05.png, 1200 by 800 pixels, and cover-06.gif, 600 by 400 pixels.
- Each page shows its file name and page number in large text.
6. Print them in that order with one PrintSettings object:
- A4, automatic orientation, one copy, grayscale and 150 DPI.
- Send each job with Printer.PrintAsync and time it.
- Record a failed job and move on.
7. Run a Release build with the given PRINTER_NAME.
8. Rerun with PRINTER_NAME set to No Such Printer 12345, then set it back.
9. That rerun must stop before any job and leave capture/ unchanged.
10. Write runrecord.md from measured values, one row per test file, with these columns:
- File, source pages counted from the file, and elapsed milliseconds.
- Result, either captured or the exception type and message.
- XPS pages read back from the file, each with width and height in millimeters and orientation.
- The ticket's queue, copy count, page size, orientation, color and resolution.
11. Below the table, give these values:
- IsLicensed, the self-test result and the printer's trays.
- Where the code stops if IsLicensed is false, without touching the key.
- What the No Such Printer 12345 run printed, and whether capture/ changed.
12. Tell me the build result, jobs captured out of six, cover-06.gif's outcome and your assumptions.Output
The run's unedited run record gives the measured values for each of the six files.
Every page that the capture wrote is in the PDF below, in print order.
Batch output as IronPrint built the jobs, captured to XPS files in place of a printer and converted to PDF page for page without edits.
- The net9.0-windows Release build reported 0 warnings and 0 errors.
- The patch self-test passed with a null paginator and wrote no file.
- Five of the six jobs were captured, with 7 pages in total.
- The three portrait PDFs became 210 by 297 mm pages, one for each source page.
- The landscape PDF and the PNG became 297 by 210 mm landscape pages.
- Every ticket specified A4 paper, one copy, monochrome output, and 150 by 150 DPI.
- The GIF was recorded as a failure with an unsupported file type error.
- The run with No Such Printer 12345 stopped before any job and left the capture folder unchanged.
- An independent reading of the XPS files matched every figure in the run record.
- A fresh start of the acceptance build produced the same five captures.
- The key scan found no copy of the license key in the project folder.
- The install prompt kept the 2026.10.1 pin.
- The documentation prompt changed no code.
- Its answer reported that the silent printing guide and the skill file disagree on GIF and HTML.
- A new CLAUDE.md received the setup prompt's rules and the measured behaviors.
- The self-check confirmed that all five captured jobs had the requested settings.
- Some steps ran differently from the page. The acceptance prompt ran first, followed by the prompts from Steps 1, 3, 5, and 7 in the same session. The app matched PRINTER_NAME without regard to case and passed on the exact name from the printer list.
What passes
- The Release build succeeds with no manual edits to the code.
- The app stops before any job when
IsLicensedis false or whenPRINTER_NAMEis not inPrinter.GetPrinterNames. - Every printable file has an XPS capture whose pages, page sizes, and ticket values match runrecord.md when you read the XPS files yourself.
- The GIF is recorded as a failure, and the batch continues.
- The license key is absent from every project file.
The run record
- All runs used one Windows 11 x64 desktop with a Core i9-14900KF and 64 GB of memory.
- No guide sent a job to a physical printer.
- This guide's project targets
net9.0-windowsand pinsIronPrint2026.10.1, with Lib.Harmony 2.3.6 for its capture mode. - A guide's duration is the sum of the logged times for the prompts on its page, and this guide's row counts only the acceptance prompt.
- Last tested October 15, 2026, for this guide, Claude Code, ChatGPT Codex, GitHub Copilot (prompts 1 and 2 only) and Google Antigravity, and October 16, 2026, for Cursor.
| Guide | Assistant and version | Model | Duration (minutes) |
|---|---|---|---|
| This guide | Claude Code 2.1.277, one session, permission prompts off | Claude Opus 5 | 23.7 |
| Claude Code | Claude Code 2.1.277, opusplan alias, prompt 3 in plan mode | Claude Sonnet 5, with Claude Opus 5 planning prompt 3 | 16.4 |
| ChatGPT Codex | Codex CLI 0.160.0, one sitting | GPT-6 Luna | 17.9 |
| GitHub Copilot | Copilot CLI 1.0.95, stopped in prompt 2 by the monthly quota | GPT-6 Luna, picked by Auto | 1.5, prompts 1 and 2 only |
| Cursor | Cursor 3.23.23 desktop app, prompt 3 in Plan Mode | Grok 4.7 | 102.8 |
| Google Antigravity | Antigravity CLI 1.3.5, which updated itself to 1.3.6 during prompt 1, prompts 1 and 5 sent with /plan, permission prompts skipped | Gemini 3.8 Flash (High) | 61.9 |
Agent-Specific Guides
Each tool guide builds one printing task with these steps.
- Use IronPrint with Claude Code for routing each laboratory document type to a named printer and refusing names the machine does not have
- Use IronPrint with ChatGPT Codex for a nightly warehouse job that prints picking lists with a copy count per order
- Use IronPrint with GitHub Copilot for a depot service that prints filled PDF handover forms, flattened before printing
- Use IronPrint with Cursor for migrating packing-slip and label printing from
System.Drawing.Printingto IronPrint print settings - Use IronPrint with Google Antigravity for a hotel front-desk web app that prints a registration card from a controller
Troubleshooting
- Print() Method Hangs in WPF and WinForms for an interface that stops responding during a synchronous print
- ShowPrintDialog Behavior on Unsupported Target Frameworks for dialog calls on a plain target framework
- Per-Page Orientation Lost When Printing Mixed PDFs when a PDF with portrait and landscape pages prints in one orientation
Questions?
If you have any questions, reach out to support@ironsoftware.com
Curtis Chau holds a Bachelor’s degree in Computer Science (Carleton University) and specializes in front-end development with expertise in Node.js, TypeScript, JavaScript, and React. Passionate about crafting intuitive and aesthetically pleasing user interfaces, Curtis enjoys working with modern frameworks and creating well-structured, visually appealing manuals.
