Como usar o IronPrint com Claude Code

Curtis Chau
Curtis Chau
Atualizado: 26 de outubro de 2026

Um laboratório hospitalar imprime três tipos de documentos de um serviço. Etiquetas de amostras vão para a impressora de etiquetas na mesa de coleta, relatórios de resultados vão para a impressora do escritório, e manifestos de correio vão para a sala de despacho. Um arquivo de roteamento nomeia a impressora para cada tipo de documento, e um único caractere errado nesse arquivo pode enviar resultados de pacientes para outra sala sem gerar erro. Claude Code, a ferramenta de codificação agente da Anthropic, edita arquivos e executa comandos em um repositório. Está disponível como uma ferramenta de linha de comando, como extensões para editores VS Code e JetBrains, no aplicativo desktop Claude e em claude.ai/code.

IronPrint imprime PDFs e imagens a partir do .NET, quer silenciosamente ou através da caixa de diálogo do sistema operacional. A propriedade PrintSettings.PrinterName seleciona a impressora para um trabalho, e Printer.GetPrinterNames lista as impressoras instaladas na máquina. Os quatro prompts testados abaixo têm o Claude Code para construir um roteador de impressoras para esse laboratório, e as seções entre eles registram o comportamento do IronPrint em que cada prompt se baseia.

Início Rápido
NuGetInstalar com NuGet

PM > Install-Package IronPrint

Instale o IronPrint executando o comando acima no Console do Gerenciador de Pacotes NuGet, ou procure pelo pacote no Gerenciador de Pacotes NuGet.

Inicie claude em um terminal aberto na pasta do projeto e troque o modelo com /model opusplan antes de enviar o primeiro prompt. Digitar @ antes de um caminho inclui o conteúdo desse arquivo na solicitação.

Add the IronPrint NuGet package, version 2026.10.1, to LabPrintRouter.csproj.
Then have Program.cs check the printer names in @config/printer-routes.json.

The program does this, in order:

1. Applies the license key and prints License.IsLicensed.
2. Prints each name from Printer.GetPrinterNames on its own line, in quotes.
3. Prints each route's document type, its printer name in quotes, and installed or missing.

A route's printer counts as installed only on an exact match, case and spaces included.
Don't send any print job. Every printer on this machine opens a Save dialog.

My key is in the IRONPRINT_LICENSE_KEY environment variable.
Program.cs reads it at startup and assigns it to License.LicenseKey.
Don't print its value, and don't dump the environment to find it.
If you check the variable, a yes or no on whether it's set is enough.
Text

As aspas na saída tornam visível um espaço final.



O que o Claude Code faz em um projeto de impressão .NET?

O agente escreve um serviço de roteamento que lê o arquivo de roteamento, compara cada nome de impressora configurado com as impressoras instaladas e grava uma decisão para cada documento. O Claude Code também pode executar o programa e seus testes e corrigir as falhas que eles relatam. O desenvolvedor decide qual impressora atende a cada tipo de documento.

Declare o nome do pacote e a versão no primeiro prompt. No ataque conhecido como slopsquatting, os atacantes registram pacotes prejudiciais sob nomes que modelos de linguagem alucinam. Um agente que escolhe um nome de pacote por si só pode instalar um desses pacotes.

Como você configura o Claude Code?

A instalação e o primeiro login seguem o início rápido da Anthropic. A configuração é feita uma vez claude abre uma sessão em um terminal e responde a um prompt.

Como você configura um projeto no qual o Claude Code possa trabalhar?

Coloque as entradas no repositório antes do primeiro prompt. O projeto exemplo para este guia contém um aplicativo de console .NET 9 para net9.0-windows, um arquivo de roteamento para quatro tipos de documento e uma caixa de entrada de sete PDFs cujos nomes começam com seu tipo de documento. Uma rota usa o nome exato de uma impressora instalada. As outras três usam uma impressora que não está instalada, um nome instalado em um caso diferente e um nome instalado com um espaço final.

O Claude Code lê o CLAUDE.md quando uma sessão começa, então suas regras se aplicam em cada sessão posterior. Uma vez que o Quickstart adicionou o pacote, o segundo prompt escreve esse arquivo e define um subagente somente leitura que revisa o código de impressão.

Add a Printing section to a new CLAUDE.md at the repository root.
Later sessions should follow these rules from it:

- All printing goes through IronPrint. Add no other printing library.
- The package is IronPrint, at the version LabPrintRouter.csproj references now.
- Look up IronPrint member names in docs/IronPrint.xml.
- config/ and inbox/ are inputs. Leave them unchanged.
- The program sends no print job unless it runs with --send.
- Never run it with --send on this machine.
- Read the key from IRONPRINT_LICENSE_KEY. Never print it, save it, or dump the environment.

