Jak używać IronPPT z GitHub Copilot
Agencja nieruchomości wysyła co piątek agentom kupujących zestaw otwartych domów. Każda oferta nieruchomości otrzymuje jeden slajd z maksymalnie trzema zdjęciami, a zdjęcia pochodzące z telefonów i aparatów są w różnych rozmiarach, kształtach i rozdzielczościach. Usługa .NET w repozytorium agencji buduje zestaw, więc każdy asystent, który zmienia tę usługę, musi umieścić każde zdjęcie w ramce bez zniekształceń.
GitHub Copilot dociera do repozytorium poprzez czat i tryb agenta w Visual Studio i VS Code, przez Copilot CLI w terminalu, oraz przez agenta w chmurze na GitHub, który zamienia przypisane zgłoszenie na prośbę o ściągnięcie. IronPPT tworzy i edytuje pliki PowerPoint w .NET bez Microsoft Office. AddImage umieszcza obraz na slajdzie, a klasa Image ustala jego rozmiar, zastępuje i usuwa. Pliki z instrukcjami wprowadzone do repozytorium dają każdej z tych powierzchni zasady IronPPT.
Ten przewodnik obejmuje kierowanie Copilot do budowy oprogramowania umieszczającego zdjęcia z IronPPT. Wykonywanie zdjęć i projektowanie szablonu slajdu to oddzielne zadania realizowane poza repozytorium. Przewodnik zarządzania obrazami opisuje wywołania IronPPT, od których zależy lista slajdów.
Szybki startOtworzyć terminal w katalogu głównym repozytorium, uruchomić Copilot CLI i przesłać prompt. Copilot CLI dołącza plik z @, podczas gdy Copilot Chat w Visual Studio używa odniesień #.
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.
Prompt nie zawiera żadnej ramki ani współrzędnej, ponieważ docs/listing-layout.md definiuje ramki zdjęć w punktach i kolejność linii tekstu.
Ustawić IRONPPT_LICENSE_KEY w środowisku, gdzie uruchamiany jest Copilot. IronPPT nie odczytuje tej nazwy samodzielnie. W naszym teście License.IsLicensed pozostał fałszywy, gdy ustawiono tylko tę zmienną. IronPPT samodzielnie odczytał zmienne o nazwach IronPPT.LicenseKey oraz IRONPPT_LICENSEKEY, ale przykładowe repozytorium kopiuje konwencjonalną nazwę do License.LicenseKey. przewodnik dotyczący klucza licencyjnego wylistuje inne obsługiwane lokalizacje.
Minimalny proces (5 kroków)
- Pobierz bibliotekę PowerPoint dla C# z NuGet
- Zapisz zasady IronPPT w .github/copilot-instructions.md oraz w jednym pliku z instrukcjami specyficznymi dla ścieżki
- Przypisać każdemu obrazowi Szerokość, Wysokość i Pozycję obliczoną na podstawie rozmiaru w pikselach danego zdjęcia
- Zastąpić zdjęcie w zapisanym zestawie za pomocą listy Obrazy dokumentu, a następnie ustawić ponownie jego ramkę
- Przypisać kolejną zmianę agentowi chmury jako zgłoszenie i zweryfikować prośbę o ściągnięcie w porównaniu z dokumentacją IronPPT API
Jak ustawić konwencje IronPPT dla Copilot?
Umieść zasady dla całego projektu w .github/copilot-instructions.md. Dokumentacja wsparcia GitHub zawiera ten plik dla Copilot Chat w Visual Studio, VS Code i IDE JetBrains, oraz dla agenta chmury i przeglądu kodu Copilot. Copilot CLI odczytuje go z tej samej lokalizacji. Visual Studio wczytuje go, gdy wybrana jest opcja niestandardowych instrukcji, która jest domyślnie włączona.
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 nazywa każde zdjęcie losowym numerem, takim jak Obraz 86115, dlatego dwa zestawy z tych samych ofert różniły się bajt po bajcie. Z tego powodu testy porównują zdjęcia i tekst.
Jak przypisać zestawowi kod jego własne zasady?
Plik taki jak .github/instructions/deck.instructions.md zawiera zasady dla części drzewa, które nazwy wzorców applyTo, tutaj projektów źródłowych i testowych. Według dokumentacji GitHub, Copilot CLI zawiera plik tylko wtedy, gdy działa na plikach pasujących do jednego z tych wzorców. W teście Copilot otworzył ten plik przed każdym innym plikiem w pierwszym promcie i w osobnej sesji zgłoszenia.
---
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.
Każda zasada w tym pliku pochodzi z próbowania IronPPT 2026.10.1.
Jak duże zdjęcie IronPPT umieszcza w zestawie ofert?
AddImage bez rozmiaru nadaje obrazowi ramkę opartą na liczbie pikseli zdjęcia podzielonej przez jego DPI, w calach, i nie ustawia jego pozycji. Domyślny slajd ma wymiary 10 na 7,5 cala, co odpowiada 720 na 540 punktów.
- Zdjescie z telefonu o rozdzielczosci 4032 na 3024 zapisane przy 72 dpi otrzymalo ramke o wymiarach 56 na 42 cale.
- To samo zdjecie w rozdzielczosci 2048 na 1536 zapisane przy 300, 72 i 96 dpi otrzymało ramki szerokosci 6,8, 28,4 i 21,3 cala. Plik PNG bez DPI zostal rozmiarowany jako 96 dpi.
- JPEG o gęstości 1 na 1 bez jednostki w nagłówku został rozmiarowany jako 1 dpi, więc zdjęcie o szerokości 4032 pikseli stało się 4032 cali szerokie.
- Szerokosc, Wysokość i Pozycja są podane w punktach. Ustawienie Szerokości tylko na 400 pozostawiło Wysokość niezmienioną, więc ramka straciła proporcje zdjecia.
Dopasowanie w docs/listing-layout.md zatem zaczyna się od rozmiaru w pikselach zdjecia. Wspolczynnik skali to mniejszy z wynikow podzielenia szerokosci ramki przez szerokość zdjęcia i wysokości przez wysokość zdjęcia, a przeskalowana ramka jest wycentrowana w ramce.
Jak zamienić zdjecie w zapisanym zestawie?
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 dał trzy różne wyniki w probach.
- Na zestawie zbudowanym w pamięci, Replace wymieniło zdjęcie i ustawiło ramkę na rozmiar nowego zdjęcia, bez pozycji.
- Na wczytanym zestawie, zastąpienie wywołane przez listę
Imagesslajdu nie zmieniało zadanego zdjęcia w żadnej próbie. Slajd z jednym zdjęciem zachował stare zdjęcie i przechował nowe, nieużyte w pliku. Na slajdzie z dwoma zdjęciami, wywołanie na pierwszym zdjęciu wymieniło drugie. - Przez
document.Images, zastępienie na wczytanym zestawie wymieniło właściwe zdjęcie. Ustawienie Szerokości, Wysokości i Pozycji po wywołaniu nadało ramce odpowiedni rozmiar i miejsce.
Sample z przewodnika zarządzania obrazem wywoluje Replace przez Slides[0].Images[0] na wczytanym zestawie, co było trasą, która pozostawiła stare zdjecie na miejscu.
Wynik
Test zapisano do slajdu dla 220 Mill Road przed i po wymianie.

