Usando IronPrint com Assistentes de Codificação de IA

Curtis Chau
Curtis Chau
Atualizado: 26 de outubro de 2026

IronPrint é a biblioteca de impressão da Iron Software para .NET. Ele envia arquivos PDF e imagens do código C# para uma impressora, seja silenciosamente ou através da caixa de diálogo de impressão do sistema, no Windows, macOS, iOS e Android.

A impressão é o último passo de muitos recursos de documentos e um passo difícil de testar, pois sua saída sai da máquina. Sem a documentação do IronPrint, um assistente não pode dizer quais membros existem. Forneça a documentação antes do primeiro pedido.

Todo assistente precisa dos mesmos quatro passos. Adicione o pacote, leia a chave do ambiente, forneça ao assistente a documentação legível por máquina do IronPrint e inspecione o conteúdo de cada trabalho antes de encerrar a tarefa. Os mesmos passos cobrem impressão silenciosa, escolher uma impressora pelo nome, configurações de impressão e impressão com diálogo.

Logo do assistente de codificação de IA Claude CodeLogo do assistente de codificação de IA ChatGPT CodexLogotipo do assistente de codificação de IA GitHub CopilotLogotipo do editor de código da IA CursorLogotipo do agente de codificação de IA Google Antigravity

Meu Assistente de IA Não Pode Lidar com a Impressão Sozinho?

O guia de impressão silenciosa descreve a rota System.Drawing.Printing como um PrintDocument com um manipulador de eventos de página para cada tipo de documento e sem renderização de PDF embutida.

A API do IronPrint gira em torno de duas classes, Printer e PrintSettings, e o Passo 3 lista a documentação legível por máquina que as descreve.

Três pontos se aplicam antes de um assistente escrever a primeira chamada de impressão.

  • Código de impressão improvisado custa tokens: cada tentativa de reconstruir uma configuração ausente de chamadas System.Drawing.Printing brutas gasta tokens, e esse código lança uma TypeInitializationException no macOS.
  • O nome do pacote importa: o pacote NuGet e o namespace são ambos IronPrint. Slopsquatting é o registro de nomes de pacotes que modelos de linguagem produzem para pacotes inexistentes, então o prompt deve nomear o pacote exatamente.
  • Licenciamento não tem taxa recorrente: as licenças do IronPrint são perpétuas. Cada nível na página de licenciamento define sua própria permissão para desenvolvedores, local e projeto.

Passo 1: Instale o IronPrint

Peça ao assistente para adicionar o pacote e nomear a versão que ele resolveu.

Add IronPrint version 2026.10.1 from NuGet to this project and restore packages.
Then tell me which IronPrint version the restore resolved.
Text

O comando .NET CLI fixa a mesma versão.

dotnet add package IronPrint --version 2026.10.1
SHELL

O framework de destino determina qual caminho de impressão o pacote usa. Uma construção net9.0-windows carrega o caminho de impressão WPF do IronPrint, e uma construção net9.0 simples no Windows carrega um caminho construído em System.Drawing.Printing. Os dois caminhos relatam nomes de bandeja diferentes para a mesma impressora. Para Adobe PDF, o caminho WPF retornava AutoSelect, enquanto a construção simples retornava Automatically Select e OnlyOne. macOS requer o destino net9.0-macos ou net9.0-maccatalyst com a carga correspondente, e Linux não é uma plataforma de impressão suportada.


Passo 2: Aplique sua chave de licença

Sem uma chave, um programa ainda pode listar impressoras e suas bandejas, mas PrintAsync lança IronSoftware.Exceptions.LicensingException com a mensagem Licença de Produção Necessária antes de um trabalho ser criado. Print lança a mesma exceção envolta em System.AggregateException. Com uma chave inválida, a mensagem é Chave de Licença Não Reconhecida. Portanto, um programa não licenciado não produz nenhuma saída, com ou sem marca d'água. O formulário abaixo emite uma chave de teste gratuita.

Comece a usar IronPrint em seu projeto hoje com uma avaliação gratuita.

Primeiro Passo:
arrow pointer

Defina a chave uma vez quando a aplicação iniciar, antes da primeira chamada do IronPrint. A chave vem de uma variável de ambiente, então nenhum commit a contém.

IronPrint.License.LicenseKey = Environment.GetEnvironmentVariable("IRONPRINT_LICENSE_KEY");
C#

