如何在GitHub Copilot中使用IronWord
.NET服务可以生成月度账户报表作为Word文件,每个文件包含一个样式化的标题、两行摘要和一个从数据构建的表格。 在本指南中,服务存在于Visual Studio解决方案中,与提供其数据的作业放在一起,所以任何修改助手都必须在同一解决方案内工作。
GitHub Copilot可以在Visual Studio或VS Code中以聊天或代理模式在该解决方案上工作,从含有Copilot CLI的终端中,并从GitHub中,其云代理为分配给它的问题打开一个pull请求。 IronWord在代码中构建DOCX,包含样式化的文本运行和合并单元格及阴影行的表格。 IronWord规则保存在库中的指令文件中,每个表面都读取这些规则。
快速入门从解决方案根目录启动Copilot CLI,并粘贴下面的提示。 Visual Studio中的Copilot Chat引用了包含#的文件,而CLI使用@。
Fill in @src/Statements/Documents/StatementBuilder.cs with a public static Build method.
Its signature is Build(Account account, IReadOnlyList<Transaction> transactions, string outputPath).
Add Account and Transaction as small records in the same folder.
Write the DOCX with IronWord, from the IronWord NuGet package.
The types are in the IronWord and IronWord.Models namespaces.
Lay out the statement exactly as @docs/statement-layout.md describes. Three parts need care:
- the bold heading row
- the merged closing-balance cell
- the alternate row shading
Save the file to outputPath, then compile the solution and clear every build error.
Tell me which files you added or changed.
提示不包含任何样式成员名称。 下面的特定路径指令文件指定要使用的成员。
解决方案的Program.cs从环境中读取IRONWORD_LICENSE_KEY并将其分配给IronWord.License.LicenseKey,所以在启动Copilot之前设置变量。 许可证密钥指南展示了相同的分配及存放密钥的配置文件。
最小工作流程(5 个步骤)
- 从NuGet下载C# Word库
- 将IronWord规则写到.github/copilot-instructions.md加上一个路径特定的指令文件
- 在运行中样式化文本,并添加合并的关闭行作为一个单独的行
- 重新打开每个保存的报表,并将其表格单元格与源数据进行比较
- 将下一个更改分配给云代理作为一个问题,并根据IronWord API参考验证pull请求
如何为Copilot设置IronWord约定?
整个库的规则放在.github/copilot-instructions.md中。 Copilot CLI、Copilot代码审查、云代理和JetBrains IDEs、Visual Studio和VS Code中的Copilot Chat都读取该文件,根据GitHub的支持矩阵。 Visual Studio仅在其Copilot Chat选项中选择自定义指令复选框后才加载它。
Statement code in this repository follows these rules:
- Statements are DOCX files written with IronWord, from the NuGet package IronWord.
- Import both namespaces, IronWord and IronWord.Models.
- Use no other Word library and no OpenXML SDK code.
- Keep the IronWord version set in Directory.Packages.props, unless the task is upgrading it.
- IRONWORD_LICENSE_KEY holds the license key, and Program.cs reads it there.
- Do not put the key in source, settings files, tests or logs.
- Never print its value, and don't list environment variables.
- docs/statement-layout.md is the layout contract. Do not edit it.
- Propose changes to that layout in your reply instead.
- IronWord's documentation for agents is at https://ironsoftware.com/word/csharp/llms.txt
- An IronWord member is real only when it builds and a saved file shows its effect.
- The documentation, its samples and IronWord.xml list some that do not compile or are not saved.
Statement tests follow these rules:
- Build statements in a temp directory and reopen the saved file with IronWord.
- Compare cell text, values and run styles. Never compare DOCX bytes.
如何为文档代码设定自己的规则?
仅用于某些文件夹的规则放在路径特定的文件中,例如.github/instructions/documents.instructions.md,其中的applyTo模式涵盖了文档代码及其测试。 GitHub的Copilot CLI文档说CLI仅在其处理的文件匹配列出的模式时才将文件添加到请求中。 在我们的运行中,CLI在每个会话开始时列出了文件的模式和路径,而Copilot在其首次编辑前读取了该文件。
---
applyTo: "src/Statements/Documents/**,tests/Statements.Tests/**"
---
The document code and its tests follow these IronWord rules:
- Style text on a Run, with new Run(new TextStyle { ... }) or Run.Style.
- TextContent.IsBold, TextContent.FontSize and Run.FontSize are read-only.
- SaveAs drops a TextStyle assigned to TextContent.Style.
- SaveAs writes a TextStyle's FontSize only when its TextFont is set too.
- Add each body line as its own paragraph with AddParagraph.
- WordDocument.AddText joins its text onto whichever paragraph came last.
- Table.ApplyCellStyle is listed in IronWord.xml but does not compile.
- Style each cell's runs in place of ApplyCellStyle.
- new Table(rows, columns) creates every cell, with zero-based indexes.
- Fill a cell with AddChild or AddText on table[row, column].
- Table.Rows, TableRow.Cells and a TableRow indexer return ITableRow and ITableCell.
- ITableRow and ITableCell have no AddText, AddChild or ExtractText.
- Cast to TableRow or TableCell first.
- SaveAs writes no merge made with Table.MergeCells.
- For a cell that spans two columns, add a new TableRow of two TableCells with AddRow.
- Give the first of those two cells GridSpan = 2.
- Shade alternate rows with Table.Zebra = new ZebraColor(first, second).
- SaveAs writes no fill set through TableCell.Shading.
- With no key set, every save throws LicensingException.
- An in-memory build does not throw it, so it proves nothing about the saved file.
该文件中的每条规则都来自一个构建、内存检查或保存的文件。附带的XML文档在表格中列出了ApplyCellStyle,但编译器用CS1061拒绝了该调用,所以光靠XML无法判断成员是否可以编译。 一次探测显示,通过单元格的Shading属性设置的填充从未写入保存的文件,而Zebra将填充写入每个单元格。
如何从CSV数据构建报表表格?
在此阶段,报表代码可能会失败且不会产生错误。 在保存的文件中,合并了MergeCells的关闭行仍包含三个普通单元格,尽管表格在内存中记录了合并。 设置为18号字体且无字体的标题被保存时没有大小。仅在对保存文件的检查中才能检测出任一个问题。
Rework @src/Statements/Pipeline/StatementJob.cs to write one statement per account, in this order:
1. Read Data/accounts.csv and Data/transactions.csv.
2. Group the transactions by account.
3. Call StatementBuilder.Build once per account.
4. Write <AccountId>.docx into the output folder that StatementJob.Run receives.
That folder is out/statements under the solution root.
The data needs care in a few places:
- Descriptions such as "Rent, September" hold commas.
- Parse quoted fields with a few lines of your own code, and add no CSV package.
- Parse amounts as decimal with the invariant culture.
- An account with no transactions still gets a statement, with its heading and closing rows.
Run the job.
For every statement, print its path, its transaction row count and its closing balance.
该装置包含四个账户,分别有五个、两个、三个和零个交易。 在CSV文件中,储蓄账户的行不是按日期顺序排列的,而布局要求最老的在前。
如何测试保存的IronWord报表?
文档上的ExtractText返回其段落,但没有任何表格文本,所以基于其的测试即使每个单元格都是空的也会通过。
在发送此提示之前,用Shift+Tab切换Copilot CLI到计划模式。
Plan an xUnit suite in tests/Statements.Tests, and wait for my approval before you write any code.
Every test loads IRONWORD_LICENSE_KEY into the License.LicenseKey property first.
ExtractText leaves out the text inside tables.
Read the statement table through Tables, Rows and Cells instead.
A reopened file reads GridSpan and MergedCells back empty.
The merged label shows up there as a closing row of two cells.
The suite has to prove these points:
- Each account in Data/accounts.csv gets a table of its transactions.
- The table also holds a heading row and that closing row.
- Cell values and the closing balance match the CSV files.
- Every heading run that holds text is bold.
- The title is bold and 18 point.
- CHK-40902 has the heading and closing rows and no others.
Once I approve, write the tests, run dotnet test and tell me the pass and fail counts.
先有一个计划,您可以在任何断言被写入之前检查套件如何读取合并的单元格和运行的样式。
如何修复无法编译的IronWord样式代码?
IronWord的表格指南通过TextContent上的对象初始值设定项,对单元格的文本进行样式化。 因这些属性是只读的,那个示例在CS0200错误下无法构建。
A teammate adapted @src/Statements/Documents/OverdraftNotice.cs from IronWord's add-table how-to.
Now the solution no longer builds.
Before you edit anything, work through these steps:
1. Build and quote each compiler error.
2. Open the IronWord.xml file inside the IronWord package in the NuGet cache.
3. List the styling members it gives for TextStyle and Run.
Then rewrite just the styling in that file.
The saved notice must keep its bold 14 point heading and its bold amount.
Rebuild and confirm the error count is zero. Don't touch any other file.
编译器报告了标题和金额上的错误,修复中使用的TextStyle成员列在XML查找中。
是什么让云代理能够处理一个问题?
云代理从问题的标题、描述和现有评论中工作,加上分配时提供的任何指令。 根据GitHub的说法,稍后添加的评论从不会传递给代理,所以完成标准应在问题主体中存在。
Title: Show debit amounts in red on statements
The change covers these files and versions:
- Files: src/Statements/Documents/StatementBuilder.cs, tests/Statements.Tests
- IronWord version: the one Directory.Packages.props sets
- Framework: .NET 9
The expected result is this:
- In the Amount column, every negative amount is red (C00000).
- Positive amounts, the heading row and the closing row keep their current color.
- docs/statement-layout.md gains the rule in the pull request text only.
The actual result is that every amount is black.
The constraints are these:
- Keep the Build signature.
- Style the runs as .github/instructions/documents.instructions.md says.
- Add no packages.
The acceptance test is this:
- The current tests still pass.
- A new test reopens CHK-40211.docx and finds red runs in exactly the four debit cells.
因为测试在一个已知报表中计算彩色单元格,所以更改整列颜色会导致测试失败。
为什么云代理的测试在IronWord项目上失败?
默认情况下,云代理在Ubuntu Linux环境中工作。 IronWord 2026.10.4在包中为linux-x64提供了一个本地库,所以在跑者上的NuGet恢复包含它。 跑者没有许可证密钥。 在没有密钥的测试机器上,报表在内存中构建没有错误,并且探测中的每个保存调用抛出了LicensingException,其消息为“需要生产许可证”。 即使代码正确,写入文件的每个测试也会失败。
在Copilot开始工作之前,GitHub Actions从.github/workflows/copilot-setup-steps.yml执行copilot-setup-steps任务。 工作流在默认分支包含该文件前不会触发。
The cloud agent's Ubuntu runner needs .github/workflows/copilot-setup-steps.yml.
GitHub picks up a single job called copilot-setup-steps, so give the file exactly that job.
Set the job up like this:
- Give it read access to the repository contents.
- Trigger it on workflow_dispatch and on pull requests that touch the file itself.
- Fetch the code and install whichever .NET SDK the projects use.
- Run a restore, then build in Release.
Without a license key, every IronWord save throws a LicensingException.
Add a step that checks IRONWORD_LICENSE_KEY, which is an Agents secret.
GitHub documents Agents secrets for the cloud agent's environment.
That includes this workflow when it runs for the agent.
So the check works like this:
- In pull_request and workflow_dispatch runs, it prints a warning and passes.
- In any other run, it exits non-zero with a clear message when the key is empty.
Put that step last, because a failing setup step makes Copilot skip whatever follows it.
Write the file, then show me the finished YAML.
最后放置检查时,仍缺少的秘密会留下一个已恢复和编译的解决方案,外加一行识别问题的线索。
将密钥存储为Agents secret:为Actions、Codespaces或Dependabot保存的secret不会传递给云代理。 在库的设置中,安全性、Secrets 和变量、Agents下添加IRONWORD_LICENSE_KEY,并以环境变量的形式接收。
合并前应检查什么?
用其自己的copilot -p调用开始审查,因此它在与编写代码的其他会话中运行。
/review every change committed after the first commit on this branch.
Hold every IronWord call up against .github/instructions/documents.instructions.md.
Check it against the XML API documentation in the IronWord NuGet package as well.
List each place they conflict.
Also flag any of these:
- styling set on TextContent instead of on runs
- a table cell filled anywhere but on the cell the table already holds
- a closing row that spans its label with MergeCells instead of GridSpan
- a font size with no TextFont beside it
- a test that reads table data with ExtractText instead of reloading the saved file
- any line that prints IRONWORD_LICENSE_KEY
Tell me what you find, and don't edit any file.
在实际运行中这些提示生成了什么?
为本指南创建的报表解决方案中,Copilot CLI无人工参与地运行了所有六个提示。我们重建了每次提交,重新运行了任务和测试,并通过不使用IronWord的脚本读取DOCX文件。
- 队友的通知文件在样式提示前引发了3个CS0200构建错误,而在之后为0。
- 样式修复中只有该文件发生了更改。
- 通知保持其14号粗体标题和粗体金额。
- 所有4个报表从CSV提示开始通过了DOCX检查。
- 所有4个关闭余额与CSV数据一致。
- 每个关闭行有两个单元格,标签跨越两个列。
- 标题为18号粗体。
- 标题行为粗体。
- 行交替为FFFFFF和F2F2F2。
- Copilot的3个测试通过。
- 每个测试通过其行和单元格读取保存的表格。
- 设置工作流解析为YAML,包含一个copilot-setup-steps任务,最后是密钥检查。
- 审查调用未更改任何文件,并在构建器中标记了两个地方。 在路径特定文件指定的情况下,在添加行之前填充关闭行的单元格。 另一种是使用TableCell.SetContent而不是AddChild或AddText。
- 有些步骤与页面中的运行不一样。 会话是无界面的,所以计划模式使用--plan标志,批准是一个键入的回复。 问题、云代理、Agents secret和设置工作流需要一个托管库且未运行。
Cursor指南将其IronWord规则作用域限制为具有glob的文件模式,正如这里路径特定指令文件使用applyTo那样。 Google Antigravity指南为linux-x64发布了一个IronWord页面,这是云代理运行的平台。
Copilot CLI版本、Auto选择的模型、测试机器和运行时长出现在共享运行记录中。
故障排除
- 将表格添加到DOCX用于行、单元格、边框和阴影
- 在DOCX中样式化文本用于字体、大小和粗体文字
- 从DOCX中提取文本用于段落文本和每个单元格的表格提取
- 应用许可证密钥用于从代码、Web.config或appsettings.json中设置密钥
- Docker中的IronWord用于Linux运行程序和容器
有问题吗?
如果您有任何问题,请联系support@ironsoftware.com
Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。