Como usar IronPPT com GitHub Copilot
Uma agência imobiliária envia aos agentes compradores um conjunto de apresentações de suas casas abertas toda sexta-feira. Cada anúncio de propriedade recebe um slide com até três fotos, e as fotos chegam de telefones e câmeras em diferentes tamanhos, formatos e resoluções. Um serviço .NET no repositório da agência cria o conjunto, então qualquer assistente que modifica esse serviço deve colocar cada foto dentro de sua moldura sem distorcê-la.
GitHub Copilot acessa o repositório através do chat e do modo agente no Visual Studio e VS Code, através do Copilot CLI em um terminal, e através de um agente em nuvem no GitHub que transforma uma issue atribuída em um pull request. IronPPT cria e edita arquivos PowerPoint em .NET sem o Microsoft Office. AddImage coloca uma imagem em um slide, e a classe Image dimensiona, substitui e remove. Arquivos de instrução comprometidos com o repositório fornecem a cada uma dessas superfícies as regras do IronPPT.
Este guia aborda como direcionar o Copilot para construir software que posiciona fotos com IronPPT. Tirar as fotos e projetar o modelo do slide são tarefas separadas que ocorrem fora do repositório. O guia de gerenciamento de imagem descreve as chamadas do IronPPT das quais o conjunto listado depende.
Início RápidoAbra um terminal na raiz do repositório, inicie o Copilot CLI e envie o prompt. O Copilot CLI anexa um arquivo com @, enquanto o Copilot Chat no Visual Studio usa referências #.
Fill in @src/Listings.Deck/ListingDeck.cs so the agency can build its weekly open-homes deck.
The repo already pins IronPPT 2026.10.1 in Directory.Packages.props.
Here is what the deck code needs:
- One public static method, Build(string listingsPath, string photosDir, string outPath).
- Listings come from @data/listings.json.
- Each listing's photos are in photos/<listing id>/, under the file names the JSON gives.
- The cover and every listing slide follow @docs/listing-layout.md.
Then do these in order:
1. Add a build command with an --out <path> option to @src/Listings.Cli/Program.cs.
2. Build the solution.
3. From the repo root, run the CLI with build --out out/listings.pptx.
Tell me how many slides the deck has and how large the file is.
O prompt não nomeia caixa ou coordenada, pois docs/listing-layout.md define as caixas de fotos em pontos e a ordem das linhas de texto.
Defina IRONPPT_LICENSE_KEY no ambiente onde o Copilot é executado. O IronPPT não lê esse nome por si só. No nosso teste, License.IsLicensed permaneceu falso quando apenas essa variável foi definida. O IronPPT leu variáveis chamadas IronPPT.LicenseKey e IRONPPT_LICENSEKEY por conta própria, mas o repositório de exemplo copia o nome convencional para License.LicenseKey. O guia de chave de licença lista os outros locais suportados.
Fluxo de trabalho mínimo (5 etapas)
- Baixar a biblioteca PowerPoint C# do NuGet
- Escreva as regras do IronPPT em .github/copilot-instructions.md mais um arquivo de instruções específico do caminho.
- Dê a cada foto uma Largura, Altura e Posição calculadas com base no tamanho dos pixels da foto.
- Substitua uma foto em um conjunto salvo através da lista de Imagens do documento, depois defina sua moldura novamente.
- Atribua a próxima alteração ao agente em nuvem como uma issue e verifique o pull request contra a referência de API do IronPPT.
Como você define as convenções do IronPPT para o Copilot?
Coloque as regras abrangentes do projeto em .github/copilot-instructions.md. A referência de suporte do GitHub lista esse arquivo para Copilot Chat no Visual Studio, VS Code e nos IDEs JetBrains, e para o agente em nuvem e revisão de código do Copilot. O Copilot CLI lê do mesmo local. O Visual Studio carrega enquanto a opção de instruções personalizadas está selecionada, e essa opção está ativada por padrão.
This repo builds the weekly open-homes deck with IronPPT. These rules apply to all of it:
- Use IronPPT, the NuGet package and namespace. Don't add another presentation or Open XML package.
- Edit the IronPPT entry in Directory.Packages.props only when the task is an IronPPT upgrade.
- Give other packages their versions in Directory.Packages.props as well.
- The code reads IRONPPT_LICENSE_KEY itself, because IronPPT doesn't look at that name.
- Copy the key into License.LicenseKey before the code saves a deck.
- Never print the key, and never list environment variables.
- docs/listing-layout.md is the contract.
- If the layout doc looks wrong, say so in your reply and leave the file as it is.
- The IronPPT docs index for agents is https://ironsoftware.com/ppt/csharp/llms.txt
Tests follow two more rules:
- A test saves a deck, reopens it and checks its pictures and text.
- Never compare the bytes of two decks.
IronPPT nomeia cada foto com um número aleatório, como Foto 86115, portanto duas compilações dos mesmos anúncios diferiram byte por byte. Os testes comparam fotos e textos por esse motivo.
Como você dá ao código do conjunto suas próprias regras?
Um arquivo como .github/instructions/deck.instructions.md contém regras para as partes da árvore que seus padrões applyTo nomeiam, aqui os projetos de origem e teste. De acordo com a documentação do GitHub, o Copilot CLI inclui o arquivo somente quando trabalha em um arquivo que corresponde a um desses padrões. Na execução do teste, o Copilot abriu este arquivo antes de qualquer outro arquivo no primeiro prompt e na sessão separada da issue.
---
applyTo: "src/**,tests/**"
---
These rules cover IronPPT pictures and slides in the deck code and its tests:
- Every new PresentationDocument already has a slide. Make the cover from that slide.
- Don't add another slide in front of the cover.
- Give every picture an explicit Width, Height and Position, in points.
- Without them, IronPPT sizes a photo from its pixels and DPI.
- At 72 dpi, a 4032 x 3024 photo comes out 56 x 42 inches.
- The default slide is 10 x 7.5 inches.
- Setting Width leaves Height as it was, and the reverse.
- Work out both from the photo's pixel size to keep its aspect ratio.
- On a deck loaded from a file, call Replace on document.Images, not on a slide's Images list.
- Replace resets the picture to the new photo's own size.
- So set Width, Height and Position again after each Replace.
- Width, Height and Position read from a reopened deck are 12,700 times the value in points.
- AddImage with an AnyBitmap stores the picture as an uncompressed BMP.
- To store a resized photo as a JPEG, encode it first and pass the stream.
Cada regra nesse arquivo vem de um teste do IronPPT 2026.10.1.
Quão grande o IronPPT faz uma foto de listagem?
AddImage sem um tamanho fornece à foto uma moldura com a contagem de pixels da foto dividida por seu DPI, em polegadas, e não escreve posição para ela. O slide padrão é de 10 por 7,5 polegadas, que é 720 por 540 pontos.
- Uma foto de telefone de 4032 por 3024 salva a 72 dpi recebeu uma moldura de 56 por 42 polegadas.
- A mesma foto de 2048 por 1536 salva a 300, 72 e 96 dpi recebeu molduras de 6,8, 28,4 e 21,3 polegadas de largura. Um PNG sem DPI foi dimensionado como 96 dpi.
- Um JPEG com densidade de 1 por 1 e sem unidade em seu cabeçalho foi dimensionado como 1 dpi, então uma foto de 4032 pixels tornou-se 4032 polegadas de largura.
- Largura, Altura e Posição são em pontos. Definir a Largura para 400 sozinho deixou a Altura inalterada, então a moldura perdeu a proporção da foto.
O ajuste em docs/listing-layout.md, portanto, começa a partir do tamanho dos pixels da foto. O fator de escala é o menor entre a largura da caixa dividida pela largura da foto e a altura da caixa dividida pela altura da foto, e a moldura escalonada é centralizada na caixa.
Como trocar uma foto em um conjunto salvo?
Swap the hero photo of L-1044 in out/listings.pptx for photos/reshoot/L-1044-front.jpg.
The photographer reshot the front, and the new photo is portrait.
Change the saved deck itself. Don't rebuild it from the JSON.
Add the swap to the CLI as a swap command with these options:
- --deck <path> names the deck to change.
- --listing <id> and --photo <n> pick the picture, counting photos from 1.
- --file <path> is the new photo.
The new photo goes in the hero box and follows the fit rules in docs/listing-layout.md.
Leave every other picture and all the text as they are.
Run the command, reopen the deck and show me the hero's position and size in points.
Replace deu três resultados diferentes nos testes.
- Em um conjunto construído na memória, Replace trocou a foto e redefiniu a moldura para o próprio tamanho da nova foto, sem posição.
- Em um conjunto carregado, Replace chamado através da lista
Imagesde um slide não alterou a foto solicitada em nenhum teste. Um slide com uma foto manteve a foto antiga e armazenou a nova foto no arquivo sem uso. Em um slide com duas fotos, a chamada na primeira foto trocou a segunda. - Através de
document.Images, Replace em um conjunto carregado trocou a foto correta. Definir Largura, Altura e Posição após a chamada deu à moldura o tamanho e lugar corretos.
O exemplo de troca do guia de gerenciamento de imagem chama Replace através de Slides[0].Images[0] em um conjunto carregado, que é o caminho que deixou a foto antiga no lugar.
Saída
A execução do teste salvou o slide para 220 Mill Road antes e depois da troca.

