如何在.NET Word文件專案中使用IronWord與Claude Code

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

每年11月,保險公司會向其保單持有人發送續保信件。 合規團隊管理信函措辭的單一Word範本,並從保單系統中獲取姓名、日期、保費和覆蓋細節。 合併後看似完整的信函並不證明合併成功。 在這份指南背後的測試中,合併留下了空白的覆蓋行、遺失了參考號或者重用了第一位客戶的數據,所有這些都完成而未拋出例外。 Claude Code 是Anthropic推出的一款自主編碼工具,可讀取代碼庫、編輯檔案,並從終端、VS Code、JetBrains IDE、桌面應用或瀏覽器運行命令。

IronWord使用字典、數據行或數據集填充DOCX範本中的MERGEFIELD佔位符,並支持表格行的重複區域。 它不需要Microsoft Office。合併僅需幾行代碼。 呼叫順序和預設選項決定了輸出的正確性,某些錯誤會產生錯誤的輸出但不會拋出例外。 以下測試的四個提示設置Claude Code生產一批續保信函,每個提示後面都是IronWord依賴的行為。

快速開始
NuGet使用NuGet安裝

PM > Install-Package IronWord

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

在專案目錄中啟動claude並運行/model opusplan一次,在任何提示之前。 路徑前的@包括該文件的內容進入請求。

Add the IronWord NuGet package, version 2026.10.4, to RenewalLetters.csproj.
Then write one renewal letter in Program.cs.

Merge the first customer row of @Data/customers.csv into @Templates/renewal-letter.docx.
Save the letter to out/letters/NM-104233.docx.
Create that folder first, and pass the path to the save call.
Don't change the template file.

Next, open the saved letter in a new WordDocument and print these in order:

1. The body text.
2. The text of every table cell, row by row, with each cell cast to TableCell to read it.
3. The names of any merge fields still in the document, or "none".

My license key is in the IRONWORD_LICENSE_KEY environment variable.
Have the program read that variable itself and apply the key before the first IronWord call.
Don't print, echo or save the key anywhere.
Don't list environment variables to look for it either.
Tell me whether it's set and nothing more.
Text

在正文之前檢查表格輸出。 覆蓋行在重複區域中,只有區域呼叫會填充。



在.NET Word文件專案中,Claude Code 該做什麼?

Claude Code 撰寫合併服務,並從兩個CSV文件中產生每份保單的信函。 然後重新打開每封保存的信件並進行檢查。 當檢查失敗時,它修訂合併代碼並重新運行批次。 開發人員決定正確的信函包含什麼,並在最後審核審核文件。

在第一個提示中指定IronWord套件及其版本。 攻擊者使用語言模型生成的套件名稱註冊惡意套件,這種技術稱為slopsquatting。

您如何設置Claude Code?

Anthropic的快速入門介紹了安裝和登入。 一旦終端中打開了claude並回應,設置就完成了。

如何設立一個Claude Code可以工作的項目?

首先將真實的輸入放入儲存庫。此指南中使用的裝置包括一個能編譯的.NET 9 console 應用程式、一個包含合併欄位的續保信件範本的Templates資料夾,以及一個包含客戶CSV和按保單號鍵的覆蓋行數據的Data資料夾。

Claude Code在每次新會話加載CLAUDE.md,因此其規則適用於所有後續的提示。快速入門安裝套件後,第二個提示創建該文件和用於合併代碼的審查者。

Create CLAUDE.md in the repository root and give it a section called Mail merge.
Every later session should find these rules in it:

- IronWord is the only DOCX library this project may use.
- The NuGet package is IronWord, at the version RenewalLetters.csproj references now.
- Look up IronWord member names in docs/IronWord.xml.
- Templates/ is read-only, and each letter starts from a new load of the template file.
- The license key rules from my first message, written out in full.
- A letter isn't finished until the saved file has been reopened and checked.

Copy docs/IronWord.xml now from the ironword folder of the local NuGet cache.
If the file isn't there, stop and say so.

Then add a subagent at .claude/agents/merge-auditor.md.
Give it the Read, Grep and Glob tools and no others.
Its job is to list every IronWord type and member used under Services/.
It should name each one that docs/IronWord.xml doesn't document.
IronSoftware.* types such as ITableCell are documented in other packages.
Have it list those separately, so it doesn't call them missing.
Text

