如何在.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

在正文文本之前查看表格输出。 承保行处于重复区域中,只有区域调用会填充该区域。



Claude Code在.NET Word文档项目中做些什么?

Claude Code编写合并服务,并从两个CSV文件中生成每个政策的一封信。 然后它重新打开每封保存的信函并检查。 当检查失败时,它会修订合并代码并重新运行批处理。 开发人员决定正确信函内容,并在最后查看审计文件。

在第一个提示中命名IronWord包及其版本。 攻击者注册恶意包,使用语言模型幻觉的包名,这种技术称为slopsquatting。

如何设置Claude Code?

Anthropic的快速开始涵盖了安装和登录。 设置完成一旦claude在终端中打开并响应。

如何设置一个Claude Code可以工作的项目吗?

首先在存储库中放置真实输入。本指南使用的测试解决方案包括一个可以编译的.NET 9控制台应用程序、一个包含续保信函及其合并字段的Templates文件夹,以及一个包含客户CSV和一个按保单号键控的承保行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中的新子代理文件,但监视器仅覆盖启动时存在的文件夹,因此在启动会话之前创建该文件夹。 对于超出成员列表的文档,代理可以从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还列出了非公共成员,所以那里的名称仍可能因CS1061错误而失败,因为在探讨中两个WordDocument成员发生了这种情况。
  • 模板:在批处理之后与其提交的副本进行比较。 在我们的授权探讨中,没有参数的单次保存将模板替换为第一个客户合并的信函,因此每次随后加载该文件时都没有要填充的字段。
  • 页眉: 页眉故障排除页面告诉读者打开自己的输出并检查页眉。 同一探讨发现,每次保存调用精确地保存了页眉和页脚字节。

AI编码助手指南包含一个完整的IronWord任务,其通过标准已固定,因此任何读者都可以重新运行它。

在实际运行中这些提示生成了什么?

Claude Code在一个会话中按顺序运行四个提示。 邮件合并块在提示3之前进入CLAUDE.md。没有代码是手动编辑的。 数据包含五个客户和十个承保行。 干净的Release重建生成了相同的审计文件。我们的包检查匹配每一行。

  • 快速开始信仅用值合并,保留了页眉行和一个空行。
  • 所有5封批量信函通过了首次审计。
  • 信函持有3、1、4、0和2个承保行,与CSV一致。
  • 预检报告一个没有数据列的字段ReferenceCode。
  • 在所有5个页眉中保持了政策编号字段。
  • 每个页脚与模板匹配。
  • 4 个测试中的 4 个在 IRONWORD_LICENSE_KEY 不存在于进程中时通过。
  • 子代理未发现IronWord.xml中遗漏的IronWord成员。
  • 批处理后模板的散列未更改。
  • 每个提示都以干净的Release构建结束。
  • 本次运行的每个记录、会话文件和存储库文件中都没有许可密钥。
  • 在提示1和4中,一个shell测试仅打印密钥是否设置。
  • 有些步骤与页面中的运行不一样。 由于会话无头运行,操作员通过输入的回复批准了提示3计划。 提示3将快速开始的SaveAs调用更改为Save以遵循CLAUDE.md。

Cursor指南中,Cursor在编辑任何文件之前也会进行计划,并将计划写入可编辑的文件中。 ChatGPT Codex指南在AGENTS.md中存储其常驻指令,Codex的对应文件为CLAUDE.md。

共享的运行记录提供了此次运行的Claude Code版本、模型、持续时间和测试机。


故障排除


有问题吗?

如果您有任何问题,请联系support@ironsoftware.com

Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。

阅读更多

准备开始了吗?

NuGet 下载量 62,392版本:2026.11刚刚发布