Slide 4 como o primeiro prompt salvou, com cada foto desenhada em sua posição e tamanho armazenados. O texto não é desenhado, e as fotos são imagens de teste geradas.

Slide 4 após o comando de troca, desenhado da mesma forma.
Como testar o conjunto?
Use Shift+Tab para alternar o Copilot CLI para o modo plano, então envie este prompt.
Plan an xUnit project at tests/Listings.Deck.Tests, and put it in the solution.
Show me the plan first, and hold the code until I say go.
Each test builds a deck from data/listings.json in a temp folder and checks one of these:
- The deck has a cover plus one slide per listing, in the order of the JSON.
- Each listing slide holds one picture per photo, in the box the layout doc gives that photo.
- Every picture keeps its photo's aspect ratio within 0.5% and stays inside its box.
- The address, the price and the bed and bath line are on the right slide.
- The swap command changes the chosen picture and no other.
Once I say go, write the tests and keep running dotnet test until they pass.
Then tell me how many tests passed.
Um teste das caixas deve ler tamanhos que o IronPPT relata erroneamente. Largura, Altura e Posição lidos de um conjunto reaberto retornam 12.700 vezes seus valores em pontos, que é o valor em EMUs, a unidade que o arquivo PPTX armazena. Uma moldura de 480 pontos lida como 6.096.000. Os testes da execução dividiram os valores lidos por 12.700 antes de compará-los com o layout.
Por que marcar uma listagem como vendida deixa as fotos para trás?
Neste cenário, um colega do SoldUpdate.cs remove as fotos de uma listagem vendida em um loop.
Find out why marking a listing sold leaves photos behind, then fix it.
@src/Listings.Deck/SoldUpdate.cs edits a saved deck.
It should strip the listing's photos from its slide and add a SOLD line.
Work through these steps before you touch SoldUpdate.cs:
1. Write a test that builds a deck, marks L-1042 sold and counts the pictures left on its slide.
2. Read how https://ironsoftware.com/ppt/csharp/how-to/manage-image/ removes all images.
3. Tell me what Slide.Images returns in IronPPT that explains the leftover photos.
The fix has to meet these conditions:
- It changes SoldUpdate.cs and no other source file.
- The new test expects no pictures on the slide.
- dotnet test passes.
Last, mark L-1042 sold in a copy of out/listings.pptx.
Tell me the copy's size before and after.
Slide.Images constrói uma nova lista a cada acesso. Um loop que lê slide.Images novamente em cada passagem, com um índice que conta para cima, pula uma foto após cada remoção. Em um slide com quatro fotos, ele removeu duas, e em um slide de listagem com três, ele removeu duas e deixou uma. Um loop que conta para baixo, como o exemplo de remoção do guia de gerenciamento de imagem faz, removeu todas as fotos, e também um foreach sobre uma cópia da lista.
A remoção também deixa os bytes da foto no arquivo. Remover quatro fotos de um conjunto de 13.766.065 bytes salvou um arquivo de 13.765.502 bytes.
O que faz de um problema algo que o agente de nuvem pode atuar?
Quando uma issue é atribuída ao Copilot, o GitHub passa ao agente o título da issue, sua descrição, os comentários que existem naquele momento e quaisquer instruções dadas na atribuição. Comentários adicionados posteriormente não chegam ao agente, então o corpo da issue deve conter todo o pedido.
Title: Shrink the weekly deck so it can be emailed
Files: src/Listings.Deck/ListingDeck.cs and tests/Listings.Deck.Tests
Versions: IronPPT 2026.10.1 on net9.0
Expected: out/listings.pptx is under 4 MB, and the deck code works like this:
- IronPPT gets a scaled copy of any photo wider or taller than 1600 pixels.
- The copy is 1600 pixels on its long side and is stored as a JPEG at quality 85.
- Every picture keeps the box, position and size it has now.
Actual: IronPPT stores each photo file as it is, so the deck is over 15 MB.
Constraints: the change stays inside these limits:
- Keep the Build signature.
- Follow .github/instructions/deck.instructions.md.
- Add no packages.
- Leave the files in photos/ untouched.
Acceptance: the issue is done when all of this holds:
- The existing tests pass.
- A new test builds the deck and opens each photo stored under ppt/media in the saved file.
- That test fails if any stored photo is over the 1600-pixel limit.
Summary: give the deck's size before and after the change.
IronPPT copia cada arquivo de foto para o conjunto byte por byte, e uma foto adicionada três vezes é armazenada três vezes. Uma foto escalonada passada para AddImage como um AnyBitmap foi armazenada como um BMP descompactado de 7.680.122 bytes para 1600 por 1200 pixels. Os mesmos pixels codificados como um JPEG em qualidade 85 e passados como um fluxo foram armazenados como 337.813 bytes.
Por que os testes do agente em nuvem falham em um projeto IronPPT?
O agente em nuvem é executado no Ubuntu Linux, a menos que o repositório escolha o contrário. O IronPPT tem como alvo o .NET Standard 2.0, e nenhum dos pacotes que ele restaura contém um arquivo nativo, então os passos de instalação não instalam nada além do SDK do .NET.
O executor também não tem chave de licença. Sem uma, o IronPPT construiu conjuntos na memória e leu conjuntos salvos, mas Save lançou uma exceção de licenciamento e não escreveu um arquivo. Portanto, cada teste que salva um conjunto falha no executor.
O GitHub executa o job copilot-setup-steps em .github/workflows/copilot-setup-steps.yml antes de o agente começar, e somente quando o arquivo está no branch padrão. Quando um passo de configuração falha, o Copilot pula os passos seguintes.
Add a workflow at .github/workflows/copilot-setup-steps.yml to prepare the cloud agent's machine.
GitHub reads only a job named copilot-setup-steps from that file.
Set the job up this way:
- It runs on ubuntu-latest with contents: read as its one permission.
- It triggers on workflow_dispatch and on any pull request that edits this file.
Give it these steps, in order:
1. Check out the repo.
2. Set up .NET 9.
3. Run dotnet restore.
4. Run dotnet build -c Release.
5. Check for the license key.
IRONPPT_LICENSE_KEY is an Agents secret.
GitHub's docs say copilot-setup-steps.yml can use Agents secrets.
The key check handles a missing key in two ways:
- A pull_request or workflow_dispatch run gets a warning, and the step still succeeds.
- Any other run fails, and the error names the missing secret.
Write the file and print the YAML for me.
Then tell me how the key check reads the key, and cite the GitHub page you followed.
Coloque a chave nos segredos dos Agentes: de acordo com o GitHub, o agente em nuvem não tem acesso aos segredos de Actions, Codespaces ou Dependabot. Nas Configurações do repositório, abra Segredos e variáveis na seção de Segurança, selecione Agentes e adicione IRONPPT_LICENSE_KEY na aba Segredos. A documentação do GitHub não fornece exemplo de uma etapa de configuração que lê um segredo de Agentes.
O que você deve verificar antes de fazer o merge?
Execute a revisão como um comando copilot -p separado, fora da sessão que escreveu o código.
/review this branch against main.
Compare the code with these three sources and list each spot where they disagree:
- the rules in .github/copilot-instructions.md
- the rules in .github/instructions/deck.instructions.md
- IronPPT.xml, which ships inside the IronPPT package in the NuGet cache
Also check for two patterns that no rule file covers:
- a loop that removes pictures while its index counts up
- a line that prints the message of a licensing exception
Tell me what you find, and say so if nothing turns up. Don't change any file.
O que os prompts produziram em uma execução real?
Os sete prompts foram executados sem acompanhamento no Copilot CLI contra um repositório de listagem construído para este guia. Uma verificação separada leu cada valor abaixo dos conjuntos salvos e do repositório.
- Antes da execução, ListingDeck era uma classe vazia e o CLI imprimiu uma linha de uso e saiu com código 1.
- Após o primeiro prompt, o conjunto continha uma capa e quatro slides de listagem, 15.150.897 bytes no total.
- Todas as 10 fotos estavam dentro de suas caixas sem erro mensurável na proporção, tamanho ou centralização.
- A troca substituiu o herói do 220 Mill Road através de document.Images.
- A nova foto em retrato mediu 243 por 324 pontos, centralizada na caixa de herói.
- Nenhuma das outras nove fotos ou o texto dos slides mudaram na troca.
- No modo plano, o Copilot escreveu um plano, não alterou nenhum arquivo e aguardou a mensagem de aprovação.
- A correção inverteu o loop em SoldUpdate.cs.
- Marcar 18 Alder Court como vendido então não deixou foto em seu slide.
- O Copilot atribuiu as fotos restantes a entradas deslocando-se dentro de uma lista e não mencionou que cada leitura de Slide.Images constrói uma nova lista.
- Três fotos removidas, 6.469.676 bytes no total, permaneceram na cópia vendida.
- A sessão da issue escalou nove fotos para 1600 pixels no lado maior com SixLabors.ImageSharp, que o IronPPT já incorpora, e não adicionou nenhum pacote.
- O conjunto reconstruído mediu 1.198.644 bytes.
- Cada foto manteve seu tamanho e posição.
- Com a chave configurada, todos os sete testes passaram. Sem ela, todos os sete falharam com a exceção de licenciamento.
- A sessão de revisão comparou o branch com o main, não relatou desacordo e não alterou nenhum arquivo.
- Alguns passos foram executados de forma diferente da página. O corpo da issue foi para uma nova sessão do Copilot CLI, porque o repositório de teste não tem um remoto GitHub. O fluxo de configuração foi escrito, mas não executado, pelo mesmo motivo.
Cursor também aplica arquivos de regras comprometidos a caminhos correspondentes, e Claude Code também mantém seu plano para aprovação antes de editar o código. O registro de execução compartilhado lista a versão do Copilot CLI, o modelo Auto selecionado, a duração e a máquina de teste.
Solução de problemas
- Como Gerenciar Imagens no PowerPoint para adicionar fotos e para o loop de remoção que conta para baixo.
- Como Adicionar Slides para o slide padrão que uma nova apresentação já possui.
- Aplicando Chaves de Licença para uma salvaguarda que lança uma exceção de licenciamento.
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.