Claude Code監看.claude/agents的新增subagent文件,但監看只覆蓋啟動時在的資料夾,因此在啟動會話前創建該資料夾。 有會員清單之外的文件,可以從IronWord的llms.txt開始,該文件鏈接了指南和故障排除頁面。

第一次保存前解決授權問題。 若無金鑰,則每次保存呼叫都會拋出LicensingException,顯示"需要生產授權"。 這適用於Save無論是否有路徑或串流,也適用於SaveAs。 IronWord授權金鑰頁面涵蓋試用和付費金鑰,以及如何在代碼中或配置文件中設置金鑰。

哪些IronWord郵件合併規則應該在CLAUDE.md中?

一個對裝置範本的探查檢查了每條與IronWord 2026.10.4的對比,最後三個使用了授權金鑰。 將區塊添加到郵件合併部分下。

IronWord 2026.10.4 behaves this way in a mail merge:

- MailMerge.Execute(DataTable) merges the first row only.
- Merge each row into its own WordDocument, loaded fresh from the template file.
- A merge removes the fields it fills, so a second Execute on the same document changes nothing.
- Call ExecuteWithRegions before Execute.
- Execute removes any region it has no table for, because RemoveUnusedRegions defaults to true.
- That region's row then stays in the table with empty cells.
- A region table with no rows removes the region row and keeps the rest of the table.
- RemoveUnusedFields defaults to true, so a field with no matching key is deleted with no error.
- Compare GetFieldNames() with the data columns before merging.
- Field names match without regard to case unless CaseInsensitiveFieldNames is set to false.
- NullValueReplacement replaces DBNull values. An empty string merges as an empty string.
- WordDocument.ExtractText() returns body paragraphs only, joined with no separator.
- ExtractText() skips table cells, the header and the footer.
- Rows[i].Cells holds ITableCell values, which have no ExtractText().
- Cast each cell to TableCell before calling ExtractText() on it.
- GetFields() and GetFieldNames() don't see merge fields in the header.
- Save each letter with Save(outputPath).
- One troubleshooting page reports a header that SaveAs(outputPath) dropped and Save kept.
- Never call Save() with no argument. It overwrites the file the document was loaded from.
Markdown

未使用的字段規則在探查中產生了最不明顯的失敗。 範本包含"參考",後接一個 客戶文件中沒有對應欄的參考代碼字段,默認合併將句子改為"參考 。"。 在呼叫我們時引用這個號碼。"。

如何合併具有重複表格行的Word範本?

用共享區域名稱的開始字段和結束字段在範本中標記重複行。 在裝置範本中,覆蓋行以TableStart:Coverages開始,TableEnd:Coverages結束。 區域呼叫接受一個名稱與區域匹配並為每個數據行複製一次的數據表。 然後,值呼叫用字典或單一數據行填充區域外的每個字段。

郵件合併指南記錄了每個重載和合併選項。

如何提示可編譯的IronWord代碼?

合併器及其審計需放在一個提示中,以計劃模式發送,以便在更改任何文件之前確定設計。 用Shift+Tab循環到計劃模式,一旦狀態欄顯示就發送提示。 使用opusplan,Opus處理計劃,Sonnet在批准後編寫代碼。

Build the batch in Services/LetterMerger.cs and Services/LetterAudit.cs.
Run both from Program.cs after the Quickstart letter.

LetterMerger reads @Data/customers.csv and @Data/coverages.csv.
For each customer it does this:

1. Loads Templates/renewal-letter.docx again.
2. Fills the Coverages region with that policy's rows, if any.
3. Fills the other fields from the customer row.
4. Saves out/letters/<PolicyNumber>.docx.

Before the first merge, it prints each template merge field with no column in either CSV.

LetterAudit opens each saved letter from disk and passes it when these all hold:

- Every customer value appears in the body text.
- The coverage table holds only that policy's rows, in CSV order.
- word/document.xml, read as a zip entry, has no merge field or MERGEFIELD instruction left.

For an empty customer value, check its whole sentence.
One case is the agent sentence with no phone number.

Two more columns don't count toward a pass:

- Header, from word/header1.xml: shows the policy number, still has the merge field, or is missing.
- Footer, from word/footer1.xml: matches the template's footer, changed, or is missing.

Write out/letter-audit.csv with one row per letter.
Print how many letters pass.
After the batch, run git status on Templates/ and tell me about any change.

Don't use a docx skill or rewrite any package XML by hand.
The audit can read parts as zip entries.
Keep fixing the merger until every letter passes.
If a header keeps its field, tell me whether any IronWord call reached it.
Then have the merge-auditor subagent review Services/.
Text

