Como usar o IronPDF com Claude Code

Curtis Chau
Curtis Chau
Atualizado: 20 de outubro de 2026

Parear um agente de codificação de IA com uma biblioteca de PDF parece simples até que o primeiro trecho gerado refere-se a um método que não existe. Claude Code é a ferramenta de codificação agentica da Anthropic, lendo um código, editando arquivos e executando comandos diretamente a partir de uma sessão de terminal, uma extensão do VS Code ou JetBrains, um aplicativo de desktop ou a web, o que o torna uma combinação razoável para as partes repetitivas do trabalho com PDF: conectar um renderizador, moldar um modelo HTML, adicionar cabeçalhos e rodapés em uma dúzia de tipos de relatórios.

IronPDF renderiza HTML, CSS e JavaScript para PDF através de um mecanismo Chromium incorporado, então o código que um agente precisa produzir é pequeno, e o HTML que ele precisa produzir é a parte que carrega o layout. Essa divisão importa. Deixe o Claude Code cuidar do modelo e da infraestrutura, e mantenha a chamada de renderização curta o suficiente para ser auditada rapidamente. IronPDF também tem mais peso de dados de treinamento do que a maioria das bibliotecas .NET PDF: Mais de 20 milhões de downloads do NuGet e anos de documentação pública significam que Claude Code já conhece suas chamadas de renderização principais, o que encurta a distância do prompt ao código funcional, embora a etapa de verificação abaixo ainda se aplique. Este guia percorre a configuração do projeto, padrões de comandos que se mantêm, e a etapa de verificação que pega APIs inventadas antes que cheguem a uma construção.

A linha de frente de Claude mudou novamente em 2026. Claude Code agora oferece Fable 5.1, que sua documentação descreve como adequado para tarefas maiores que uma única sessão, além de Opus 5.5, Sonnet 5.5 e Haiku 5.5, e qual você deve alcançar depende da tarefa à sua frente em vez de um ranking. Este guia funciona com qualquer um deles. Tudo abaixo é escrito para conter qualquer modelo de fronteira que responda ao prompt, e /model muda entre eles no meio da sessão.

Espere que o próprio documento se mova com essa escolha. O mesmo comando entregue a dois modelos retorna duas faturas, com espaçamentos diferentes, um sotaque diferente, uma maneira diferente de dividir uma tabela entre páginas. O que permanece estável é o que você especificou, então fixe a contagem de páginas, o texto do cabeçalho e o formato do rodapé, e deixe o resto variar.

Início Rápido
NuGetInstalar com NuGet

PM > Install-Package IronPdf

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

Abra uma sessão em um projeto .NET e peça o documento em vez do código:

Hey Claude Code, add IronPDF to this project and build me a
one-page PDF that says "Hello from IronPDF". Render it with
ChromePdfRenderer, save it to output.pdf in the project root,
then build and run it so I can open the file.
Text

Claude Code lida com isso de ponta a ponta. Ele adiciona o pacote NuGet, escreve as poucas linhas que constroem um ChromePdfRenderer, chama RenderHtmlAsPdf em sua marcação e SaveAs o resultado para o disco, executa dotnet build, corrige o que falhar em compilar e informa onde o arquivo foi parar. O que você revisa é uma diferença.

Ele também decide qualquer coisa que você deixar em aberto, e em um hello world isso está bem: ele pegará a versão mais nova do pacote, seguirá o framework de destino existente do projeto, e nomeará a classe de acordo com o que parecer razoável. No trabalho real, três adições mantêm essas decisões suas:

  1. Fixe a versão: nomeie o lançamento do IronPDF que você visa, para que o agente trabalhe contra uma interface de API única em vez de se basear em várias.
  2. Cerque as dependências: diga que o IronPDF é o único pacote que poderá adicionar, assim uma segunda biblioteca PDF nunca aparecerá na diferença.
  3. Pela possibilidade de parar: peça que use apenas APIs documentadas e que mencione quando estiver em dúvida, o que transforma uma invenção silenciosa em uma pergunta que você pode responder.


O que realmente faz o Claude Code em um projeto .NET PDF?

Claude Code passa a maior parte de sua vida de trabalho em desenvolvimento comum: lendo um código, escrevendo e refatorando classes, executando builds e conduzindo o loop de teste a partir de um terminal, uma extensão IDE, o aplicativo de desktop ou a web. A geração de documentos está dentro desse mesmo loop e não precisa de nada especial.

