如何使用IronPPT與GitHub Copilot
一家房地產代理每週五向買方經紀人發送其開放房屋的簡報。 每個房產清單都有一張幻燈片,其中最多包括三張照片,照片來自於手機和相機,各具不同大小、形狀和分辨率。 該代理的儲存庫中的一個.NET服務構建這些簡報,因此任何更改該服務的助手必須將每一張照片保持在其框架內而不失真。
GitHub Copilot通過Visual Studio和VS Code中的聊天和代理模式、終端中的Copilot CLI以及GitHub上的雲代理到達儲存庫,將指定的問題轉化為拉取請求。IronPPT在.NET中建立和編輯PowerPoint檔案,不需要Microsoft Office。AddImage將照片放在幻燈片上,而Image類大小、替換和移除它。 提交到儲存庫的指令檔為這些介面提供IronPPT規則。
本指南涵蓋了指導Copilot使用IronPPT放置照片的軟體構建。 拍攝照片和設計幻燈片模板是在儲存庫之外進行的獨立任務。 管理圖片指南描述了依賴於IronPPT的列表簡報的調用。
快速開始在儲存庫根目錄打開終端,啟動Copilot CLI並提交提示。 Copilot CLI附加一個包含@的檔案,而Visual Studio中的Copilot Chat使用#參考。
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.
提示中不命名任何框或座標,因為docs/listing-layout.md定義了照片框的點數和文本行的順序。
在Copilot運行的環境中設置IRONPPT_LICENSE_KEY。 IronPPT不會自行讀取該名稱。 在我們的測試中,當僅設置該變量時,License.IsLicensed保持不變為假。 IronPPT確實讀取了IronPPT.LicenseKey和IRONPPT_LICENSEKEY名的變量,但是示例儲存庫將常規名稱複製到License.LicenseKey。 授權金鑰指南列出了其他支持的位置。
最小工作流程(5 個步驟)
- 從NuGet下載C# PowerPoint程式庫
- 將IronPPT規則寫入.github/copilot-instructions.md加上一個路徑專用的指令檔
- 為每張照片分配由該照片像素大小計算的寬度、高度和位置
- 通過文檔的Images列表替換已保存簡報中的照片,然後重新設置其框架
- 將下一次更改分配為雲代理的一個問題,並根據IronPPT API參考驗證拉取請求
如何為Copilot設置IronPPT規則?
將項目範圍內的規則放在.github/copilot-instructions.md中。 GitHub的支援參考列出了該檔給Visual Studio、VS Code和JetBrains IDEs中的Copilot Chat,以及雲代理和Copilot代碼審核。 Copilot CLI從相同位置讀取。 Visual Studio在選擇自定義指令選項時加載該檔,該選項預設為開啟。
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用隨機數如Picture 86115命名每張圖片,因此來自相同列表的兩個構建逐字節不同。 測試因此比較了圖片和文本。
如何為簡報代碼設置自己的規則?
諸如.github/instructions/deck.instructions.md之類的檔案保存了其applyTo模式命名的樹的那些部分的規則,在這裡是原始碼和測試專案。 根據GitHub的文檔,Copilot CLI僅在它處理匹配這些模式的檔案時才包括該檔。 在測試運行中,Copilot在第一個提示和問題的單獨會話中打開了這個檔案。
---
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.
該檔中的每條規則都來自IronPPT 2026.10.1的測試。
IronPPT生成的列表照片有多大?
不帶大小的AddImage使照片具有像素數除以DPI,以英寸為單位的框架,而不為其設置位置。 默認的幻燈片是10 x 7.5英寸,即720 x 540點。
- 一張4032 x 3024的手機照片以72 dpi保存,獲得了一個56 x 42英寸的框架。
- 相同的2048 x 1536照片以300、72和96 dpi保存,分別獲得了6.8、28.4和21.3英寸寬的框架。一個不帶DPI的PNG被設置為96 dpi。
- 一個JPEG在header中密度為1 x 1且沒有單位,設置為1 dpi,因此4032像素的照片變成了4032英寸寬。
- 寬度、高度和位置以點為單位。 僅設置寬度為400使高度保持不變,因此框架丟失了照片的長寬比。
docs/listing-layout.md 中的擬合因此從照片的像素大小開始。縮放因子選取框寬與照片寬之比和框高與照片高之比中較小者,並在框內居中縮放後的框架。
如何交換已保存簡報中的照片?
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給出了三種不同的結果。
- 在內存中生成的簡報上,Replace交換了照片並將框架重置為新照片的自身大小,沒有設置位置。
- 在載入的簡報上,通過幻燈片的
Images列表調用Replace在任何探針中都沒有更改所請求的圖片。 帶有一張圖片的幻燈片保留了舊的照片,並將新的照片儲存在檔中未使用。 在具有兩張照片的幻燈片上,對第一張照片的調用交換了第二張照片。 - 通過
document.Images,載入的簡報上的Replace交換了正確的照片。 在調用後設置寬度、高度和位置給了框架正確的大小和位置。
管理圖片指南的替換示例通過Slides[0].Images[0]調用Replace於載入的簡報上,這是將舊照片保留原位的路徑。
輸出
測試運行在交換前後保存了220 Mill Road的幻燈片。

第一次提示保存了幻燈片4,每個圖片在其儲存的位置和大小狀態下繪製。文本未繪製,照片是生成的測試圖片。