Uma vez que uma chave válida é atribuída, IronPrint.License.IsLicensed retorna true. IronPrint.License.IsValidLicense testa qualquer string de chave. A biblioteca nunca lê IRONPRINT_LICENSE_KEY por conta própria, e no teste deste artigo, definir a variável sem a atribuição deixou IsLicensed como false.

Por favor, note: Chaves de Licença IronPrint também cobre a definição da chave no Web.config, App.config ou appsettings.json.

Passo 3: Direcione Seu Assistente para a Documentação LLM do IronPrint

  • llms.txt indexa 43 páginas, uma linha cada. Inclua-o em cada nova sessão.
  • llms-full.txt contém um resumo de cada uma das 33 páginas de documentação em um arquivo.
  • llms-full-catalog.txt é o índice com os artigos do blog incluídos.
  • A referência de objeto fornece a assinatura de cada membro.
  • Ferramentas que leem arquivos de habilidade podem carregar skill.md. Suas seções cobrem instalação, licenciamento, receitas de impressão, implantação de plataforma e correções para falhas conhecidas.
  • A Ficha Técnica do Produto de IA lista as plataformas suportadas e os principais casos de uso.

Se uma tarefa depende de um guia específico, direcione o assistente para essa página.

Envie o índice com uma instrução para permanecer dentro dele.

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.
Text

A linha sobre membros duvidosos permite que o assistente relate uma lacuna em vez de inventar um membro.


Passo 4: Adicione o Contexto do IronPrint ao Seu Projeto

As instruções de chat terminam com a sessão, então as regras do IronPrint vão em um arquivo de projeto que a ferramenta lê toda vez. Claude Code carrega CLAUDE.md, ChatGPT Codex carrega AGENTS.md, e o arquivo do GitHub Copilot é .github/copilot-instructions.md. Cursor carrega regras .mdc de .cursor/rules/bem como AGENTS.md, e Google Antigravity carrega AGENTS.md ou GEMINI.md. O mesmo texto funciona em cada arquivo, com frontmatter MDC adicionado para uma regra do Cursor. Comece com este bloco.

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.
Markdown

O exemplo de arquivo único do arquivo de habilidade ainda fixa o IronPrint 2026.8.1, duas versões mais antigo que o pacote 2026.10.1 testado aqui.


Passo 5: Prompt de Configuração Única

Este prompt combina os Passos 1 a 4 em uma única mensagem, enviada quando um projeto ou sessão começa.

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.
Text
Dicas: Depois, verifique o arquivo do projeto do Passo 4 para confirmar que as regras foram escritas.

Passo 6: Padrões de Prompt que Produzem Código Funcional

Diga de onde vem o nome da impressora, qual tipo de arquivo imprime e cada configuração de impressão.

Vago Imprima a fatura com IronPrint.

Melhor Retire o nome da impressora da configuração, confirme se aparece em Printer.GetPrinterNames e imprima invoice.pdf com PrintSettings definido para A4, orientação automática, escala de cinza e duas cópias.

Nomeie a versão do IronPrint e o framework de destino para o qual o código é destinado.

Melhor Use IronPrint 2026.10.1 em net9.0-windows e atribua a chave de IronPrint_LICENSE_KEY antes do primeiro trabalho.

Solicite arquivos completos. Um fragmento pode deixar de fora a diretiva using IronPrint; e a linha que atribui a chave.

Melhor Retorne todo o Program.cs com cada diretiva using e a atribuição de licença nele, para que ele seja compilado sem edições.


Passo 7: Verifique o Que Você Obtém de Volta

Testes com 2026.10.1 mediram o comportamento por trás de cada erro abaixo.

  • Nomes de impressoras não verificados: um nome que não corresponde a nenhuma impressora instalada não gera erro. Em nosso teste, PrintAsync não gerou exceção, e o trabalho foi para a impressora padrão, Microsoft Print to PDF, que o segurou até que uma pessoa respondesse ao diálogo Salvar Como. Aceite apenas nomes que Printer.GetPrinterNames retornou.
  • Print em um thread de UI: a chamada síncrona bloqueia o thread que a chama, o que congela as interfaces WPF e WinForms, conforme a página de solução de problemas de travamento explica. Use PrintAsync.
  • Uma impressora de teste que solicita: dois trabalhos enviados para Microsoft Print to PDF foram concluídos apenas depois que uma pessoa digitou um nome de arquivo. Um teste não assistido precisa de uma impressora que se conclua sozinha ou do método de captura na próxima seção.
  • ShowPrintDialog em um alvo plain: a página de solução de problemas diz que a chamada pode gerar uma AggregateException em um alvo plain .NET. No Windows, uma compilação net9.0 plain não gerou exceção. A chamada abriu uma caixa de diálogo real de impressão e retornou apenas quando a caixa de diálogo foi fechada, após 10,1 segundos. Mantenha chamadas de diálogo fora do código não assistido.