Copy IronPrint.xml to docs/ now, from the ironprint 2026.10.1 folder of the local NuGet cache.
Use the one under lib/net7.0-windows7.0.
If it isn't there, tell me, and still add the subagent below.

Then create a subagent at .claude/agents/printer-name-auditor.md.
Limit its tools to Read, Grep and Glob.
It reviews Services/ and returns three lists:

- IronPrint types and members in use, flagging any that docs/IronPrint.xml lacks.
- Types under IronSoftware.*, listed apart, since they ship in other assemblies.
- Every place a PrinterName gets set, and whether that name passed an exact installed check first.
Text

O Claude Code observa o .claude/agents e carrega uma nova definição de subagente adicionada sem reiniciar, mas somente quando essa pasta existia no início da sessão. Portanto, o repositório exemplo contém a pasta, com um arquivo vazio .gitkeep, antes da sessão abrir. llms.txt do IronPrint indexa seus guias de como fazer, sua habilidade de agente e sua outra documentação.

Aplique a chave de licença antes da primeira chamada de impressão. Sem uma chave, Printer.Print e Printer.PrintAsync lançam uma exceção, e nenhum trabalho é enfileirado. A página Chaves de Licença do IronPrint oferece uma chave de avaliação e mostra tanto a atribuição de código quanto a configuração de arquivo.

Quais regras de impressora do IronPrint pertencem ao CLAUDE.md?

Investigamos o comportamento de cada linha no IronPrint 2026.10.1, uma vez licenciado e uma vez não licenciado. Cole o bloco na seção de Impressão.

These printer rules come from probes on IronPrint 2026.10.1:

- PrintSettings.PrinterName must equal a Printer.GetPrinterNames() entry, character for character.
- Any other name sends the job to the Windows default printer, and nothing throws.
- That covers a missing printer, a different case, a trailing space and an empty string.
- Decide whether to print with StringComparison.Ordinal.
- A trimmed or case-blind match may label a near miss, but it never sends a job.
- Printer.GetPrinterTrays() returns an empty list for a name that isn't installed.
- An empty tray list is also normal for some real printers, so it can't test a name.
- Printer.GetPrinterNames() works without a key, so a printer list proves nothing about licensing.
- IronPrint doesn't read IRONPRINT_LICENSE_KEY by itself. Assign License.LicenseKey at startup.
- Assigning a null key doesn't throw. License.IsLicensed just stays false.
- Without a key, Printer.Print throws AggregateException with a LicensingException inside.
- Without a key, Printer.PrintAsync throws LicensingException directly.
- LicensingException is IronSoftware.Exceptions.LicensingException, internal to IronPrint.dll.
- Print and PrintAsync both wait on the driver, and a Save dialog keeps them waiting.
Markdown

As duas formas de exceção afetam o manuseio de erros. Um manipulador verifica a exceção de PrintAsync mas a exceção interna de Print. Nenhum pode usar catch (LicensingException), porque o tipo não é público e essa cláusula falhou com CS0122 na investigação.

O IronPrint rejeita um nome de impressora que não coincide?

De acordo com o guia de especificação de nome de impressora, a comparação de nomes é sensível a maiúsculas e minúsculas, e um nome errado falha silenciosamente ou gera um erro. Nosso teste enviou um relatório de duas páginas sob quatro nomes que não correspondiam a uma impressora instalada. Os nomes eram um nome de impressora não instalado, "adobe pdf" para o "Adobe PDF" instalado, o nome instalado seguido de um espaço e uma string vazia. Nenhuma das quatro chamadas lançou exceção, e cada trabalho foi enviado para a fila padrão, que na máquina de testes é Microsoft Print to PDF.

Portanto, o roteador precisa comparar cada nome configurado com os nomes instalados por conta própria, antes de chamar o método de impressão.

Como o IronPrint constrói um trabalho de impressão?

O IronPrint envia cada página do PDF para o driver como uma imagem na resolução em PrintSettings.Dpi. O trabalho de teste para Microsoft Print to PDF produziu um PDF A4 de duas páginas, em que cada página era uma única imagem de 1239 por 1754 pixels sem camada de texto, renderizada a 150 DPI. As saídas de exemplo no guia seguem o mesmo padrão no padrão de 300 DPI, com 2479 por 3508 pixels por página A4. Portanto, uma verificação da saída de uma impressora de PDF deve comparar contagens de páginas ou imagens, porque o texto impresso não pode ser pesquisado.