交換命令後的幻燈片4,以相同方式繪製。
如何測試簡報?
使用Shift+Tab將Copilot CLI切換到計劃模式,然後提交此提示。
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.
對框進行的測試必須讀取IronPPT報告錯誤的大小。 從重新打開的簡報中讀取的寬度、高度和位置返回它們在點數中的值的12,700倍,這是PPTX檔案儲存的單位EMUs。 一個480點的框架讀回為6,096,000。運行中的測試在將讀回值與佈局進行比較之前將其除以12,700。
為什麼標記為已售的清單會留有照片?
在這種情況下,隊友的SoldUpdate.cs在循環中移除了已售清單的照片。
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都構建一個新列表。 在每一次迭代中,循環再次讀取slide.Images,並且一個計數增長的索引,每次移除後跳過一張照片。 在有四張照片的幻燈片上,它移除了兩張,而在有三張的列表幻燈片上,它移除了兩張,留下了一張。 如管理圖片指南的移除所有示例所做,倒計數的循環移除了所有圖片,一個foreach對一個列表的副本進行了同樣的操作。
移除還會將照片的位元組保留在檔中。從一個13,766,065位元組的簡報中移除四張照片,保存了一個13,765,502位元組的檔案。
使雲代理可以操作的問題具備什麼條件?
當一個問題被指派給Copilot時,GitHub將問題的標題、描述、當時存在的評論以及分配時給出的所有指令傳遞給代理。 稍後添加的評論無法到達代理,問題本體必須包含整個請求。
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將每個照片檔案逐字節地複製到簡報中,並且一個照片添加三次將儲存三次。 縮放照片作為AnyBitmap 傳遞給AddImage時,被儲存為7,680,122位元組的未壓縮BMP,解析度為1600 x 1200像素。 相同的像素以85質量的JPEG格式編碼並作為流傳遞時儲存為337,813位元組。
為什麼雲代理的測試在IronPPT專案中失敗?
雲代理在Ubuntu Linux上運行,除非儲存庫選擇其他配置。IronPPT針對.NET Standard 2.0,其恢復的套件中沒有包含本機文件,因此設置步驟不安裝超出.NET SDK的任何東西。
運行者也沒有授權金鑰。 沒有金鑰,IronPPT在內存中構建了簡報並讀取了已保存的簡報,但Save拋出了一個授權異常且沒有寫入檔案。因此,所有保存簡報的測試在運行者上都失敗。
GitHub在代理啟動前在.github/workflows/copilot-setup-steps.yml中運行copilot-setup-steps作業,且僅在檔案位於預設分支時運行。 當任何設置步驟失效時,Copilot會跳過其後的步驟。
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.
在代理秘密中放置金鑰:根據GitHub,雲代理無權訪問Actions、Codespaces或Dependabot秘密。 在儲存庫的設定中,打開安全性部分中的秘密和變量,選擇代理並在秘密標籤中添加IRONPPT_LICENSE_KEY。 GitHub的檔例沒有展示任何能讀取授權秘密的設置步驟。
合併之前應檢查什麼?
在編寫代碼的會話之外,將審核作為單獨的copilot -p命令運行。
/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.
在實際運行中,這些提示產生了什麼結果?
這七個提示在與此指南構建的列表儲存庫中Copilot CLI中的未監控狀態運行。單獨檢查從已保存的簡報和儲存庫中讀取了以下每個數字。
- 在運行前,ListingDeck是一個空類,CLI打印了一行用法並以代碼1退出。
- 在第一次提示結束後,簡報包括了一個封面和四張列表幻燈片,共15,150,897位元組。
- 所有10張圖片均在其框內,沒有測得的比例、大小或居中誤差。
- 通過document.Images調用,交換220 Mill Road的主打照片。
- 縱向重新拍攝的照片測量為243 x 324點,居中於主打框中。
- 其他九張照片或幻燈片文本在交換中未更改。
- 在計劃模式中,Copilot寫了一個計劃,未更改任何檔,等待批准訊息。
- 修正反轉了SoldUpdate.cs中的循環。
- 標記18 Alder Court為已售,然後幻燈片上沒有圖片。
- Copilot將剩餘的照片歸因於列表內的條目移動,而沒有提到每次讀取Slide.Images都會構建一個新列表。
- 三張已移除的照片,全部6,469,676位元組,留在售出的副本中。
- 問題的會話將九張照片縮放至長邊1600像素,使用SixLabors.ImageSharp,它已經被IronPPT引入,且未添加套件。
- 重建的簡報測量為1,198,644位元組。
- 每張圖片保留了其大小和位置。
- 設置金鑰後,所有七個測試通過。 未設置金鑰時,所有七個測試因授權異常失敗。
- 審核會話比較了分支和主幹,未報告分歧,也未更改任何檔案。
- 一些步驟與頁面上運行的不同。 問題本體去了新的Copilot CLI會話,因為測試儲存庫沒有GitHub遠端。 設置工作流程已編寫但未運行,出於同樣的原因。
Cursor也將已提交的規則檔應用於匹配的路徑,以及Claude Code在編輯代碼之前也會為批准保持其計劃。 共享運行記錄列出了Copilot CLI釋放,模型Auto選擇,持續時間和測試機器。
疑難排解
- 如何在PowerPoint中管理圖像 用於添加照片和計數下的移除所有循環
- 如何添加幻燈片 用於新演示已持有的預設幻燈片
- 應用授權金鑰 用於節省引發授權異常的保存
問題?
如果您有任何疑問,請聯繫support@ironsoftware.com
Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。