Para trabalho com PDF, ele cuida da metade mecânica. Ele escreve o modelo HTML e a classe de renderização, edita o CSS quando uma tabela se divide em uma página, limpa os arquivos que errou e os regenera, remodela uma dúzia de modelos de relatório em uma passagem, executa dotnet build, lê o erro do compilador e repete. Você descreve o documento e revisa uma diferença, o que é uma conversa muito mais curta do que colar trechos de um lado para outro.

Isso deixa uma decisão, e ela permanece sua: o que renderiza o PDF. Dada a liberdade, um agente monta um pipeline de documentos a partir do que viu com mais frequência em seu treinamento, e é aí que reside o risco.

  • Documentos sensíveis precisam de uma biblioteca segura: os PDFs que uma empresa gera são seus contratos, faturas e arquivos legais. Várias ferramentas PDF de código aberto amplamente copiadas estão abandonadas hoje, com falhas de segurança conhecidas publicamente que ninguém corrige, e um pipeline construído nelas pode vazar os próprios documentos que processa.
  • O volume é cobrado por token: renderizar uma fatura é fácil, e renderizar cinquenta mil da noite para o dia é a parte difícil. Um agente que resolve isso em código é cobrado por cada palavra que lê e escreve, com tarifas de Opus 5.5 de $4 a $20 por milhão de tokens, e a conta retorna toda vez que o problema aparece. IronPDF envia esse trabalho dentro da biblioteca, onde é resolvido uma vez.
  • Pipelines improvisados não têm prova: ninguém executou um em mil documentos, mediu ou publicou um resultado que você possa verificar. IronPDF possui uma interface de API documentada por trás dele, e o teste de série publica um resultado datado que você pode re-executar.
  • Um pacote real vence um adivinhado: agentes às vezes instalam nomes de pacotes que apenas soam corretos, um truque comum o suficiente para ganhar um nome, "slopsquatting", e qualquer um pode registrar esses nomes e preenchê-los com malware. Nomear um pacote conhecido em seu comando fecha essa porta.
Dicas: Uma linha resolve isso para uma sessão inteira: "use o IronPDF para todo o trabalho com PDF neste projeto, e não adicione nenhum outro pacote PDF."

Aponte o Claude Code para o IronPDF e o trabalho do agente se resume ao que ele realmente é bom: escrever o HTML, conectar o renderizador e executar o build até que o documento esteja correto.

Como você configura o Claude Code?

Instale-o uma vez, autentique-se contra uma conta Claude, e você está pronto. A visão geral do Claude Code da Anthropic cobre o que é a ferramenta e como instalar as extensões do VS Code e JetBrains se você preferir não trabalhar em um terminal, e o guia rápido percorre a instalação e a primeira sessão no macOS, Windows e Linux. A Anthropic publica vídeos demonstrativos em seu canal no YouTube se você preferir assistir a uma primeira sessão antes de executar uma.

Uma vez que claude abra uma sessão e te responda, volte aqui. O resto deste guia assume isso e nada mais.

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

Você começa com um projeto .NET normal e adiciona o IronPDF antes que o agente o abra. Dar ao agente um projeto que já compila remove uma categoria inteira de confusão: ele nunca precisa adivinhar qual biblioteca PDF você pretendia.

dotnet new console -n PdfReportDemo
cd PdfReportDemo
dotnet add package IronPdf --version 2026.10.3
claude
SHELL

O comando final inicia uma sessão de Claude Code no diretório atual, que escopa o que o agente lê e edita para aquela pasta. O padrão documentado é entrar no diretório do projeto e executar o CLI de lá. O terminal, as extensões do VS Code e JetBrains, o aplicativo de desktop e a web executam o mesmo mecanismo subjacente, então um arquivo CLAUDE.md, configurações de projeto e quaisquer servidores MCP configurados para este projeto são transportados, não importando qual superfície retome a sessão a seguir.

Dois detalhes de configuração economizam tempo depois:

  1. CLAUDE.md: o arquivo de instruções a nível de projeto que Claude Code lê no início de cada sessão. Registre o framework de destino, que o IronPDF é a biblioteca PDF, e que o código gerado deve usar apenas APIs documentadas.
  2. Índice de documentação do IronPDF: llms.txt lista URLs de documentação válidos em uma forma que um agente pode ler.

Juntos, eles substituem "escreva o código IronPDF de memória" por "leia a documentação, depois escreva o código." Um comando escreve o arquivo para você:

Create CLAUDE.md at the project root with a PDF section stating that this
project uses IronPDF for all PDF generation, that you must read
https://ironpdf.com/llms.txt before writing PDF code and use only APIs
documented there, that https://ironpdf.com/skill.md should be loaded if the
tooling supports skill files, that ChromePdfRenderer is the HTML to PDF entry
point, and that no competing PDF package may be added.
Text