Deixe o Agente Verificar Seu Próprio Trabalho

Peça ao assistente para executar estas verificações e relatar as evidências.

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.
Text

Trabalhos de impressão silenciosa com IronPrint

No Windows, o IronPrint 2026.10.1 passa cada trabalho para a classe de diálogo de impressão do WPF sem mostrá-la, com um bilhete de impressão que mantém as configurações. Um patch de teste interceptou essa chamada e salvou cada trabalho como um arquivo XPS, então os números nesta seção foram medidos sem papel.

  • Cada página PDF é renderizada como uma imagem na configuração Dpi. Uma página A4 tornou-se uma imagem de 1240 por 1753 pixels a 150 DPI na execução abaixo, e uma imagem de 2479 por 3508 pixels a 300 DPI em nosso teste.
  • PaperSize.A4 produziu páginas de 210 por 297 mm, e PaperSize.Letter produziu páginas de 215,9 por 279,4 mm.
  • Com PaperOrientation.Automatic, uma página em paisagem foi impressa como uma página em paisagem. Com Portrait, a mesma página foi reduzida para caber em uma folha retrato e encheu apenas a parte superior.
  • Uma página PDF colorida chegou como uma imagem cinza quando Grayscale estava ativado. Texto vermelho em um PNG permaneceu vermelho, e apenas o bilhete de impressão solicitou saída em tons de cinza para ele.
  • NumberOfCopies definiu o contagem de cópias do ticket, e o trabalho ainda manteve um conjunto de páginas.

O guia de configurações de impressão diz que a impressora pode limitar o DPI e que algumas plataformas ignoram a contagem de cópias, então ambos os valores são pedidos ao driver.


Formatos de arquivo com IronPrint

Em 2026.10.1, arquivos PDF, PNG, JPG, BMP e TIFF imprimem. Arquivos GIF e HTML lançam System.IO.InvalidDataException com a mensagem Tipo de arquivo não suportado antes de um trabalho ser criado, embora o guia de impressão silenciosa liste ambos os formatos. O arquivo de habilidade lista os cinco formatos que funcionam. Renderize HTML para PDF primeiro, por exemplo, com IronPDF.

Uma imagem é impressa como uma única página, escalada para a largura da página. Um PNG de 1200 por 800 pixels impresso em uma página paisagem A4 com orientação Automatic, e na parte superior de uma página retrato com Portrait.


Um Resultado Que Você Pode Reproduzir

O teste é um único prompt, e todo o código vem do assistente. Crie uma pasta vazia, abra uma nova sessão nela, cole o prompt e verifique o resultado com a lista em 'O que passa'.

Por favor, note: Os requisitos são Windows, o SDK .NET 9, um assistente que execute comandos de terminal, acesso à rede para NuGet e a documentação, uma chave de avaliação ou produção do IronPrint em IRONPRINT_LICENSE_KEY, e o nome de uma impressora instalada em PRINTER_NAME. O prompt captura cada trabalho para um arquivo XPS, de modo que a impressora não recebe nada.

O prompt

Como o aplicativo escreve seu próprio conjunto de testes, os seis arquivos da execução do teste são combinados abaixo em ordem de impressão. Seus quatro PDFs permanecem inalterados, e o PNG e o GIF cada um aparecem em uma página de seu próprio tamanho de pixel.

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.
Text

Saída

O registro de execução não editado da execução dá os valores medidos para cada um dos seis arquivos.

Toda página que a captura escreveu está no PDF abaixo, em ordem de impressão.

