Cómo usar IronPPT con GitHub Copilot
Una agencia inmobiliaria envía a los agentes compradores un conjunto de sus casas abiertas cada viernes. Cada listado de propiedades recibe una diapositiva con hasta tres fotos, y las fotos llegan de teléfonos y cámaras en diferentes tamaños, formas y resoluciones. Un servicio .NET en el repositorio de la agencia construye el conjunto, por lo que cualquier asistente que modifique ese servicio debe colocar cada foto dentro de su marco sin distorsionarla.
GitHub Copilot accede al repositorio a través del chat y modo de agente en Visual Studio y VS Code, a través de Copilot CLI en un terminal, y a través de un agente en la nube en GitHub que convierte un problema asignado en una solicitud de extracción. IronPPT crea y edita archivos de PowerPoint en .NET sin Microsoft Office. AddImage coloca una imagen en una diapositiva, y la clase Image la dimensiona, reemplaza y elimina. Los archivos de instrucciones comprometidos en el repositorio dan a cada una de esas superficies las reglas de IronPPT.
Esta guía cubre cómo dirigir a Copilot para construir software que coloque fotos con IronPPT. Tomar las fotos y diseñar la plantilla de la diapositiva son tareas separadas que ocurren fuera del repositorio. La guía de gestión de imágenes describe las llamadas de IronPPT de las que depende el conjunto de listados.
Inicio rápidoAbre un terminal en la raíz del repositorio, inicia Copilot CLI y envía el aviso. Copilot CLI adjunta un archivo con @, mientras que Copilot Chat en Visual Studio usa referencias #.
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.
El aviso no nombra caja o coordenada, porque docs/listing-layout.md define las cajas de fotos en puntos y el orden de las líneas de texto.
Configura IRONPPT_LICENSE_KEY en el entorno donde se ejecuta Copilot. IronPPT no lee ese nombre por sí solo. En nuestra prueba, License.IsLicensed permaneció falso cuando solo se configuró esa variable. IronPPT sí leyó variables nombradas IronPPT.LicenseKey y IRONPPT_LICENSEKEY por sí mismo, pero el repositorio de ejemplo copia el nombre convencional en License.LicenseKey. La guía de clave de licencia enumera las otras ubicaciones compatibles.
Flujo de trabajo mínimo (5 pasos)
- Descarga la biblioteca de PowerPoint de C# desde NuGet
- Escribe las reglas de IronPPT en .github/copilot-instructions.md más un archivo de instrucciones específico para la ruta
- Dale a cada imagen un Ancho, Altura y Posición calculados a partir del tamaño en píxeles de la foto
- Reemplaza una foto en un conjunto guardado a través de la lista de Imágenes del documento, luego configura su marco nuevamente
- Asigna el próximo cambio al agente en la nube como un problema y verifica la solicitud de extracción contra la referencia de API de IronPPT
¿Cómo se configuran las convenciones de IronPPT para Copilot?
Coloca las reglas del proyecto en .github/copilot-instructions.md. La referencia de soporte de GitHub lista ese archivo para Copilot Chat en Visual Studio, VS Code y las IDE de JetBrains, y para el agente en la nube y la revisión de código de Copilot. Copilot CLI lo lee desde la misma ubicación. Visual Studio lo carga mientras su opción de instrucciones personalizadas está seleccionada, y esa opción está activada por defecto.
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 nombra cada imagen con un número aleatorio, como Imagen 86115, por lo que dos construcciones de los mismos listados diferían byte por byte. Las pruebas comparan imágenes y texto por ese motivo.
¿Cómo se le da al código del conjunto sus propias reglas?
Un archivo como .github/instructions/deck.instructions.md contiene reglas para las partes del árbol que sus patrones applyTo nombran, aquí los proyectos de origen y prueba. Según la documentación de GitHub, Copilot CLI incluye el archivo solo cuando trabaja en un archivo que coincide con uno de esos patrones. En la ejecución de prueba, Copilot abrió este archivo antes que cualquier otro archivo en el primer aviso y en la sesión separada del problema.
---
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 regla en ese archivo proviene de una prueba de IronPPT 2026.10.1.
¿Qué tan grande hace IronPPT una foto de listado?
AddImage sin un tamaño le da a la imagen un marco del conteo de píxeles de la foto dividido por su DPI, en pulgadas, y no escribe posición para ella. La diapositiva predeterminada es de 10 por 7.5 pulgadas, que equivale a 720 por 540 puntos.
- Una foto de teléfono 4032 por 3024 guardada a 72 dpi recibió un marco de 56 por 42 pulgadas.
- La misma foto 2048 por 1536 guardada a 300, 72 y 96 dpi recibió marcos de 6,8, 28,4 y 21,3 pulgadas de ancho. Un PNG sin DPI se dimensionó a 96 dpi.
- Un JPEG con una densidad de 1 por 1 y sin unidad en su encabezado se dimensionó a 1 dpi, por lo que una foto de 4032 píxeles se convirtió en 4032 pulgadas de ancho.
- Ancho, Altura y Posición toman puntos. Establecer el Ancho en 400 solo dejó la Altura sin cambios, por lo que el marco perdió la proporción de aspecto de la foto.
Por lo tanto, el ajuste en docs/listing-layout.md comienza desde el tamaño en píxeles de la foto. El factor de escala es el menor entre el ancho de la caja dividido por el ancho de la foto y la altura de la caja dividida por la altura de la foto, y el marco escalado está centrado en la caja.
¿Cómo se intercambia una foto en un conjunto guardado?
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 dio tres resultados diferentes en las pruebas.
- En un conjunto construido en memoria, Reemplazar intercambió la foto y restableció el marco al tamaño propio de la nueva foto, sin posición.
- En un conjunto cargado, Reemplazar llamado a través de la lista
Imagesde una diapositiva no cambió la imagen solicitada en ninguna prueba. Una diapositiva con una foto mantuvo la foto antigua y almacenó la nueva foto en el archivo sin usar. En una diapositiva con dos fotos, la llamada en la primera foto intercambió la segunda. - A través de
document.Images, Reemplazar en un conjunto cargado intercambió la imagen correcta. Configurar Ancho, Altura y Posición después de la llamada le dio al marco el tamaño y lugar correctos.
El ejemplo de reemplazo de la guía de gestión de imágenes llama a Reemplazar a través de Slides[0].Images[0] en un conjunto cargado, que es la ruta que dejó la foto antigua en su lugar.
Resultado
La ejecución de prueba guardó la diapositiva para 220 Mill Road antes y después del intercambio.