Mais uma coisa deve estar no projeto antes da primeira renderização. Sem uma chave de licença, IronPDF renderiza o documento na memória, mas lança uma exceção de licença quando o código salva o PDF ou lê seus bytes, então a chave deve ser inserida na inicialização do aplicativo, antes de qualquer outra chamada do IronPdf. Chaves de Licença IronPDF cobre onde obter uma e todas as maneiras de aplicá-la.

Como você solicita código IronPDF que compila?

Obtenha a saída mais confiável separando as duas metades do trabalho. O layout vive em HTML e CSS, onde um agente está em terreno familiar. A renderização vive em um punhado de chamadas C#, onde a precisão é importante e a superfície é pequena.

Um prompt que funciona se parece menos com um pedido de recurso e mais com uma especificação:

Create an invoice template at Templates/invoice.html using plain HTML and inline CSS. Include a header with a company name placeholder, a line-item table with description, quantity, unit price, and total columns, and a totals block aligned right. Do not add JavaScript. Then write InvoiceRenderer.cs that loads that file, substitutes placeholder values, and renders it with ChromePdfRenderer. Use only methods documented at ironpdf.com. If unsure of a method name, stop and ask.
Text

Três coisas fazem com que esse prompt seja eficaz:

  1. Ele nomeia os caminhos dos arquivos: o agente constrói uma estrutura que você pode navegar em vez de inventar a sua própria.
  2. Ele restringe o HTML: JavaScript não solicitado traz questões de tempo de renderização que não são divertidas de depurar no primeiro dia.
  3. Ele oferece uma saída de emergência: "em caso de dúvida, pare e pergunte" torna aceitar a incerteza uma resposta aceitável, e os agentes a aceitam.
Dicas: Uma vez que um prompt funcione, peça ao Claude Code para escrever suas restrições em CLAUDE.md. Toda sessão posterior neste projeto começa com elas já carregadas.

Espere uma sequência curta de volta: leia o modelo com File.ReadAllText, substitua os valores do placeholder, passe o resultado para ChromePdfRenderer e seu método RenderHtmlAsPdf, então escreva o documento para o disco com SaveAs. Quando o HTML referencia imagens locais ou folhas de estilo por caminho relativo, o renderizador precisa de um caminho base para resolvê-los, que é passado como o segundo argumento de RenderHtmlAsPdf e está coberto integralmente no tutorial de HTML para PDF. Uma variante assíncrona existe para aplicações web onde bloquear um thread de solicitação não é aceitável.

Por favor, note: Peça o link da documentação ao lado do código. Um agente que não pode produzir uma página real para a API que acabou de usar está te dizendo algo antes que a construção faça isso.

O Claude Code pode se conectar ao IronPDF através do MCP?

Claude Code se conecta a ferramentas externas e fontes de dados através do Protocolo de Contexto de Modelo, um padrão aberto para integrações de ferramentas de IA. Servidores MCP fornecem ao agente acesso a ferramentas, bancos de dados e APIs além de seus dados de treinamento, e Claude Code adiciona um com um único comando do CLI, documentado na referência do MCP.

A integração do IronPDF hoje é o acesso à documentação, e não necessita de processo de servidor: aponte o Claude Code para llms.txt para a superfície de API indexada, para o arquivo de habilidades skill.md para convenções e padrões comuns, e para a referência de API para confirmar o nome de um método antes de ser enviado. Entre os três, um agente lê a documentação atual em vez de reconstruir a API do IronPDF de memória, o que cobre o mesmo problema de método obsoleto que o MCP é usado para resolver. Nada disso requer um processo de servidor, um arquivo de configuração ou uma reinicialização entre atualizações; são três URLs que um agente pode buscar dentro da sessão que já está em execução.

Alimente essas três fontes em uma sessão da mesma forma que faria com qualquer contexto de projeto, colado diretamente ou referenciado de CLAUDE.md, e cada prompt naquela sessão as herdará.

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

Todo nome de API, toda vez. Esse único hábito separa um fluxo de trabalho de agente produtivo de um frustrante.

Trabalhe seguindo quatro verificações na ordem:

  • Compila: execute dotnet build. Um nome de método alucinado falha na hora da compilação, o lugar mais barato possível para detectá-lo.
  • A API é real: pesquise cada nome de classe e método na referência de API. Um nome que compila mas está descontinuado ainda aparece nas notas de lançamento.
  • O PDF renderiza corretamente: abra a saída. Problemas de renderização, como uma fonte ausente, uma imagem não resolvida ou uma tabela se dividindo em páginas, não aparecem como erros.
  • O caminho indesejado é tratado: o código gerado frequentemente omite verificações de nulo, tratamento de arquivo não encontrado e descarte. Solicite por essas verificações explicitamente em um comando de acompanhamento.