Para inspecionar trabalhos sem imprimi-los, a configuração de teste conectou a chamada de impressão WPF que o IronPrint usa no Windows. O hook grava cada trabalho em disco no formato XPS e não envia nada para a fila, e as imagens de página salvas mediam 1239 por 1754 pixels, o mesmo que o trabalho de teste. O IronPrint grava as outras configurações no ticket de impressão do trabalho. Com Grayscale ligado, o ticket solicitou saída em monocromático. As imagens das páginas foram armazenadas como RGB e continham apenas pixels em tons de cinza. A contagem de cópias do ticket veio de NumberOfCopies, e o trabalho continha cada página uma vez.

A rota da etiqueta mostra o que um fallback faz para um trabalho. A entrada é specimen-label__S-031.pdf, uma etiqueta de 100 por 50 mm da inbox, que o arquivo de roteamento envia para LAB-ZEBRA-01 a 300 DPI com PaperSize.PrinterDefault.

Saída

As configurações da rota da etiqueta foram enviadas sem a verificação de nome, então o trabalho retrocedeu para Microsoft Print to PDF. O tamanho de papel padrão da impressora então foi resolvido para o papel A4 dessa impressora, e a etiqueta se tornou uma imagem de 1179 por 591 pixels em uma página A4 no modo paisagem. O trabalho escalou essa imagem para 297 por 149 mm, a largura total do papel.

Etiqueta de amostra S-031 como o IronPrint construiu o trabalho sem a verificação de nome. Uma página A4 no modo paisagem a 300 DPI, endereçada à Microsoft Print to PDF e capturada para um arquivo no lugar de uma impressora.

Como você solicita código IronPrint que compila?

Envie o roteador e seu relatório como um prompt no modo de plano, para que o design seja acordado antes de quaisquer alterações de arquivo. Pressione Shift+Tab até que a barra de status mostre o modo de plano, então envie o prompt. Sob opusplan, o plano vem do Opus, e o Sonnet faz as alterações após a aprovação do plano.

Build the router in Services/PrintRouter.cs and the report in Services/RoutingReport.cs.
Call both from Program.cs after the printer check.
Program.cs passes PrintRouter the list from one Printer.GetPrinterNames call.

Each PDF in inbox/ is named <documentType>__<id>.pdf.
For each file, PrintRouter does this:

1. Finds the route for its document type in config/printer-routes.json.
2. Checks the route's printer against that list.
3. Builds PrintSettings from the route's paper size, orientation, DPI, copies and grayscale.
4. Sends the job with Printer.PrintAsync, but only under --send.

Each file gets the first of these decisions that fits:

- send, when the printer name matches an installed name exactly.
- name-mismatch, when it matches one after ignoring case and outer spaces.
- not-installed, when nothing matches.
- no-route, when the config has no route for the type.

Only send files reach the print call.
Put that call behind an interface so tests can use a fake.

Write out/routing-report.csv with a header row and one row per file, sorted by file name.
Its first columns are File, DocumentType, ConfiguredPrinter, Decision and InstalledName.
Then come PaperSize, Orientation, Dpi, Copies and Grayscale from the route.
InstalledName holds the installed printer for send and the near match for name-mismatch.
It stays empty for the other two decisions.
A no-route row leaves the five route columns empty too.
Write Grayscale as true or false.
Print a count of files per decision.

Run the program without --send and show me the CSV.
Then have the printer-name-auditor subagent review Services/.
Text

Duas partes do prompt protegem o roteamento.

  1. A bandeira de envio: sem --send, o programa não envia trabalho, então o agente pode executar e testar o roteador em uma máquina cujas impressoras abrem um diálogo.
  2. O subagente auditor: um subagente personalizado carrega o CLAUDE.md, então as regras de nomeagem de impressora se aplicam à sua revisão também. Dos agentes embutidos, o Explore e o Plan começam sem CLAUDE.md.
Dicas: Antes de aprovar o plano, confirme que o nome dado ao IronPrint é o nome instalado do check exato. Um plano que combina nomes sem considerar maiúsculas ou minúsculas e, em seguida, passa o nome configurado envia os manifestos do correio para a impressora padrão.

O código de roteamento do IronPrint pode ser testado sem uma chave de licença?

Sim, desde que os testes substituam a chamada de impressão. Ler o arquivo de roteamento, listar as impressoras instaladas e construir PrintSettings todos funcionam sem uma chave, então cada decisão de roteamento pode ser testada em um servidor de compilação que não possui chave.