La Diapositiva 4 como el primer aviso la guardó, con cada imagen dibujada en su posición y tamaño almacenados. El texto no está dibujado, y las fotos son imágenes de prueba generadas.

Diapositiva 4 después del comando de intercambio, dibujada de la misma manera.
¿Cómo se prueba el conjunto?
Usa Shift+Tab para ciclar Copilot CLI al modo de planificación, luego envía este aviso.
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.
Una prueba de las cajas tiene que leer tamaños que IronPPT informa incorrectamente. Ancho, Altura y Posición leídos de un conjunto reabierto devuelven 12,700 veces su valor en puntos, que es el valor en EMUs, la unidad que almacena el archivo PPTX. Un marco de 480 puntos leído de regreso como 6,096,000. Las pruebas de la ejecución dividieron los valores leídos por 12,700 antes de compararlos con el diseño.
¿Por qué marcar un listado como vendido deja fotos atrás?
En este escenario, el SoldUpdate.cs de un compañero elimina las fotos de un listado vendido en un bucle.
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 construye una nueva lista en cada acceso. Un bucle que lee slide.Images nuevamente en cada pasada, con un índice que cuenta hacia arriba, omite una imagen después de cada eliminación. En una diapositiva con cuatro imágenes eliminó dos, y en una diapositiva de listado con tres eliminó dos y dejó una. Un bucle que cuenta hacia abajo, como lo hace el ejemplo de eliminar-todo de la guía de gestión de imágenes, eliminó cada imagen, y también lo hizo un foreach sobre una copia de la lista.
La eliminación también deja los bytes de la foto en el archivo. Al eliminar cuatro fotos de un conjunto de 13,766,065 bytes se guardó un archivo de 13,765,502 bytes.
¿Qué hace que un problema sea en el que el agente de la nube pueda actuar?
Cuando se asigna un problema a Copilot, GitHub pasa al agente el título del problema, su descripción, los comentarios que existen en ese momento y cualquier instrucción dada al asignar. Los comentarios agregados más tarde no llegan al agente, por lo que el cuerpo del problema debe contener toda la solicitud.
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 archivo de foto en el conjunto byte por byte, y una foto añadida tres veces se almacena tres veces. Una foto escalada pasada a AddImage como AnyBitmap se almacenó como un BMP sin comprimir de 7,680,122 bytes para 1600 por 1200 píxeles. Los mismos píxeles codificados como un JPEG a calidad 85 y pasados como un flujo se almacenaron como 337,813 bytes.
¿Por qué fallan las pruebas del agente en la nube en un proyecto de IronPPT?
El agente en la nube se ejecuta en Ubuntu Linux a menos que el repositorio elija lo contrario. IronPPT apunta a .NET Standard 2.0, y ninguno de los paquetes que restaura contiene un archivo nativo, por lo que los pasos de configuración no instalan nada más allá del SDK de .NET.
El ejecutor tampoco tiene clave de licencia. Sin una, IronPPT construyó conjuntos en memoria y leyó conjuntos guardados, pero Save lanzó una excepción de licencia y no escribió ningún archivo. Por lo tanto, cada prueba que guarda un conjunto falla en el ejecutor.
GitHub ejecuta el trabajo copilot-setup-steps en .github/workflows/copilot-setup-steps.yml antes de que el agente comience, y solo cuando el archivo está en la rama predeterminada. Cuando un paso de configuración falla, Copilot omite los pasos después de él.
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.
Coloca la clave en los secretos de Agentes: según GitHub, el agente en la nube no tiene acceso a los secretos de Actions, Codespaces o Dependabot. En la Configuración del repositorio, abre Secretos y variables en la sección de Seguridad, selecciona Agentes y añade IRONPPT_LICENSE_KEY en la pestaña de Secretos. La documentación de GitHub no da ejemplo de un paso de configuración que lea un secreto de Agentes.
¿Qué debes verificar antes de fusionar?
Ejecuta la revisión como un comando copilot -p separado, fuera de la sesión que escribió el 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.
¿Qué produjeron los prompts en una ejecución real?
Los siete avisos se ejecutaron sin supervisión en Copilot CLI contra un repositorio de listados construido para esta guía. Una verificación separada leyó cada figura a continuación desde los conjuntos guardados y el repositorio.
- Antes de la ejecución, ListingDeck era una clase vacía y la CLI imprimió una línea de uso y salió con código 1.
- Después del primer aviso, el conjunto tenía una portada y cuatro diapositivas de listado, 15,150,897 bytes en total.
- Las 10 imágenes estaban dentro de sus cajas sin error medible en proporción, tamaño o centrado.
- El intercambio reemplazó al héroe de 220 Mill Road a través de document.Images.
- La nueva captura en formato vertical midió 243 por 324 puntos, centrada en la caja heroica.
- Ninguna de las otras nueve imágenes ni el texto de la diapositiva cambiaron en el intercambio.
- En modo de planificación, Copilot escribió un plan, no cambió ningún archivo y esperó el mensaje de aprobación.
- La corrección invirtió el bucle en SoldUpdate.cs.
- Marcar el 18 Alder Court como vendido no dejó fotos en su diapositiva.
- Copilot atribuyó las fotos restantes a las entradas que se desplazaban dentro de una lista y no mencionó que cada lectura de Slide.Images construye una lista nueva.
- Tres fotos eliminadas, 6,469,676 bytes en total, permanecieron en la copia vendida.
- La sesión del problema escaló nueve fotos a 1600 píxeles en el lado largo con SixLabors.ImageSharp, que IronPPT ya incluye, y no añadió ningún paquete.
- El conjunto reconstruido midió 1,198,644 bytes.
- Cada imagen mantuvo su tamaño y posición.
- Con la clave configurada, las siete pruebas pasaron. Sin ella, las siete fallaron con la excepción de licencia.
- La sesión de revisión comparó la rama con main, no reportó desacuerdo y no cambió ningún archivo.
- Algunos pasos se ejecutaron de manera diferente a lo esperado. El cuerpo del problema fue a una nueva sesión de Copilot CLI, porque el repositorio de prueba no tiene un remoto de GitHub. El flujo de trabajo de configuración se escribió pero no se ejecutó, por la misma razón.
Cursor también aplica archivos de reglas comprometidos a rutas que coinciden, y Claude Code también retiene su plan para aprobación antes de editar el código. El registro compartido de ejecución lista la versión de lanzamiento de Copilot CLI, el modelo Auto seleccionado, la duración y la máquina de prueba.
Solución de problemas
- Cómo gestionar imágenes en PowerPoint para añadir imágenes y para el bucle de eliminar-todo que cuenta hacia abajo
- Cómo añadir diapositivas para la diapositiva predeterminada que ya tiene una nueva presentación
- Cómo aplicar claves de licencia para una guardada que lanza una excepción de licencia
¿Preguntas?
Si tienes alguna pregunta, contacta a support@ironsoftware.com
Curtis Chau tiene una licenciatura en Ciencias de la Computación (Carleton University) y se especializa en el desarrollo front-end con experiencia en Node.js, TypeScript, JavaScript y React. Apasionado por crear interfaces de usuario intuitivas y estéticamente agradables, disfruta trabajando con frameworks modernos y creando manuales bien estructurados y visualmente atractivos.