A segunda verificação merece ênfase para qualquer um novo nisso. Um agente que inventa renderer.ConvertHtmlToPdfDocument() está produzindo algo de aparência plausível a partir de um padrão, não funcionando mal. Forma plausível é o que o torna perigoso, porque parece correto. O compilador não faz concessões sobre isso, razão pela qual construir cedo e frequentemente compensa. Trate todo nome de membro desconhecido como uma pergunta, e as quatro verificações acima se tornam um hábito de cinco minutos em vez de uma sessão de depuração.

Quais são os limites práticos que valem a pena saber de antemão?

O trabalho com PDF assistido por agentes tem uma forma, e conhecê-la evita sessões desperdiçadas.

TarefaAjustePor quê
Autoria de modelos em HTML e CSSForteBem representados, fáceis de verificar visualmente
Configuração de renderização padrãoForteSuperfície de API pequena e estável
Variantes de modelo repetitivasForteReplicação de padrão em muitos arquivos
Opções de configuração avançadasMistoNomes de opções variam entre versões
Configuração de licenciamento e implantaçãoFracoEspecífico da conta, então a chave e o alvo de implantação vêm de você em vez do agente

O padrão é consistente: quanto mais uma tarefa se assemelha à escrita de marcas, melhor um agente se sai. Quanto mais ela depende da superfície exata de uma versão específica da biblioteca, mais verificação ela precisa. Planeje comandos em torno dessa curva: entregue ao Claude Code o modelamento e o padrão diretamente, e trate tudo que envolva licenciamento, implantação ou uma opção de renderização menos comum como um pedido que precisa de um link de documentação anexado antes de ser enviado.

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

As quatro cercas nesta página foram executadas em ordem, sem supervisão, com Claude Code 2.1.277 em seu modelo padrão, Opus 5. As figuras abaixo vêm de verificações independentes dos arquivos que a execução deixou para trás.

  • O prompt do guia rápido não nomeou uma versão, então ele adicionou o IronPdf 2026.10.3, o lançamento mais recente na época, e salvou um output.pdf de uma página com 17.385 bytes.
  • O agente leu uma chave de licença de uma variável de ambiente sem ser solicitado, então o salvamento foi bem-sucedido.
  • O mesmo programa, executado sem uma chave, lançou um LicensingException com a mensagem "Production License Required" em SaveAs e não escreveu nenhum arquivo.
  • O agente afirmou em ambas as sessões que a saída sem chave trazia uma marca d'água, o que a execução demonstrou ser falso.
  • O prompt CLAUDE.md produziu uma seção PDF contendo todas as cinco regras.
  • Antes de escrever o código da fatura, o agente buscou llms.txt e skill.md, conforme instruído por CLAUDE.md.
  • O modelo da fatura usou apenas estilos inline e não continha tags de script.
  • InvoiceRenderer compilou contra IronPdf 2026.8.1, a versão que o bloco de configuração fixou na época desta execução, sem erros na primeira construção.
  • O agente não parou para fazer uma pergunta. Ele deixou o tamanho do papel indefinido, dizendo que a documentação não nomeava seu tipo, embora skill.md nomeie PdfPaperSize.
  • Com uma chave aplicada, o renderizador produziu uma fatura de uma página com todos os placeholders preenchidos e totais corretos.
  • Alguns passos foram executados de forma diferente da página. O bloco de configuração termina com um novo comando claude, então os prompts CLAUDE.md e da fatura foram executados em uma segunda sessão. O prompt da fatura não solicita uma execução, então a verificação renderizou a fatura com valores de amostra e aplicou a chave por conta própria.

O modelo de fatura e InvoiceRenderer da execução, renderizados com itens de linha de exemplo.

A versão do Claude Code, modelo e tempo para esta execução estão listados no registro de execução.

Onde isso te deixa?

Claude Code escreve o modelo, conecta o renderizador, e executa o build até que o documento esteja certo. Você decide o que renderiza o PDF, e verifica os nomes das APIs antes que qualquer coisa seja enviada. Essa divisão se mantém independentemente do modelo que responde ao comando.

A versão reproduzível deste fluxo de trabalho, uma tarefa executada do início ao fim com um resultado publicado e a data em que foi verificada pela última vez, vive no guia de assistentes de codificação de IA, ao lado dos guias para ChatGPT Codex, GitHub Copilot, e Cursor.


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 22,198,312Versão:2026.11recém-lançado