Como usar o IronPDF com o Cursor
Peça a qualquer assistente de IA para escrever código IronPDF e ele produzirá algo que parece correto. Às vezes é. Outras vezes, ele chama um método que nunca existiu, e você descobre isso na compilação em vez da revisão. O modelo não está com defeito. Ele está preenchendo uma lacuna no que conhece com algo plausível, que é o mesmo instinto que o torna útil e perigoso na mesma medida.
Cursor é um editor de código focado em IA construído no VS Code, e seu recurso mais valioso para trabalho com bibliotecas não é a caixa de bate-papo. É a capacidade de buscar a documentação de uma biblioteca a partir de um link e de comprometer regras de projeto no repositório, para que o editor responda com APIs reais do IronPDF e siga as convenções da sua equipe sem precisar ser informado duas vezes. O IronPDF renderiza HTML, CSS e JavaScript em PDF através de um motor Chromium embutido. Nenhuma ferramenta conhece a outra, e não há integração para instalar. O que você configura em vez disso é o contexto, e essa configuração é o que a primeira metade deste guia cobre.
Uma distinção antes de começar, porque dois tópicos semelhantes são confundidos. Este guia é sobre usar um editor de IA para construir software com IronPDF. Não se trata de usar modelos de IA para ler ou analisar o conteúdo de arquivos PDF, que o tutorial de processamento de PDF com IA cobre separadamente.
Início RápidoAbra um projeto C# no Cursor e solicite a documentação do IronPDF em vez da memória do modelo:
Read https://ironpdf.com/llms.txt and the pages it links to.
In this C# project, create Program.cs that renders "<h1>Hello from IronPDF</h1>"
to hello.pdf. Read the license key from the IRONPDF_LICENSE_KEY environment
variable. Use only methods that appear in the linked documentation.
O Cursor escreve as poucas linhas que importam: construa um ChromePdfRenderer, chame RenderHtmlAsPdf na marcação e SaveAs o resultado no disco. O link de documentação na primeira linha é o que separa isso de uma mesma solicitação digitada em uma janela de chat geral, e configurá-lo é a primeira seção real abaixo.
Uma breve nota de segurança. Um agente com acesso a gravação de arquivos e terminal nunca deve receber uma chave de licença em linha, então mantenha-a em uma variável de ambiente ou em um arquivo de configuração que é excluído do controle de versão. O guia da chave de licença cobre as opções suportadas.
Fluxo de trabalho mínimo (5 etapas)
- Baixe a biblioteca PDF C# do NuGet
- Aponte o Cursor para a documentação do IronPDF com um link para
llms.txt - Comprometa uma regra de projeto fixando a versão do IronPDF e suas convenções
- Referencie arquivos específicos com menções
@e o link de documentação ao solicitar - Compile, abra o PDF e verifique cada nome de API contra a referência de API
O que está realmente rodando por trás da caixa de bate-papo?
O Cursor não vem com um único modelo anexado. Ele envia o seu próprio, e também permite que você aponte o mesmo editor para o de outra pessoa.
Composer é o modelo agêntico próprio do Cursor. O seletor de modelos também oferece os modelos Grok da SpaceXAI, que o Cursor co-desenvolveu, e modelos da OpenAI, Anthropic, Google e outros laboratórios. Você pode alternar entre eles dentro de uma única sessão. Tab, a conclusão em linha do Cursor, termina uma linha e prevê a próxima edição. O teste executado abaixo usou o Grok 4.7.
Para o trabalho em PDF, há uma consequência prática que vale a pena planejar em torno disso. A maior parte de uma sessão de documento é trabalho barato e repetitivo: ajuste uma margem, reconstrua, olhe para o resultado, ajuste novamente. Ocasionalmente, uma tabela quebra em uma página por um motivo que nenhum compilador explicará, e esse é o momento de passar para um modelo que pensa mais antes de editar. Espere que o documento mude com a escolha também. O mesmo comando dado a dois modelos retorna dois layouts que diferem em espaçamento e quebras de página enquanto ainda atendem ao que você especificou explicitamente, e isso é o argumento para fixar a contagem de páginas, o texto do cabeçalho e o formato do rodapé em vez de confiar em um padrão.
Isso também significa que esta série se sobrepõe aqui. Execute um modelo Claude dentro do Cursor e as observações no guia Claude Code ainda se aplicam ao seu resultado, porque o modelo é o mesmo, embora a superfície não seja.
Como você fornece a documentação do IronPDF ao Cursor para que ele pare de adivinhar?
O Cursor costumava indexar a documentação externa atrás de uma menção @Docs. Seu notas da versão 3.21 registram que a opção Docs "já havia parado de adicionar documentação ao contexto do agente" e a removeram do menu @. O que funciona hoje é um link. O agente do Cursor tem uma ferramenta web que busca um URL nomeado no prompt, e o IronPDF publica llms.txt, um índice de suas páginas de documentação. Em um teste com o CLI do Cursor, o agente buscou aquele índice e depois as páginas de cabeçalhos e rodapés às quais ele se liga antes de responder. Fornecer a documentação do IronPDF ao Cursor é o passo de configuração de maior valor neste guia, porque substitui a memória por recuperação.
O raciocínio vale a pena ser declarado claramente para quem é novo nisso. Um modelo interrogado sobre uma biblioteca específica se baseia no que ele absorveu durante o treinamento, o que pode estar um ano desatualizado e nunca foi verificado em relação à versão atual. Um link de documentação dá ao editor algo para olhar. A diferença aparece imediatamente em nomes de métodos: um modelo não fundamentado inventa renderer.ConvertHtmlToPdfDocument(), e ele lê perfeitamente até o compilador discordar.
O link vai em um prompt como uma linha de texto:
Use the IronPDF docs at https://ironpdf.com/llms.txt.
What are the options for adding a footer with page numbers to a rendered PDF?
Show the exact class and property names from the documentation, and link the
page you took them from.
Pedir pela página fonte é um hábito de verificação barato. Se o editor não puder indicar uma página de documentação real para a API que acabou de recomendar, isso é um sinal para verificar antes de escrever código contra ela.
Como você escreve regras de projeto que codificam suas convenções do IronPDF?
As regras de projeto do Cursor vivem em um diretório .cursor/rules na raiz do repositório e são controladas por versão, portanto, são comprometidas juntamente com o código e todos os desenvolvedores herdam o mesmo comportamento sem configurar nada.
As regras são arquivos .mdc: markdown com frontmatter YAML carregando description, globs e alwaysApply. Cursor os lê de forma recursiva, então subdiretórios funcionam. Um arquivo .md simples nessa pasta é ignorado, porque não tem frontmatter para ativar. Uma regra para convenções do IronPDF se parece com isso:
---
description: IronPDF conventions for PDF generation in this project
globs: **/Services/**/*.cs, **/Pdf/**/*.cs
alwaysApply: false
---
# IronPDF conventions
- Use ChromePdfRenderer for all HTML-to-PDF conversion.
- Target the IronPDF version pinned in Directory.Packages.props. Do not upgrade it
as part of an unrelated change.
- Never inline a license key. Read it from configuration or the
IRONPDF_LICENSE_KEY environment variable.
- Prefer the shared PdfDocumentService helper over constructing a renderer
per call. A ChromePdfRenderer instance is reusable.
- Use the async rendering methods in web request paths.
- Do not invent IronPDF API names. If a method is uncertain, say so and cite
the documentation instead of guessing.
Essa última linha faz mais do que aparenta. Dizer ao modelo que admitir incerteza é aceitável reduz APIs inventadas, e colocá-lo em uma regra comprometida significa que você para de repetí-lo em cada comando.
A linha globs é a parte que vale a pena copiar deliberadamente. Tudo marcado alwaysApply: true é carregado em todas as solicitações e gasta orçamento de contexto, então escopar a regra IronPDF para os caminhos onde o código PDF realmente vive mantém isso fora de solicitações que não têm nada a ver com renderização.
AGENTS.md simples na raiz do projeto, o mesmo arquivo que o ChatGPT Codex e o Google Antigravity leem. Ele não carrega frontmatter, então não possui globs e sempre se aplica. Escolha .cursor/rules quando você quiser escopo, e AGENTS.md quando quiser um arquivo de instruções que várias ferramentas respeitem.Um limite surpreende as pessoas: as regras se aplicam a interações de agente e chat, não ao preenchimento Tab ou edições inline. Uma convenção codificada em uma regra molda o que o agente escreve e não impedirá o Tab de sugerir algo diferente. Vale a pena saber antes de concluir que uma regra está sendo ignorada.
Qual modo se encaixa na mudança?
O Cursor expõe várias maneiras distintas de fazer uma edição, e escolher a errada desperdiça tempo. O instinto útil é o escalonamento.
| Modo | Alcance-o quando | Tarefa típica de PDF |
|---|---|---|
| Aba | Você já está digitando e a próxima edição é previsível | Terminando uma propriedade de opções de renderização que você já configurou antes |
| Edição inline | A mudança cabe em uma frase e vive em um arquivo | Adicionando uma margem, um rodapé ou uma configuração de tamanho de página |
| Agente | O trabalho abrange arquivos ou precisa de uma compilação e um loop de correção | Integrando um renderizador em um serviço e fazendo-o compilar |
| Planeje primeiro | Uma reescrita é grande o suficiente para que revisá-la depois do fato seja pior do que concordar sobre ela primeiro | Migrando um gerador de relatórios de outra biblioteca PDF |
| Agente na nuvem | A tarefa não precisa ser supervisionada e não bloqueia nada | Escrevendo uma suíte de testes em torno da saída de PDF |
Uma edição inline em um renderizador é a ilustração mais clara, porque você descreve a mudança e revisa uma diferença no local em vez de ler um novo arquivo:
Add a 25mm top margin and an HTML footer showing "{page} of {total-pages}",
centered, max height 15mm.
O que cai no arquivo é curto o suficiente para verificar num relance:
var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.MarginTop = 25;
renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter
{
MaxHeight = 15,
HtmlFragment = "<div style='text-align:center'>{page} of {total-pages}</div>",
};
MarginTop = 25 reafirma a margem superior padrão de 25 milímetros do IronPDF, de modo que essa linha não altera a página. Nenhuma das margens move o rodapé. A margem inferior define onde o corpo para acima dela, como a correção do rodapé mais tarde nesta página mostra.
{page} e {total-pages} são campos de mesclagem próprios do IronPDF, em vez de placeholders de string que você substitui, o tipo de detalhe que a documentação acerta e um palpite insuficientemente fundamentado geralmente não.
O que uma menção @ realmente muda?
Menções de contexto dizem ao editor exatamente o que procurar. Nomear o arquivo que constrói um PDF produz um resultado muito melhor do que descrevê-lo, porque uma descrição é com perda e uma referência de arquivo não é.
@Services/InvoiceRenderer.cs @Templates/invoice.html Use the IronPDF docs at https://ironpdf.com/llms.txt.
The footer overlaps the last line of the invoice table. Fix it in the renderer
configuration, not the template. Explain which setting causes the overlap.
Junto com os arquivos, o menu @ do Cursor aceita pastas para trabalhos que abrangem um módulo, saída do terminal, chats anteriores, diffs do Git e o navegador embutido. Quando você não sabe qual arquivo é importante, deixe a menção de fora e o agente busca a base de código por conta própria. Combinar um arquivo com um link de documentação, como acima, é o padrão que mantém o trabalho com IronPDF preciso: o arquivo fornece o que seu código faz atualmente, e os documentos fornecem o que a biblioteca realmente oferece.
Esse comando em particular também ilustra por que a fundamentação é importante. Um rodapé configurado sem uma margem correspondente sobrepõe ao corpo, porque o rodapé ocupa um espaço que o conteúdo não cede por si só. É uma configuração do renderizador em vez de um problema de CSS, e o guia de cabeçalhos e rodapés documenta o relacionamento.
Essa é a fatura que o teste de execução renderizou após a correção:
Como você planeja e executa uma migração para o IronPDF?
As migrações são onde uma reescrita multi-arquivo não revisada se torna cara, porque desfazer uma é mais difícil do que escrevê-la. O planejamento antes da implementação existe exatamente para isso: ele toma o objetivo, faz perguntas esclarecedoras e produz um plano editável antes de qualquer código ser escrito.
@Reports/ Use the IronPDF docs at https://ironpdf.com/llms.txt.
This folder builds PDFs by positioning text at coordinates with another library.
Plan a migration to IronPDF using HTML templates.
Summarize what the current output looks like, covering page size, sections, and
fonts, then propose the template structure and the files that change. Keep
existing public method signatures so callers don't change. Don't write code yet.
Revise o plano, corrija-o em uma ou duas frases e entregue-o para ser implementado. O modo agente lê a base de código, edita arquivos, executa comandos do terminal, lê as saídas e itera, então o acompanhamento é curto:
Implement the approved plan. Then run dotnet build, fix what breaks, and
show me the diff. Don't add new packages.
Confinar o agente ao plano aprovado e proibir novos pacotes importa mais do que parece. Agentes deixados sem restrições tendem a tratar uma migração como um convite para redesenhar a convenção de chamada como um bônus.
Trabalhos que não precisam de supervisão podem ser executados em um agente de nuvem enquanto você continua em outros lugares. Uma suíte de testes em torno da saída de PDF é um bom candidato, porque os testes afirmam sobre o documento e não sobre a implementação e não precisam que a migração esteja concluída primeiro:
Write xUnit tests for the migrated report output: result is non-empty, begins
with the %PDF- signature, extracted text contains the bound company name, and
page count matches expectation. No golden-file byte comparisons, since
rendering output is not byte-stable across versions or platforms.
Eliminar a comparação de bytes previne toda uma classe de testes instáveis que, de outra forma, custariam uma tarde a alguém.
Onde os problemas de renderização realmente residem?
Três das causas que o IronPDF documenta para diferenças entre navegador e PDF são uma folha de estilos escrita para mídia de tela em vez de impressão, uma fonte web que não foi carregada quando o layout foi calculado, e conteúdo produzido por JavaScript que foi capturado muito cedo. Nomear o sintoma e o arquivo obtém uma resposta muito mais útil do que colar o projeto inteiro.
@Templates/report.html @Services/ReportRenderer.cs Use the IronPDF docs at https://ironpdf.com/llms.txt.
The report renders correctly in Chrome but the PDF drops the logo and splits a
table row across pages. Explain the cause of each before changing anything,
then fix the table break in CSS and the logo in the renderer configuration.
Separar o diagnóstico da correção lhe dá algo para avaliar em vez de uma mudança para reverter. Neste caso, os dois problemas têm lares diferentes: o comportamento de quebra de página pertence à folha de estilo, coberto pelo guia de quebras de página, enquanto um logotipo que é resolvido em um navegador e não na renderização geralmente é uma questão de caminho base, porque uma string HTML bruta não carrega localização de documento para resolver URLs relativos.
Este é o relatório do site que o teste de execução renderizou após ambas as correções:
Falhas de implantação são onde o acesso ao terminal ganha seu lugar, já que a resposta geralmente reside no contêiner, não no código.
@Dockerfile Use the IronPDF docs at https://ironpdf.com/llms.txt.
Rendering works on Windows but fails in our Linux container with:
[PASTE FULL EXCEPTION AND STACK TRACE HERE]
Check for missing native dependencies IronPDF's Chromium engine needs on
Debian-based images. Explain the cause, then propose the Dockerfile change.
Don't modify C# code unless the cause is there.
A instrução para não tocar no código da aplicação é deliberada. Uma biblioteca compartilhada ausente em uma imagem não é um problema de C#, e um agente com mão livre às vezes envolverá a chamada em um try/catch que esconde a falha em vez de corrigi-la. O guia de implantação Docker documenta os requisitos atuais, que mudam entre versões.
O que os prompts produziram em uma execução real?
Sete das nove solicitações nesta página foram executadas em ordem em uma sessão do Cursor CLI, versão 2026.10.14-941492e. A edição em linha foi executada no aplicativo desktop do Cursor, versão 3.23.23. O projeto era uma pequena aplicação .NET 8 no IronPDF 2026.10.3 com todos os arquivos que as solicitações nomeiam e os defeitos que descrevem. As figuras abaixo são de renderizações independentes do código que o agente escreveu, não de suas respostas.
- O agente buscou 21 páginas de documentação do IronPDF diferentes durante a sessão, começando de llms.txt.
- Cada classe e membro nomeado na resposta do rodapé existia no IronPDF 2026.10.3, e todas as sete páginas que citou foram carregadas.
- O programa Quickstart escreveu um hello.pdf de uma página com 17.385 bytes com a chave definida e lançou uma LicensingException em SaveAs sem ela.
- A edição em linha adicionou uma margem superior de 25 mm, que é o padrão do IronPDF, e um rodapé centralizado que imprimiu "1 de 1".
- Antes da correção do rodapé, a linha Total devido foi impressa sobre a primeira linha do rodapé de uma fatura de uma página.
- A correção elevou a margem inferior em InvoiceRenderer.cs de 10 para 40 milímetros e deixou o modelo inalterado.
- Após a correção, nenhuma linha da fatura tocou o rodapé, e os totais se moveram para uma segunda página.
- A migração manteve todas as quatro assinaturas de métodos públicos, removeu PDFsharp e não adicionou pacote.
- O relatório migrado manteve duas páginas A4, as fontes Arial, a ordem das seções e o total regional.
- Duas renderizações do mesmo relatório migrado tinham o mesmo tamanho e bytes diferentes.
- Os testes xUnit passaram 4 de 4 com a chave e 0 de 4 sem ela.
- Antes da correção de renderização, o relatório do site mostrava o texto alternativo do logotipo e dividia sua última linha de tabela entre as páginas 1 e 2.
- A correção passou a pasta de modelo como caminho base, e uma regra de folha de estilos manteve cada linha de tabela junta.
- Após a correção, o logotipo apareceu na página 1 e a última linha se moveu inteira para a página 2.
- Em testes CLI, o arquivo de regras foi aplicado em 6 de 6 testes com globs separados por vírgulas e em 0 de 6 com uma lista YAML.
- Alguns passos foram executados de forma diferente da página. O CLI enviou cada menção @ como texto simples, e o agente abriu os arquivos nomeados com suas próprias ferramentas. Após o plano de migração, a sessão permaneceu em modo de plano, então as duas solicitações seguintes retornaram planos que uma mensagem de acompanhamento construiu. A suíte de testes foi executada como um agente local, porque agentes de nuvem precisam de um repositório hospedado. O prompt de edição em linha foi executado no aplicativo desktop do Cursor, que o registrou como um chat do Agente com a linha selecionada anexada. O prompt do Docker não foi executado porque a máquina de teste não tem ambiente Docker ou Linux.
O registro de execução no guia de assistentes de codificação de IA lista a ferramenta, o modelo e a duração de cada guia nesta série.
O que você deve configurar primeiro?
A fundação, antes de qualquer outra coisa. Conectar a documentação do IronPDF e comprometer uma regra de projeto com escopo leva cerca de quinze minutos, se aplica a cada prompt depois disso e é toda a diferença entre este fluxo de trabalho e colar perguntas em um assistente de chat geral. Tudo o que vem depois, as edições inline, as menções, o planejamento, os agentes, é uso comum de editor que acaba funcionando melhor quando a fundamentação está no lugar.
O hábito de verificação permanece o mesmo, independentemente de qual modelo está respondendo: compile cedo, abra o PDF e verifique os nomes de API em relação à documentação antes de qualquer coisa ser enviada. A versão reproduzível dessa verificação, executada do início ao fim com um resultado publicado, vive no guia de assistentes de codificação de IA, junto com os guias para ChatGPT Codex, GitHub Copilot, e Google Antigravity.
Solução de problemas
- Aplique uma chave de licença no IronPDF: se ao salvar o PDF lançar uma exceção de licenciamento
- Inicializando RenderingOptions Correto: se um nome de opção sugerido não resolver
- Qual versão do IronPDF deveria usar?: para fixar uma versão na sua regra de projeto
- Como executar o IronPDF em um contêiner Docker: se uma renderização funciona localmente e falha dentro de um contêiner
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.