Saída em lote conforme o IronPrint construiu os trabalhos, capturados em arquivos XPS no lugar de uma impressora e convertidos para página por página de PDF sem edições.

  • A compilação de Release net9.0-windows relatou 0 avisos e 0 erros.
  • O autoteste do patch passou com um paginador nulo e não escreveu nenhum arquivo.
  • Cinco dos seis trabalhos foram capturados, com 7 páginas no total.
  • Os três PDFs retrato tornaram-se páginas de 210 por 297 mm, uma para cada página de origem.
  • O PDF em paisagem e o PNG tornaram-se páginas de paisagem de 297 por 210 mm.
  • Cada bilhete especificava papel A4, uma cópia, saída em tons de cinza e 150 por 150 DPI.
  • O GIF foi registrado como uma falha com um erro de tipo de arquivo não suportado.
  • A execução com Sem Impressora Tal 12345 parou antes de qualquer trabalho e deixou a pasta de captura inalterada.
  • Uma leitura independente dos arquivos XPS coincidiu com cada número no registro de execução.
  • Um novo início da compilação de aceitação produziu as mesmas cinco capturas.
  • A varredura de chaves não encontrou nenhuma cópia da chave de licença na pasta do projeto.
  • O prompt de instalação manteve a fixação do 2026.10.1.
  • O prompt de documentação não alterou nenhum código.
  • Sua resposta informou que o guia de impressão silenciosa e o arquivo de habilidade discordam sobre GIF e HTML.
  • Um novo CLAUDE.md recebeu as regras do prompt de configuração e os comportamentos medidos.
  • A autoverificação confirmou que todos os cinco trabalhos capturados tinham as configurações solicitadas.
  • Alguns passos foram executados de forma diferente da página. O prompt de aceitação executou primeiro, seguido pelos prompts dos Passos 1, 3, 5 e 7 na mesma sessão. O aplicativo correspondeu a PRINTER_NAME sem considerar maiúsculas e minúsculas e passou o nome exato da lista de impressoras.

O que passa

  • A compilação de Release é bem-sucedida sem edições manuais no código.
  • O aplicativo para antes de qualquer trabalho quando IsLicensed é false ou quando PRINTER_NAME não está em Printer.GetPrinterNames.
  • Cada arquivo imprimível tem uma captura XPS cujas páginas, tamanhos de página e valores de bilhete correspondem a runrecord.md quando você lê os arquivos XPS você mesmo.
  • O GIF é registrado como uma falha, e o lote continua.
  • A chave de licença está ausente em todos os arquivos de projeto.
Por favor, note: Para outro lançamento do IronPrint, altere a versão no passo 1 do prompt e leia primeiro o changelog do IronPrint.

O registro da execução

  • Todas as execuções usaram um desktop Windows 11 x64 com um Core i9-14900KF e 64 GB de memória.
  • Nenhum guia enviou um trabalho para uma impressora física.
  • O projeto deste guia visa net9.0-windows e fixa IronPrint 2026.10.1, com Lib.Harmony 2.3.6 para seu modo de captura.
  • A duração de um guia é a soma dos tempos registrados para os prompts em sua página, e a linha deste guia conta apenas o prompt de aceitação.
  • As versões e modelos na tabela vêm dos próprios arquivos de sessão e logs de cada ferramenta para a execução, não de uma verificação de versão separada.
  • Último teste em 15 de outubro de 2026, para este guia, Claude Code, ChatGPT Codex, GitHub Copilot (apenas prompts 1 e 2) e Google Antigravity, e em 16 de outubro de 2026, para Cursor.
GuiaAssistente e versãoModeloDuração (minutos)
Este guiaClaude Code 2.1.277, uma sessão, prompts de permissão desativadosClaude Opus 523.7
Claude CodeClaude Code 2.1.277, alias opusplan, prompt 3 em modo de planoClaude Sonnet 5, com Claude Opus 5 planejando o prompt 316.4
ChatGPT CodexCodex CLI 0.160.0, em uma única sessãoGPT-6 Luna17.9
GitHub CopilotCopilot CLI 1.0.95, interrompido no prompt 2 pela cota mensalGPT-6 Luna, escolhido pelo Auto1.5, apenas prompts 1 e 2
CursorAplicativo desktop Cursor 3.23.23, prompt 3 em Modo de PlanoGrok 4.7102.8
Google AntigravityAntigravity CLI 1.3.5, que se atualizou para 1.3.6 durante o prompt 1, prompts 1 e 5 enviados com /plan, prompts de permissão ignoradosGemini 3.8 Flash (Alto)61.9

Guias Específicos para Agentes

Cada guia de ferramenta constrói uma tarefa de impressão com estas etapas.


Solução de problemas


Questões?

Se você tiver dúvidas, entre em contato com support@ironsoftware.com

Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais bem estruturados e visualmente atraentes.

Leia Mais

Pronto para começar?

Downloads no NuGet 52,106Versão:2026.11recém-lançado