如何在GitHub Copilot中使用IronPPT
一家房地产经纪公司每周五向买房代理发送其开放房屋的幻灯片。 每个房产列表接收一张幻灯片,最多可以包括三张照片,而这些照片从手机和相机上传输过来时大小、形状和分辨率各不相同。 代理公司的存储库中有一个.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仅在设置了该变量时仍保持为false。 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 IDE中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乘以7.5英寸,即720乘以540点数。
- 一个以72 dpi保存的4032乘以3024手机照片得到了56乘以42英寸的框架。
- 以300、72和96 dpi保存的同一2048乘以1536照片分别得到宽6.8、28.4和21.3英寸的框架。无DPI的PNG大小被设置为96 dpi。
- 一张密度为1乘以1且头文件中没有单位的JPEG被设置为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循环到计划模式,然后提交此提示。
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文件存储的EMU单位。 读取回的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的循环,使用一个向上计数的索引,在每次删除后跳过一张图片。 在含有四张照片的幻灯片上,它移除了两张,在含有三张照片的列表幻灯片上,它移除了两张并留下了一张。 管理图像指南的remove-all示例中,循环向下计数,删除了每张照片,一个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将每个照片文件字节逐字节复制到幻灯片中,三次添加的照片将存储三次。 一个缩放照片作为AddImage传递给AnyBitmap后被存储为一个未压缩的7,680,122字节的BMP,尺寸为1600乘以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.
将密钥放在Agents秘密:根据GitHub,云代理无法访问Actions、Codespaces或Dependabot秘密。 在存储库的设置中,打开安全部分的秘密和变量,选择Agents并在秘密选项卡中添加IRONPPT_LICENSE_KEY。 GitHub的文档中没有提供读取Agents秘密的设置步骤示例。
合并前应检查什么?
以独立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字节。
- 所有十张图片均在它们的框中,没有可测量的纵横比、尺寸或居中错误。
- 通过document.Images替换了220 Mill Road的主图。
- 剪影重拍测量为243乘以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的版本、自动选择的模型、持续时间和测试机器。
故障排除
- 如何在PowerPoint中管理图片 用于添加图片和包含向下计数的移除循环
- 如何添加幻灯片 用于新的演示文稿已经持有的默认幻灯片
- 应用许可密钥 用于因许可异常而抛出的保存
有问题吗?
如果您有任何问题,请联系support@ironsoftware.com
Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。