如何使用IronWord與GitHub Copilot

Curtis Chau
Curtis Chau
已更新: 2026年10月19日

.NET服務可以生成月度帳戶聲明作為Word文件,每個文件都有一個設計的標題、兩行摘要和一個由數據構建的表格。 在本指南中,該服務駐留在Visual Studio解決方案中,與提供其數據的作業並列,因此任何修改它的助手必須在同一解決方案中工作。

GitHub Copilot可以從Visual Studio或VS Code中的聊天或代理模式在這個解決方案上工作,並從帶有Copilot CLI的終端和從GitHub中,透過其雲端代理開啟分配給它的問題的pull request。 IronWord在代碼中構建DOCX,具有設計的文本運行和表格,這些表格具有合併的單元格和陰影行。 IronWord規則保存在存儲庫中的指令文件中,並且這些表面中的每一個都會閱讀它們。

表格指南和文本樣式指南涵蓋了此指南依賴的API的兩個部分。

快速開始
NuGet使用NuGet安裝

PM > Install-Package IronWord

在 NuGet 包管理器控制台中運行上述命令安裝 IronWord,或在 NuGet 包管理器中搜索該包。

從解決方案根目錄啟動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.
Text

提示未命名任何樣式成員。 下面的路徑專用指令文件指定要使用的成員。

解決方案的Program.cs從環境中讀取IRONWORD_LICENSE_KEY並將其分配給IronWord.License.LicenseKey,所以啟動Copilot之前設置此變量。 授權金鑰指南顯示了相同的分配和可以保存金鑰的配置文件。



如何為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.
Markdown

如何為文檔代碼規範設置自己的規則?

僅適用於某些文件夾的規則放在一個路徑專用的文件中,如.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.
Markdown

該文件中的每條規則均源自一個構建、一個內存檢查或一個保存的文件。出貨的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.
Text

夾具包含四個帳號,有五個、兩個、三個和零個交易。 在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.
Text

首先有一個計劃時,您可以檢查套件如何讀取合併單元格和運行的樣式,而不寫任何斷言。

如何修復無法編譯的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.
Text

編譯器報告標題和金額出錯,XML查找列出了修復所使用的TextStyle成員。

使雲代理可以操作的問題具備什麼條件?

雲端代理從問題的標題、描述和現有評論中工作,外加分配時提供的任何指令。 根據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.
Markdown

由於測試在一個已知聲明中計算彩色單元格,因此對整個列著色的更改將導致測試失敗。

為什麼雲端代理的測試在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.
Text

檢查放置在最後時,缺少的機密仍然留下了一個恢復和編譯的解決方案,此外還有一行指出問題所在。

將金鑰存儲為代理密鑰:存儲在Actions、Codespaces或Dependabot中的機密不會傳送給雲端代理。 在儲存庫的設置下的安全、機密和變量、代理選項中添加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.
Text

在實際運行中,這些提示產生了什麼結果?

Copilot CLI在為本指南建立的聲明解決方案上自動運行了所有六個提示。我們重建了每個提交,重新運行了任務和測試,並使用不使用IronWord的腳本讀取了DOCX文件。

  • 隊友的通知文件在樣式提示之前造成了3次CS0200構建錯誤,之後為0次。
  • 僅該文件在樣式修復中更改。
  • 通知保留了其粗體14點的標題和粗體金額。
  • 從CSV提示開始,所有4份聲明通過了DOCX檢查。
  • 所有4個結餘都符合CSV數據。
  • 每個結束行都有兩個單元,標籤跨越兩列。
  • 標題是18點的粗體。
  • 標題行是粗體。
  • 行交替使用FFFFFF和F2F2F2。
  • Copilot的3次測試通過了。
  • 每次測試都是通過其行和單元格讀取保存的表格。
  • 設置工作流程解析為YAML,包含一個copilot-setup-steps任務,最後是金鑰檢查。
  • 審查調用未更改文件,並在構建器中標記了兩個位置。 一個在添加行之前填充結束行的單元,如路徑專用文件所指定。 另一個使用TableCell.SetContent,而不是AddChild或AddText。
  • 一些步驟與頁面上運行的不同。 會話以無頭運行,因此計劃模式使用--plan標誌,並且批准是鍵入的回覆。 問題、雲端代理、代理密鑰和設置工作流程需要一個托管的存儲庫且沒有運行。

Cursor指南使用通配符將其IronWord規則限定在文件模式上,如此處路徑專用指令文件中的applyTo一樣。 Google Antigravity指南發布了一個IronWord頁面,適用於其運行的linux-x64平台的雲端代理。

在共享運行記錄中,顯示了Copilot CLI版本、Auto挑選的模型、測試機和運行的持續時間。


疑難排解


問題?

如果您有任何疑問,請聯繫support@ironsoftware.com

Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。

閱讀更多

準備好開始了嗎?

NuGet 下載次數 62,392版本:2026.11剛剛發布