Add a LabPrintRouter.Tests xUnit project that targets net9.0-windows.
It tests PrintRouter through a fake print sink.

The tests read the copies of inbox/ and config/ in their output folder.
Give the router a fixed printer list of "Adobe PDF", "Microsoft Print to PDF" and "Fax".
Assert these results:

- The decision for each of the 7 files.
- The fake receives the 2 result reports and nothing else.
- RPT-4471 goes out with A4, Portrait, 150 DPI, 1 copy and grayscale on.
- Printer.GetPrinterNames runs without throwing while no key is applied.

Set the project up this way:

- It lives in its own folder, and the repository root gets no solution file.
- LabPrintRouter.csproj must not compile anything in that folder.
- The test output folder gets copies of config/ and inbox/.

Run dotnet test one time, in a child process that has no IRONPRINT_LICENSE_KEY.
Tell me the pass count from that run.
Text

O que você deve verificar antes de confiar no código IronPrint gerado?

Revise o código IronPrint gerado com estas verificações.

  • A compilação: um membro que o IronPrint não tem para dotnet build com um erro de compilação. O IronPrint.xml enviado também documenta um método da classe interna PdfiumUtils, e o código que a chama falha com CS0122.
  • O relatório de roteamento: compare cada decisão com o arquivo de roteamento e a lista de impressoras instaladas antes do primeiro trabalho real.
  • Uma página de teste por impressora: antes da liberação, confirme em cada dispositivo que uma página de teste foi impressa onde a rota diz.

O guia de assistentes de codificação AI fornece uma tarefa completa do IronPrint, com critérios de passagem fixos, como um teste repetível.

O que os prompts produziram em uma execução real?

Os quatro prompts foram executados em uma única sessão do Claude Code, na ordem mostrada. Antes do prompt 3, o bloco de regras foi colado em CLAUDE.md, e ninguém editou o código manualmente.

  • A saída do Quickstart nomeou todas as quatro impressoras instaladas e marcou uma rota instalada e três ausentes.
  • O relatório de roteamento continha uma linha para cada um dos 7 arquivos.
  • 2 arquivos foram marcados enviar, 2 nome-incompatível, 2 não-instalados, e 1 sem-rota.
  • Cada decisão correspondia à nossa verificação independente contra as impressoras instaladas.
  • A correspondência próxima foi Adobe PDF para o manifesto de courier e Microsoft Print to PDF para o resumo da enfermaria.
  • Uma execução limpa de Release em uma cópia nova produziu o mesmo relatório.
  • Sem a chave, o programa relatou IsLicensed como False e fez as mesmas 7 decisões.
  • 10 de 10 testes foram aprovados em um processo sem variável IRONPRINT_LICENSE_KEY.
  • O subagente não encontrou nenhum membro do IronPrint faltando no IronPrint.xml.
  • O subagente encontrou uma atribuição de nome de impressora, colocada após a verificação exata.
  • As filas de impressão estavam vazias após a execução, e nenhum comando nas transcrições usou --send.
  • A captura dos dois trabalhos enviados continha 3 páginas de retrato A4 para a fila Adobe PDF, cada uma uma imagem de 1239 por 1754 pixels.
  • Cada prompt deixou uma compilação de Release sem avisos ou erros.
  • Uma verificação das transcrições, os arquivos de sessão e o repositório não encontrou cópia da chave de licença.
  • Alguns passos foram executados de forma diferente da página. Uma resposta digitada aprovou o plano do prompt 3, porque a sessão foi executada sem interface. Nenhum trabalho foi impresso, porque cada impressora na máquina de teste abre um diálogo de Salvar, então os dois trabalhos enviados foram capturados para XPS.

A primeira linha de envio no relatório de roteamento foi result-report__RPT-4471.pdf, um relatório de resultados de duas páginas da inbox.

Saída

A ferramenta de captura passou as configurações desta linha do relatório de roteamento para o IronPrint. O PDF abaixo contém ambas as páginas capturadas sem alterações.

Relatório de resultados RPT-4471 como o IronPrint construiu o trabalho de envio do relatório de roteamento da execução. Ambas as páginas são A4 retrato a 150 DPI para a fila Adobe PDF, capturadas para um arquivo no lugar de uma impressora.

Cursor também tem um modo de plano, e o guia do Cursor envia seu prompt 3 nele. Codex lê suas regras de projeto do AGENTS.md, o equivalente do CLAUDE.md, como mostra o guia do ChatGPT Codex. A versão do Claude Code desta execução, modelos e duração total aparecem no registro da execução ao lado da máquina de teste.


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