Como Usar o IronPDF com o GitHub Copilot
A maioria dos guias de codificação assistida por IA assume que você está disposto a trocar de editores. Para trabalho em .NET, essa suposição frequentemente está errada. Projetos IronPDF que residem no Visual Studio estão dentro de soluções com referências de projeto, configuração NuGet e um pipeline de compilação que ninguém quer realocar apenas para experimentar um assistente.
O GitHub Copilot funciona onde esses projetos já estão, no Visual Studio, VS Code, e IDEs JetBrains, então esse fluxo de trabalho não precisa de migração. Ele também faz algo que um assistente apenas de editor não pode: ele roda dentro do próprio GitHub. Você pode descrever um problema com PDF em um problema, atribuí-lo ao agente de nuvem do Copilot e receber uma solicitação de pull. IronPDF renderiza HTML, CSS e JavaScript em PDF por meio de um mecanismo Chromium embutido, e não há integração entre os dois produtos. O que os conecta é o repositório e as convenções que você faz commit nele.
Uma distinção antes, porque dois tópicos similares competem. Este guia é sobre usar um assistente de codificação de IA para construir software com o IronPDF. Não é sobre usar modelos de IA para ler ou analisar conteúdo de PDF, o que o tutorial de processamento de PDF com IA cobre separadamente.
Início RápidoAbra a solução em qualquer IDE que já esteja e peça o documento:
In this C# console project, create Program.cs that uses IronPDF to render
"<h1>Hello from IronPDF</h1>" to hello.pdf. Read the license key from the
IRONPDF_LICENSE_KEY environment variable, never inline. Then build and fix
any errors.
Copilot escreve as poucas linhas que importam, construindo um ChromePdfRenderer, chamando RenderHtmlAsPdf, e salvando o resultado com SaveAs. Essa parte não é notável, e não é por isso que este guia existe. O que se segue é: o mesmo assistente fará este trabalho sem ninguém assistindo, em um branch, como um pull request, e isso muda o que você tem que configurar.
Duas notas de segurança, ambas breves. Uma chave de licença nunca pertence embutida em um prompt ou um commit; ele fica na configuração, como o guia de chave de licença descreve, ou em uma variável de ambiente ou um segredo de repositório. E um agente com acesso de escrita ao repositório abre pull requests reais, então proteção de branch e revisão humana continuam sendo o controle que importa.
Fluxo de trabalho mínimo (5 etapas)
- Baixe a biblioteca PDF C# do NuGet
- Faça commit de
.github/copilot-instructions.mdcom as convenções do IronPDF do projeto - Use chat inline para pequenas edições e modo de agente para trabalho multi-arquivo
- Para trabalho não supervisionado, abra um problema detalhado e atribua-o ao agente de nuvem
- Revise o pull request, verificando todos os nomes de API contra a referência de API.
Onde o Copilot se encaixa em um projeto já no Visual Studio?
O Copilot funciona em três alcances, e escolher o correto economiza mais tempo do que qualquer técnica de prompt.
Completações inline e chat lidam com qualquer coisa que você possa descrever em uma frase e que viva em um único arquivo: ajustar uma margem, adicionar um rodapé a uma chamada de renderizador existente, renomear um auxiliar. Você descreve a mudança, você recebe um diff no lugar, você aceita ou não.
Modo de agente lida com trabalho abrangendo vários arquivos, onde o Copilot decide quais arquivos editar, roda comandos de terminal, lê a saída e itera sobre erros. Este é o alcance certo para uma migração ou um refatoramento.
O agente de nuvem no GitHub lida com trabalhos que não precisam de supervisão alguma. Você atribui uma issue, ele planeja, envia um branch, e abre um pull request. Isso é o que faz o Copilot diferente de um assistente restrito ao editor, e é onde o restante deste guia concentra sua atenção.
O Copilot é também um leitor razoável. Pedir para que ele explique o tipo de opções de renderização e liste quais o projeto atualmente define transforma a referência de API em algo que você pode consultar ao invés de rolar.
Como você comete convenções que todas as superfícies seguem?
Instruções personalizadas do repositório são cometidas ao repositório, o que significa que elas governam o chat do IDE e o agente autônomo igualmente, incluindo quando o agente trabalha sem ninguém observando. Escreva-as uma vez, depois pare de se repetir em prompts.
O arquivo é .github/copilot-instructions.md. Para uma equipe .NET este é o formato que vale a pena padronizar, porque é o que o Visual Studio documenta ao carregar, junto com o VS Code, JetBrains, o agente de nuvem e a revisão de código do Copilot. Copilot lê outros arquivos de instrução também, AGENTS.md entre eles, mas o suporte varia por superfície de uma forma que muda de lançamento para lançamento, então o padrão mais seguro para uma loja Visual Studio é o arquivo nomeado após o produto.
# Copilot instructions
## PDF generation
- Use IronPDF for all PDF generation. Use ChromePdfRenderer for HTML 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 rather than guessing.
## Testing
- Assert on extracted text, page count and the %PDF- signature.
- Never use golden-file byte comparisons; rendering output is not byte-stable.
A linha sobre admitir incerteza merece seu lugar. O padrão de um modelo é produzir algo plausivelmente formatado em vez de admitir uma lacuna, e inventar renderer.ConvertHtmlToPdfDocument() funciona perfeitamente bem até que o compilador discorda. Dar permissão para parar é barato e funciona.
Instruções específicas de caminho em .github/instructions/**/*.instructions.md orientam para arquivos correspondentes, o que mantém as convenções de PDF fora de solicitações que não têm nada a ver com PDFs.
O que faz uma issue para que o agente realmente possa agir?
Aqui a habilidade que importa não é escrever prompts. É escrita de problemas, porque, de acordo com o GitHub, o agente trabalha com o título do problema, descrição e comentários existentes, e não vê comentários adicionados após a atribuição. Ninguém está presente para esclarecê-la.
Uma issue fraca se parece com isto:
Title: PDF looks wrong
The invoice PDF doesn't look right. Can we fix the layout?
O agente não tem arquivo para abrir, não sabe a qual de vários PDFs se refere, sem descrição do resultado correto e sem erro para trabalhar. Ele irá explorar, adivinhar e produzir um pull request que pode abordar completamente a coisa errada.
Uma issue forte contém tudo o que um colega necessitaria:
Title: Invoice PDF splits table rows across pages and drops the logo
**Files:** Services/InvoiceRenderer.cs, Templates/invoice.html
**IronPDF version:** as pinned in Directory.Packages.props
**Framework:** .NET 8
**Expected:** A4 portrait, 20mm margins. Line-item table rows stay intact
across page breaks. Company logo renders in the header.
**Actual:** A table row splits between pages 1 and 2. The logo area is blank
in the PDF but renders correctly when Templates/invoice.html is opened in
Chrome. No exception is thrown.
**Constraints:** Fix page-break behavior in CSS, not in C#. Keep the public
signature of InvoiceRenderer.RenderAsync unchanged. No new packages.
**Acceptance:** Existing tests pass, plus a new test asserting page count for
the fixture in TestData/invoice-12-items.json.
Seis coisas separam a segunda da primeira: arquivos nomeados, a versão do framework e da biblioteca, a saída esperada declarada concretamente, o comportamento real incluindo o que não acontece, restrições rígidas e uma definição de pronto.
Aquele detalhe sobre não lançar exceção está realmente fazendo trabalho. Ele diz ao agente que este é um problema de renderização ao invés de um crash, o que descarta uma categoria inteira de investigação antes de começar. A observação de que o logotipo é renderizado no Chrome mas não no PDF restringe ainda mais: uma string HTML bruta não carrega localização de documento, então caminhos de imagem relativos se resolvem contra o diretório de trabalho do processo em vez da pasta do template, enquanto um navegador sabe de onde a página veio.
Uma vez atribuído, o agente planeja, envia um branch, abre um pull request, e solicita revisão. Você revisa o diff ao invés de assistir ao trabalho.
Por que os testes do agente falham em um projeto IronPDF?
Esta é a seção que nenhum guia geral do Copilot irá escrever, e é aquela mais provável de lhe poupar uma tarde.
O agente de nuvem compila e testa em seu próprio ambiente efêmero. Para a maioria dos projetos, fonte mais um restaure de pacote é suficiente. Um projeto IronPDF precisa de mais, porque a renderização depende de um mecanismo Chromium com dependências de plataforma nativas. Se essas estão ausentes do executor Linux do agente, cada teste que renderiza um PDF falhará, por razões que não têm nada a ver com o código que o agente acabou de escrever.
A consequência é pior do que um build vermelho. Deixado para encontrar e instalar dependências ausentes por conta própria, o agente trabalha por tentativa e erro, o que a documentação do GitHub chama de lento e pouco confiável.
A correção é pré-configurar o ambiente com .github/workflows/copilot-setup-steps.yml. Parece um fluxo de trabalho comum do GitHub Actions com duas regras fáceis de esquecer: o trabalho deve ser nomeado copilot-setup-steps, e o arquivo não será acionado a menos que exista na branch padrão do seu repositório.
name: "Copilot Setup Steps"
on:
workflow_dispatch:
push:
paths:
- .github/workflows/copilot-setup-steps.yml
pull_request:
paths:
- .github/workflows/copilot-setup-steps.yml
jobs:
# The job MUST be called `copilot-setup-steps` or Copilot will not pick it up.
copilot-setup-steps:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@v4
- uses: actions/setup-dotnet@v4
with:
dotnet-version: '8.0.x'
# Install the native dependencies IronPDF's Chromium engine needs on
# Debian-based images. Take the current package list from the Docker
# and Linux deployment guide rather than copying one from anywhere else,
# because it changes between releases.
- name: Install IronPDF native dependencies
run: |
sudo apt-get update
sudo apt-get install -y <packages from the IronPDF Linux guide>
- run: dotnet restore
Dois detalhes decidem se isso funciona.
Primeiro, uma chave de licença não está automaticamente disponível para o agente. GitHub Actions, Codespaces e segredos Dependabot não estão disponíveis para uma sessão de agente, então a chave precisa ser adicionada separadamente como um segredo do agente nas configurações do repositório ou da organização.
Segundo, e este é o que produz o sintoma confuso: se um passo de configuração falhar, o Copilot não para. Ele pula os passos restantes e começa a trabalhar com qualquer estado em que o ambiente estiver. Uma instalação de dependência que falha silenciosamente, portanto, parece exatamente um problema de código. Execute o fluxo de trabalho manualmente na aba Ações uma vez antes de confiar nele.
O que você deve verificar antes de fazer o merge?
O pull request é a superfície de revisão, e os mesmos padrões se aplicam como a qualquer branch de um colega. A própria revisão de código do Copilot pode ser uma segunda passada sobre a saída do agente, que detecta problemas mecânicos antes que um humano leia o diff.
Três verificações são importantes especificamente para mudanças do IronPDF:
- Todo nome de API aparece na documentação, ou algo plausível passou despercebido?
- O PDF gerado realmente parece certo? Uma compilação limpa não diz nada sobre o layout.
- A alteração permaneceu dentro das restrições definidas pelo problema?
Solicitar testes no mesmo pull request vale a pena tornar padrão:
Add xUnit tests for this change: output is non-empty, begins with the %PDF-
signature, extracted text contains the bound company name, and page count
matches the fixture. No golden-file byte comparisons.
Excluir a comparação de bytes evita uma classe de teste instável que, caso contrário, custaria uma tarde, já que duas renderizações do mesmo HTML em processos distintos diferem em seus timestamps e ID de documento.
Quando é o código, e quando é o contêiner?
Três causas documentadas de diferenças de renderização entre navegador e PDF são uma folha de estilo escrita para mídia de tela em vez de impressão, uma fonte web que não havia sido carregada ao calcular o layout, e conteúdo produzido por JavaScript que foi capturado muito cedo. Todos os três são do lado do código, e todos os três valem a pena ser nomeados na solicitação:
Templates/report.html renders correctly in Chrome but the PDF splits a table
row across pages and the totals block lands on the next page alone.
Explain the cause before changing anything, then fix it in the CSS using page
break properties. Do not modify ReportRenderer.cs.
Pedir um diagnóstico antes de uma mudança dá a você algo para avaliar ao invés de uma correção para engenharia reversa. O comportamento de quebra de página pertence à folha de estilos, e o guia de quebras de página cobre as propriedades relevantes. Limitar a mudança ao CSS evita que um agente resolva um problema de layout reestruturando o C#.
A outra metade da questão é aquela que a seção anterior respondeu: quando o mesmo código renderiza localmente e falha em um contêiner ou em um executor, geralmente não é o código de fato. Cole o erro completo ao invés de paráfraseá-lo, e aponte a solicitação para o Dockerfile ao invés do aplicativo. Uma biblioteca compartilhada ausente não é um problema de C#.
O que os prompts produziram em uma execução real?
Os três prompts e os dois corpos de problema nesta página rodaram em ordem, sem supervisão, com GitHub Copilot CLI 1.0.95, que roteou cada vez para o GPT-6 Luna. O arquivo de instruções e o fluxo de trabalho de etapas de configuração foram cometidos conforme escritos. As figuras abaixo provêm de verificações independentes dos arquivos que a execução deixou para trás.
- O prompt de início rápido produziu um Program.cs de 13 linhas que leu a chave de IRONPDF_LICENSE_KEY e compilou sem erros ou avisos.
- O agente não executou o programa.
- Executado com a chave, o programa salvou um hello.pdf de uma página com 17.385 bytes.
- Antes que os problemas fossem executados, a fatura dividia um item em linha entre as páginas 1 e 2 e não continha imagem.
- O problema forte produziu uma fatura de duas páginas com todos os itens de linha inteiros e o logotipo na página 1.
- O agente incorporou o logotipo como uma URI de dados em C# e corrigiu as quebras de página no CSS.
- A assinatura pública de InvoiceRenderer.RenderAsync permaneceu inalterada, e nenhum pacote foi adicionado.
- O novo teste afirmou duas páginas para o conjunto de 12 itens, e todos os 3 testes passaram.
- O agente adicionou uma regra para repetir o cabeçalho da tabela e relatou que ele repetiu. A página 2 da fatura renderizada não continha linha de cabeçalho.
- O problema fraco também corrigiu ambos os defeitos, embora não tenha nomeado nenhum arquivo ou sintoma específico.
- A mesma alteração reescreveu toda a folha de estilo e reduziu o texto do corpo de 13 para 11 pixels.
- O prompt de testes adicionou uma verificação de não-vazio e uma verificação de nome de empresa aos testes existentes, então o número permaneceu em 3, e nenhum comparou bytes.
- O prompt do relatório nomeou a quebra de página forçada antes dos totais e a regra de linha ausente como as causas antes de editar o CSS.
- O relatório corrigido se ajustou em 2 páginas em vez de 3, sem linha dividida e os totais abaixo dos últimos quatro sites. ReportRenderer.cs permaneceu inalterado.
- O agente nunca listou variáveis de ambiente, e a chave não apareceu em nenhuma transcrição, commit ou arquivo de sessão do Copilot.
- Alguns passos foram executados de forma diferente da página. O repositório não tinha um remoto do GitHub, então o CLI substituiu o agente de nuvem e cada problema iniciou uma nova sessão. A solicitação de testes foi para a sessão do problema forte em vez de um comentário da solicitação de pull. O fluxo de trabalho de etapas de configuração não foi executado, porque esta máquina não tem um executor do GitHub Actions nem um ambiente Linux.
A fatura após o problema forte, renderizada pelo InvoiceRenderer da execução a partir do conjunto de 12 itens.
O relatório após a correção de CSS do prompt de relatório, renderizado pelo ReportRenderer da execução.
A versão do CLI do Copilot, modelo e tempo para esta execução estão listados no registro da execução.
O que continua funcionando quando ninguém está assistindo?
Duas coisas, e são as duas que valem a pena configurar primeiro. Instruções cometidas em .github/copilot-instructions.md governam o agente em uma branch à meia-noite exatamente como governam seu IDE ao meio-dia. Um copilot-setup-steps.yml que instala as dependências nativas do IronPDF é o que poupa esse mesmo agente de encontrá-las e instalá-las por tentativa e erro. Todo o resto é uso ordinário de assistente que funciona melhor depois que esses dois existem.
O hábito de verificação não muda com o alcance: construa cedo, abra o PDF e verifique os nomes de API contra a documentação antes que qualquer coisa seja 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 aos guias para Claude Code, ChatGPT Codex e Cursor.
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 devo usar?: para fixar uma versão no seu arquivo de instruções
- Como executar o IronPDF em um contêiner Docker: para as dependências nativas que o executor do agente precisa
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.