提示中有兩部分取決於IronWord和Claude Code的行為。

  1. 審計讀取已保存的套件:標題和頁腳不包含在提取的文本或字段清單中。其列從通過計數中排除,因為沒有IronWord合併呼叫填充標題,因此計數它會引導代理進入提示中禁止的XML解決方案。
  2. 只讀評論員:自定義代理裝載CLAUDE.md,所有內建代理除Explore和Plan外也載入,因此合併-審計員檢查Services/對照郵件合併規則檢查。
提示: 僅在計劃加載客戶循環內的範本並在值呼叫前放置區域呼叫時批准計劃。 加載範本一次的計劃會產生五份副本的第一封信。

可以在沒有授權金鑰的情況下測試IronWord合併代碼嗎?

可以,只要測試在保存之前停止。 加載範本、合併範本、和讀取回文字都以未授權狀態運行,因此沒有金鑰的建置代理仍然可以運行合併測試。

Add a RenewalLetters.Tests xUnit project that tests LetterMerger without writing any file.

Merge NM-104267 and NM-104288 in memory.
Assert the body text and every coverage table cell against the CSV rows.
Cover the policy with no coverage rows and the agent sentence with an empty phone number.

A few things about the setup:

- Split the merge from the save in LetterMerger if a test needs that.
- Leave the license key unset when the variable is missing.
- Put the test project in its own folder, with no solution file at the repository root.
- Keep RenewalLetters.csproj from compiling the files in that folder.
- Have the test project copy Templates/ and Data/ to its output folder.

Run dotnet test on the test project once, in a child process with no IRONWORD_LICENSE_KEY variable.
Show me the tests passing without a key.
Text

信任生成的IronWord代碼之前,您應該檢查什麼?

將每個值與提取出來的正文文本進行包含測試比較,因為其段落返回時之間沒有斷行。

向審查中添加三個檢查。

  • 構建: dotnet build在IronWord缺少的任何成員名稱上失敗。 發送的IronWord.xml也列出未公有的成員,因此那裡找到的名稱仍可能會因為兩個WordDocument成員在探查中而失敗的CS1061。
  • 範本:在批次後與其提交副本比較。 在我們授權的探查中,單次保存無參數替換首個客戶合併信件範本,因此該文件的每次後續加載都不包含要填充的字段。
  • 標題: 標題疑難排解頁告訴讀者打開自己的輸出並檢查標題。 相同探查發現每次保存呼叫都逐字節保存標題和頁腳。

AI編碼助手指南包含完整的IronWord任務,其通過標準已固定,因此任何讀者都可重新運行。

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

Claude Code在一個會話中按順序運行了四個提示。 郵件合併區塊在第三個提示之前進入CLAUDE.md。沒有代碼手動編輯。 數據包含五位客戶和十條覆蓋行。 一個乾淨的Release重建產生相同的審核文件。我們的套件檢索匹配每一行。

  • Quickstart信件,僅合併值,保持標題行和一個空行。
  • 所有5封批次信通過首個檢閱。
  • 信件保持3、1、4、0、和2條覆蓋行,如CSV中。
  • 預飛報告一個無數據欄的字段,ReferenceCode。
  • 所有5封信函保險號欄留在標題中。
  • 每個頁腳與範本相符。
  • 4 個中的 4 個測試通過,且未提供 IRONWORD_LICENSE_KEY。
  • subagent未找到IronWord.xml中遺失的IronWord成員。
  • 批次後範本的哈希值未更改。
  • 每次提示最終以乾淨的Release構建結束。
  • 此運行中,每個成績單、會話文件及儲存庫文件中金鑰都不存在。
  • 在提示1和4中,shell測試僅打印金鑰是否設置。
  • 一些步驟與頁面上運行的不同。 因為會話在無頭環境下運行,操作員用鍵入的回覆批准了第三個提示計劃。 提示3依照CLAUDE.md把Quickstart的SaveAs呼叫改為Save。

在游標指南中,游標在編輯文件前也會計劃,並將計劃寫入可編輯文件中。ChatGPT Codex指南將其常設指令儲存於AGENTS.md中,Codex是CLAUDE.md的對等者。

共享的運行記錄提供此運行的Claude Code版本、模型、持續時間、和測試設備。


疑難排解


問題?

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

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

閱讀更多

準備好開始了嗎?

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