Slajd 4 jako pierwszy prompt zapisano, z każdym obrazem narysowanym na jego przechowywanej pozycji i rozmiarze. Tekst nie jest rysowany, a zdjęcia to wygenerowane obrazy testowe.

Slajd 4 po poleceniu wymiany, narysowany w ten sam sposób.
Jak przetestować zestaw?
Użyć Shift+Tab, aby przełączyć Copilot CLI na tryb planu, a następnie przesłać ten 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.
Test skrzynek musi odczytac rozmiary, które IronPPT raportuje błędnie. Szerokość, Wysokość i Pozycja odczytane z ponownie otwartego zestawu zwracaja 12 700 razy ich wartość w punktach, co odpowiada wartości w EMU, jednostce, którą plik PPTX przechowuje. Ramka o szerokości 480 punktów odczytana została jako 6 096 000. Testy z wykonania podzieliły odczytane wartości przez 12 700 przed porównaniem ich z układem.
Dlaczego oznaczenie oferty jako sprzedanej zostawia zdjęcia?
W tym scenariuszu, SoldUpdate.cs współpracownika usuwa zdjęcia sprzedanej oferty w pętli.
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 buduje nową listę przy każdym dostepie. Pętla, która odczytuje slide.Images na każdej iteracji, z indeksem, który się zwiększa, pomija zdjęcie po każdej usunięciu. Na slajdzie z czterema zdjęciami usunęło dwa, a na slajdzie z trzema zdjęciami usunęło dwa i zostawiło jedno. Pętla, która zlicza do tyłu, jak w przykladzie usuwania wszystkich z przewodnika zarządzania obrazem, usunęła każde zdjecie, podobnie jak foreach nad jedną kopią listy.
Usuniecie również pozostawia bajty zdjęcia w pliku. Usunięcie czterech zdjęć z zestawu o pojemności 13 766 065 bajtów zapisało plik o pojemności 13 765 502 bajtów.
Co sprawia, że temat jest działaniem, które agent chmurowy może realizować?
Kiedy zgłoszenie jest przypisane do Copilot, GitHub przekazuje agentowi tytuł zgłoszenia, jego opis, komentarze istniejące w tamtym momencie oraz jakiekolwiek polecenia podane przy przypisaniu. Komentarze dodane później nie docierają do agenta, więc ciało zgłoszenia musi zawierać całe żądanie.
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 kopiuje każdy plik zdjęcia do zestawu bajt po bajcie, a zdjęcie dodane trzy razy jest przechowywane trzy razy. Zdjecie przeskalowane przekazane do AddImage jako AnyBitmap zapisano jako nieskompresowane BMP o pojemności 7 680 122 bajtów dla 1600 na 1200 pikseli. Te same piksele zakodowane jako JPEG o jakości 85 i przekazane jako strumień zostały zapisane jako 337 813 bajtów.
Dlaczego testy agenta chmury nie powiodły się na projekcie IronPPT?
Agent chmurowy działa na Ubuntu Linux, chyba że repozytorium wybiera inaczej. IronPPT celuje w .NET Standard 2.0 i żadna z przywracanych paczek nie zawiera pliku natywnego, więc kroki konfiguracji nie instalują niczego poza SDK .NET.
Biegacz nie ma również klucza licencyjnego. Bez niego, IronPPT budował zestawy w pamięci i czytał zapisane zestawy, ale Save rzucał wyjątek license i zapisywał pliku. Dlatego każdy test, który zapisuje zestaw, nie powodzi się na biegaczu.
GitHub uruchamia zadanie copilot-setup-steps w .github/workflows/copilot-setup-steps.yml przed uruchomieniem agenta, tylko wtedy, gdy plik jest na domyślnej gałęzi. Kiedy krok konfiguracji zawiedzie, Copilot pomija kroki po nim.
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.
Umieść klucz w sekretach agentów: Według GitHub, agent chmurowy nie ma dostępu do sekretów Actions, Codespaces lub Dependabot. W Ustawieniach repozytorium, otwórz Sekrety i zmienne w sekcji Bezpieczeństwo, wybierz Agenci i dodaj IRONPPT_LICENSE_KEY na karcie Sekrety. Dokumentacja GitHubu nie daje przykładu kroku konfiguracji, który odczytuje sekret Agentów.
Co należy sprawdzić przed scaleniem?
Uruchomić przegląd jako osobne polecenie copilot -p, poza sesją, która napisała kod.
/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.
Co wyprodukowały zapytania w rzeczywistym uruchomieniu?
Siedem promptów uruchomiono bez nadzoru w Copilot CLI przeciwko repozytorium ofert zbudowanemu dla tego przewodnika. Osobne sprawdzenie odczytało każdą z poniższych wartości z zapisanych zestawów i repozytorium.
- Przed uruchomieniem, ListingDeck była pustą klasą, a CLI wydrukował linie użytku i zakończył z kodem 1.
- Po pierwszym promptie, zestaw zawierał okładkę i cztery slajdy ofert, w sumie 15 150 897 bajtów.
- Wszystkie 10 zdjęć znajdowało się w swoich ramkach bez wykrywalnego błędu w proporcji wymiarów, rozmiarze lub wycentrowaniu.
- Wymiana zamieniła bohatera 220 Mill Road przez document.Images.
- Portretowe zdjęcie mierzyło 243 na 324 punkty, wycentrowane w ramce bohatera.
- Żadne z pozostałych dziewięciu zdjęć ani tekst slajdu nie zmienily się podczas wymiany.
- W trybie planu, Copilot napisał plan, nie zmienił pliku i czekał na wiadomość zatwierdzenia.
- Poprawka odwróciła pętle w SoldUpdate.cs.
- Oznaczenie 18 Alder Court jako sprzedane nie pozostawiło żadnego zdjęcia na jego slajdzie.
- Copilot przypisał pozostawione zdjęcia do przesunięcia wpisów wewnątrz listy i nie wspomniał, że każde odczytanie Slide.Images buduje nową listę.
- Trzy usunięte zdjęcia, w sumie 6 469 676 bajtów, pozostały w sprzedanej kopii.
- Sesja zgłoszenia przeskalowała dziewięć zdjęć do 1600 pikseli po długim boku za pomocą SixLabors.ImageSharp, którą IronPPT już wprowadza, i nie dodano żadnego pakietu.
- Odbudowany zestaw ważył 1 198 644 bajty.
- Każde zdjęcie zachowało swój rozmiar i pozycję.
- Z ustawionym kluczem, wszystkie siedem testów przeszło pozytywnie. Bez niego, wszystkie siedem zakończyło się błędem licencyjnym.
- Sesja przeglądowa porównała gałąź z main, nie zgłosiła żadnych niezgodności i nie zmieniła pliku.
- Niektóre kroki uruchomiono inaczej niż na stronie. Ciało zgłoszenia poszło do nowej sesji Copilot CLI, ponieważ testowe repozytorium nie ma zdalnego GitHuba. Przepływ konfiguracji został napisany, ale nie uruchomiono, z tego samego powodu.
Cursor również stosuje zapisane pliki zasad do pasujących ścieżek, a Claude Code również trzyma plan do zatwierdzenia przed edycją kodu. Wspólny zapis uruchomienia wymienia wydanie Copilot CLI, model Auto wybrany, czas trwania i maszynę testową.
Rozwiązywanie problemów
- Jak zarządzać obrazami w PowerPoint dla dodawania obrazów i dla pętli usuwania wszystkich, która zlicza się w dół
- Jak dodać slajdy dla domyślnego slajdu, który nowa prezentacja już posiada
- Zastosowanie kluczy licencyjnych dla zapisu, który rzuca wyjątek licencyjny
Pytania?
W przypadku jakichkolwiek pytań, należy skontaktować się z support@ironsoftware.com
Curtis Chau posiada tytuł licencjata z informatyki (Uniwersytet Carleton) i specjalizuje się w front-endowym rozwoju, z ekspertką w Node.js, TypeScript, JavaScript i React. Pasjonuje się tworzeniem intuicyjnych i estetycznie przyjemnych interfejsów użytkownika, Curtis cieszy się pracą z nowoczesnymi frameworkami i tworzeniem dobrze zorganizowanych, atrakcyjnych wizualnie podręczników.