利用AI编程助手使用IronWord

Curtis Chau
Curtis Chau
更新: 2026年10月26日

IronWord是Iron Software的.NET DOCX库。 它允许您在Word文档中创建、编辑、样式化和构建表格,并在没有微软Office的情况下读取文本。IronWord自2023年12月以来在NuGet上提供,包含公共指南和代码示例。

当前示例不反映2026.10.4版本的行为。在此版本中,文本元素的大小、颜色和粗细为只读。 全局替换不影响表格单元,全局文本提取排除表格。

AI编程工具有两种类型。

  • 助手在编辑器中操作。 它们完成行或重写方法,类似于GitHub Copilot的内联建议。
  • 代理管理完整的任务,例如编辑多个文件、运行构建和程序,并返回结果供审核,类似Claude Code、Cursor、ChatGPT Codex和Google Antigravity。

两种类型都需要相同的设置,无论任务是添加文本、样式化、构建表格、替换占位符或提取文本。 安装IronWord包,从环境变量读取密钥,给助手IronWord的机器可读文档,并在任务完成前重新打开每个已保存的DOCX。

Claude Code标志ChatGPT Codex标志GitHub Copilot标志Cursor编辑器标志Google Antigravity标志

我的AI助手不能自己处理Word文档吗?

没有文档,助手从覆盖其他DOCX库和旧版IronWord版本的训练数据来写IronWord代码。 IronWord的机器可读文档为其提供当前API。

一页信件很简单。 DOCX库之间的差异在模板、表格和大规模生成中显现。

  • 错误文档没有错误保存:当一条线合并到上一个段落或占位符留在表格单元中时,IronWord不引发异常。 只读取保存的文件才能发现故障。
  • 原始OpenXML需要每个功能的低级代码:运行、运行属性、表格和部分设置是独立的XML元素,而OpenXML SDK为每个都有一个类,因此助手编写的代码很长,您需要维护。 IronWord通过一个对象模型来暴露它们。
  • 包和命名空间共享一个名称:两者都是IronWord,模型类型位于IronWord.Models下。 注册助手幻想的包名称为slopsquatting,因此提示应该给出准确的包名。
  • 许可条款提前定义:IronWord许可为永久性,许可页面给出了每个层的开发者、地点和项目的限制。

步骤1:安装IronWord

让助手安装包。

Install IronWord 2026.10.4 from NuGet in this project and restore it.
Then tell me the IronWord version the restore picked.
Text

从终端固定一个版本。

dotnet add package IronWord --version 2026.10.4
SHELL

单个包支持Windows、Linux和macOS,因为IronWord 2026.10.4包含了win-x64、win-x86、linux-x64、osx-x64和osx-arm64的本地布局引擎。Docker设置指南推荐使用Ubuntu、Debian或RHEL基础镜像,并涵盖了在Linux容器中安装字体。


步骤 2:应用您的许可证密钥

一个未授权的程序仍然可以创建文档、加载一个、提取其文本并在内存中替换单词,但每次保存都会引发IronSoftware.Exceptions.LicensingException,消息为需要生产许可证。 这包括SaveAs和每种形式的Save,到路径、流或字节。 键入错误的密钥会使保存失败,出现未识别的许可证密钥。 可以在下方请求免费试用密钥。

从今天开始在您的项目中使用 IronWord 免费试用。

第一步:
arrow pointer

在启动时一次性设置密钥,在任何IronWord调用前。 从环境变量读取可保持其不在存储库中。

IronWord.License.LicenseKey = Environment.GetEnvironmentVariable("IRONWORD_LICENSE_KEY");
C#

当分配的密钥有效时IronWord.License.IsLicensed为真,而IronWord.License.IsValidLicense测试一个密钥字符串。 异常类不是公共的,因此捕获Exception并读取其消息。

请注意: IronWord许可证密钥还解释了Web.config和appsettings.json选项。

步骤3:将您的助手指向IronWord的LLM文档

  • llms.txt每页有一行条目。 每次会话开始时交给助手。
  • llms-full.txt将所有46个文档页面的摘要放在一个文件中。
  • llms-full-catalog.txt将博客文章添加到索引中。
  • API参考给出每个成员的声明。
  • skill.md用于加载技能文件的工具。 它涵盖安装、许可、代码示例和常见故障表。
  • AI产品概况表列出了支持的.NET目标和主要用例。

当任务依赖于特定指南时,请命名具体指南。

Read https://ironsoftware.com/word/csharp/llms.txt before you touch IronWord code.
Use only what those pages show.

Here's how the object model works:
- A document is a WordDocument made of paragraphs, runs, and tables.
- Styling goes on the run through a TextStyle.
- Nothing reaches disk until the document is saved.

If you need a member the pages don't mention, look it up in the API reference.
It's at https://ironsoftware.com/word/csharp/object-reference/api/.
Build once to prove the call compiles.
If it still looks doubtful, tell me so instead of guessing.
Text

获得回答“未记录”的许可时,助手有另一个选择而不是编造方法。


步骤4:将IronWord上下文添加到您的项目

在聊天室中键入的指令在会话结束时消失,所以将IronWord规则保存在工具加载的项目文件中。 该文件是Claude Code的CLAUDE.md,ChatGPT Codex的AGENTS.md,GitHub Copilot的.github/copilot-instructions.md,Cursor的.cursor/rules/中的.mdc文件或AGENTS.md,以及Google Antigravity的AGENTS.md或GEMINI.md。 一个文本块适用于所有这些,尽管Cursor的规则文件也接受MDC前言。

All DOCX work in this project uses IronWord.
The NuGet package and its namespace are both `IronWord`.
Model types live in `IronWord.Models`.

Follow these rules for every Word document:
- Start from the docs index at https://ironsoftware.com/word/csharp/llms.txt.
- Load the skill file from https://ironsoftware.com/word/csharp/skill.md.
- Build documents from `Paragraph`, `Run`, and `Table` objects.
- Add each one with `AddParagraph` or `AddTable`.
- `WordDocument.AddText` appends to the last paragraph rather than starting a new one.
- Style a run with `Run.Style = new TextStyle { ... }`.
- Give the style a `TextFont` whenever it sets `FontSize`.
- Size, color, and weight on `TextContent` are read-only.
- `WordDocument.ReplaceText` does not reach table cells.
- Replace placeholders paragraph by paragraph across `doc.Paragraphs`.
- That list includes the paragraphs inside table cells.
- Read body text from top-level paragraphs.
- Read table text from `Tables`, `Rows`, and `Cells`, and cast each cell to `TableCell`.
- `WordDocument.ExtractText` leaves out tables and joins paragraphs without a separator.
- Build a new `WordDocument` for each file you save. A second save writes the body again.
- Set `IronWord.License.LicenseKey` from IRONWORD_LICENSE_KEY at startup.
- Never print the key or write it into a file.
- Reopen every saved document before calling a change done.
- Compare its paragraphs and cells with what was written.
- Do not add a second DOCX library. If IronWord cannot do something, say so.
Markdown

技能文件在至少七处与测量结果不一致。 其单文件示例仍使用2026.8.1,比NuGet上的2026.10.4包提早三个版本。 它将全文件替换称为整篇文档查找和替换,这与下文的测量结果相矛盾。 其示例将文档模型序列化为JSON,这在2026.10.4测试的每个文档上导致了序列化错误。他们仅将无参数的Save作为获取字节的方式,尽管IronWord.xml指出它还将加载的文档写回其源文件。技能文件通过TextContent.Style样式化文本,保存了一个空的运行样式。 第7步涵盖了另外两个,文档的添加文本调用和发货的XML。


步骤5:一次性设置提示

以下提示将第1到第4步合并为一个开篇消息。

Prepare this project for Word document work with IronWord.
Then append these rules to the instruction file your future sessions load:
- Reference the IronWord NuGet package at version 2026.10.4.
- Its namespace is also IronWord.
- The paragraph, run, table, and style types live in IronWord.Models.
- Take IronWord.License.LicenseKey from the IRONWORD_LICENSE_KEY environment variable.
- Assign it before any IronWord call.
- Never print the key, and keep it out of every file you write or commit.
- Fetch https://ironsoftware.com/word/csharp/llms.txt first and code against what it documents.
- Look up any other member in the API reference.
- It lives at https://ironsoftware.com/word/csharp/object-reference/api/.
- Confirm that member in a build before you rely on it.
- Where the tool supports skill files, load https://ironsoftware.com/word/csharp/skill.md.
- Believe the compiler over the skill when they disagree.
- After any change that saves a DOCX, reopen that file with IronWord.
- Compare each paragraph and table cell with the text you meant to write.

Tell me which file you appended them to.
Text
提示: 之后,请打开步骤4的项目文件并确认其中包含规则。

步骤6:产生可用代码的提示模式

指定段落、样式和表格。

模糊 用IronWord制作Word报告。

更好 将标题作为其自己的段落添加,其运行具有20点粗体Calibri的TextStyle,附加每个主体段落使用AddParagraph,然后添加一个每个度量单位一行的两列表格。

声明IronWord版本和目标框架,因为成员在不同版本之间发生变化。

更好 在.NET 9上使用IronWord 2026.10.4,并在首次保存之前从IronWord_LICENSE_KEY设置许可证密钥。

要求完整文件。 代码片段可以省略段落、运行和表格类型需要的IronWord.Models指令,或设置密钥的行。

更好 返回完整的Program.cs,包括使用指令和许可证分配,以便它可以不变地构建。


步骤7:验证收到的内容

以下每个错误均可在2026.10.4中重现。

  • 对文本元素进行样式化:TextContent上的大小、颜色、粗细和字体名仅报告有效样式,而Run上的大小和字体名也是只读的,因此分配它们会因CS0200失败。将一个TextStyle应用于运行代替。
  • 用文档自带的添加文本调用构建段落:WordDocument.AddText附加到最后一个段落而不是开始一个新段落。
  • 将发货的XML视为API:技能文件指示代理在IronWord.xml中搜索成员名称,但在2026.10.4中,该文件记录的成员非公开,如段落上的跨运行替换方法和文档上的Markdown导出,并省略了范围在页面级的文本提取,它确实编译。 调用隐藏的成员会因CS1061失败。
  • 一次保存一个文档两次:内存中构建的文档的第二次保存会在第一份拷贝后再写入其全部正文,因此具有三个段落和一个表格的通知会以六个段落和两个表格保存。 为每个保存的文件构建新文档。
  • 编辑包含表格的已加载文档:当加载并保存包含表格的DOCX时,表格内或后面段落的替换被悄然丢失,尽管内存中的文档显示了它。 在内存中构建的文档和没有表格的已加载文档保留其编辑。

让代理验证其自己的工作

代理可以运行相同的检查并报告每个结果。

Rebuild in Release and run it.
If it's a web app, start it in the background.
Call each endpoint that saves or returns a DOCX, then stop the app.

After that, show me the evidence:
- Name each IronWord type and member the code calls, with the docs page where it appears.
- Report the value of IronWord.License.IsLicensed.
- Reopen each DOCX the program produced.
- Count the paragraphs outside tables and the table rows in each file.

For every paragraph and cell in each file, list the text written and the text found.
Say whether the two agree.
Text

使用IronWord提取文本

在2026.10.4中,提取调用返回不同的结果。

  • 文档的文本提取连接正文段落而无分隔符,并且不返回表格文本。
  • 其段落列表保存正文段落和每个表格单元段落,按文档顺序。
  • 表格行保存类型为接口的单元,故将每个单元强制转换为TableCell以读取其文本。
  • 单元自身的文本提取将其段落连接而无分隔符。

对于一个具有标题、一个正文段落和四行表格的报告,段落列表返回10个条目,其中8个是表格单元。 单元段落有一个TableCell父级,因此读者可以将正文与表格文本分开。 文本提取指南展示了如何读取单元。


使用IronWord替换占位符

一个加载的通知在两个正文段落和一个表格单元中保留了CUSTOMER_NAME,第一个正文副本分为两个运行。 IronWord 2026.10.4在内存中以三种方式替换了它。

替换调用正文段落表格单元
文档上的ReplaceText已替换,包括跨运行分割的副本未改变
每个Paragraphs条目上的ReplaceText已替换已替换
每个表格单元上的ReplaceText未改变已替换

分割的副本在加载的文件中被替换,因为IronWord在加载时合并相邻的纯文本运行。 在内存中从两个运行构建的段落也在分割过程中被替换。 对于MERGEFIELD模板,邮件合并指南涵盖了单独的合并API。


一个您可以重复的结果

整个测试即为下面的提示,助手编写所有代码。 打开一个空文件夹,在那里启动一个新会话,并粘贴提示。 然后将结果与“通过标准”下的标准进行比较。

请注意: 在开始之前,安装.NET 9 SDK并在IRONWORD_LICENSE_KEY中设置IronWord试用或生产密钥。 助手需要网络访问权限和运行终端命令的权限。

提示

Build a .NET 9 minimal API that writes internal report documents as DOCX and reads them back.
Start in an empty directory. If it holds a project file or code, say so and stop.
No one can answer questions, so plan, code, build, run, and repair on your own.
Settle open points sensibly and write each choice down.
Keep every deliverable in the project directory.

Do these steps in order:
1. Install IronWord 2026.10.4 from NuGet as the only DOCX library, and write every DOCX with it.
2. Use only members in https://ironsoftware.com/word/csharp/llms.txt, its guides, or API reference.
3. At startup, assign IRONWORD_LICENSE_KEY to IronWord.License.LicenseKey.

The key follows these rules:
- Never view, print, echo, hard-code, or save it, or list the environment.
- If IronWord.License.IsLicensed is false, report that and stop.

4. Add POST /documents and POST /extract.

POST /documents takes JSON and returns a DOCX built like this:
- The title is one paragraph, bold at 20 point.
- Each body paragraph is its own paragraph.
- Optional label and value rows form a two-column table.
- An absent or empty row list gives no table.

POST /extract takes one DOCX upload and returns JSON with two fields:
- "paragraphs" lists paragraphs outside tables that hold text, in document order.
- "rows" holds one array of cell texts per table row.

5. In process, write 8 DOCX files to testset/ with the /documents code and title style.

The set holds these files:
- letter-01 to letter-03: a title and three body paragraphs.
- report-01 to report-03: a title, one body paragraph, and five label and value rows.
- notice-01 and notice-02: a title, two body paragraphs, and a two-row table.
- After replacement, no title, body paragraph, or table row repeats in the set.
- manifest.json gives each file's title, customer name, and replaced paragraphs and rows.

Build each notice this way:
- Its rows are Reference and an ID you pick, then Customer and CUSTOMER_NAME.
- Body paragraph one is "Dear CUSTOMER_NAME," as the runs "Dear CUSTOMER_" and "NAME,".
- Body paragraph two mentions CUSTOMER_NAME again.
- Extend the /documents code so it takes runs.
- Save the notice as built to pre-replacement/notice-01.docx or pre-replacement/notice-02.docx.
- Replace each CUSTOMER_NAME with its customer name through IronWord's ReplaceText.
- Only then save it to testset/.

6. Before /extract is first called, check each testset file's word/document.xml yourself.

Fix the generator whenever a check fails.
Once /extract code reads a testset file, over HTTP or in process, the testset is final.
Open it as a ZIP with only System.IO.Compression and System.Xml.Linq, and pass these checks:
- The first paragraph's run is bold at 40 half-points.
- Paragraphs outside tables that hold text match the manifest in number and text.
- So do table rows.
- CUSTOMER_NAME and CUSTOMER_ occur nowhere in it.
- Each pre-replacement notice keeps body paragraph one in exactly those two runs.

7. Make /extract read every upload with IronWord, the same way each time.

The /extract code has these limits:
- It uses no other DOCX reader, no ZIP or XML parsing, and not the manifest.
- It holds no title, paragraph, label, value, or customer name as a literal.
- It never picks a reading by comparing it with expected text.
- You may change how it reads between runs. The program may not.

8. Build in Release and launch the API.

Then make these requests in order:
- Send /documents your own title, four rows, and two body paragraphs, none from the testset.
- Save the returned DOCX as report.docx.
- POST report.docx and every testset file to /extract over HTTP.
- Save each raw response body as extract/<file name without .docx>.json.

9. Write roundtrip.md in three parts.

Part one gives each file's step 6 values, with report.docx measured against your request.
Give title size in half-points and placeholders as CUSTOMER_NAME or CUSTOMER_ occurrences.
Part two describes the /extract method and the ReplaceText calls that made the replacements.
Part three is a 50-row table, one row per expected title, body paragraph, and table row.
Its columns are File, Element, Expected text, Text read, and Match, filled this way:
- Element is title, paragraph N, or row N.
- Expected text comes from the manifest or the request.
- Text read is copied from the saved response, wrong or not, or is (missing) if absent.
- A row's text, expected or read, is its label and value joined by ": ".
- So no label, value, ID, or name contains a colon.
- Match needs exactly equal text at the same position.
- An extra or missing paragraph, row, or cell fails all of that file's rows.

10. Until all 50 rows match, study the failing responses and change the /extract method.

Each pass follows these rules:
- Rebuild and rerun after each change.
- Keep only the latest responses in extract/.
- Stop after the sixth run that still fails.

11. Finish with a short summary that gives me these things:
- The Release build result and rows matched out of 50.
- The /extract method, the step 6 values, and each assumption you relied on.
- If the sixth run fails, the failing rows, each method tried, and what you think causes them.
Text

输出

运行的未编辑往返表格列出所有11个文件和50行的测量值。 report.docx是POST /documents返回的文档。

  • 每个替换前的通知包含3个占位符,问候语分为运行“Dear CUSTOMER_”和“NAME,”。
  • 每个保存的通知不包含占位符,问候语仍为两个运行,逗号在第二个中。
  • 所有11个文件均通过第6步检查,每个标题均为40半点粗体。
  • 在提取端点的第一次调用中,50行全都匹配,因此第10步修复循环从未运行。
  • Claude Code在草稿文件中发现了字体大小和第二次保存行为,并每次构建两次通知。
  • 提取端点从段落列表中删除了表格单元段落,并逐行读取单元。
  • 文档提示未更改代码并仅在API参考中找到TableCell.Paragraphs。
  • 第5步将其规则和测量的行为写入新的CLAUDE.md。
  • 自检匹配了所有87个段落和单元,跨越所有11个文件。
  • 我们自己对保存的文件进行的检查通过了每个要求。
  • Release版的新启动返回了相同的9个响应。
  • 有些步骤与页面中的运行不一样。 步骤1、3、5和7的提示在同一会话中接受提示后出现。 在接受提示期间,Claude Code启动的API阻止了重建,因此Claude Code重新启动并再次匹配50个中的50个。

通过的标准

  • 项目在Release中构建,手动无需更改。
  • 自行测量保存的文件时,重现了第6步值和50个匹配行。
  • 项目文件夹中的任何文件中都不出现许可证密钥。
请注意: 要尝试另一个版本,请在步骤1中设置其版本号,并阅读IronWord变更日志中的条目。

运行记录

  • 一台Windows 11 x64桌面,配备Core i9-14900KF处理器和64 GB内存,运行了每个测试。
  • 每个项目目标.NET 9。
  • 运行使用了IronWord 2026.10.1。然后在2026年10月12日发布的2026.10.4中固定了提示,其中增加了.NET 8构建,并通过将SixLabors.ImageSharp迁移到.NET 8及更高版本的4.1.3版本,解决了CVE-2026-106110至CVE-2026-106116的问题。
  • 2026.10.4暴露了与2026.10.1相同的公共API和相同的XML文档,并且32次在.NET 9上的2026.10.4探测运行给出了与在2026.10.1上的相同的结果。
  • 五个工具指南中的测试项目在xUnit上运行,Antigravity通过SixLabors.ImageSharp调整了缩略图大小,IronWord通过IronSoftware.System.Drawing引用了SixLabors.ImageSharp。
  • 时间加总为引导页面上每个提示的记录分钟数。 本指南的行仅计入接受提示。
  • 最后测试 2026年10月15日,适用于本指南、GitHub Copilot、Claude Code、Google Antigravity和ChatGPT Codex,2026年10月12日适用于Cursor。
指南助手和版本模型持续时间(分钟)
本指南Claude Code 2.1.277,一个会话,关闭权限提示Claude Opus 516.2
Claude CodeClaude Code 2.1.277,opusplan别名,计划模式下的提示3Claude Sonnet 5,Claude Opus 5计划提示335.4
ChatGPT CodexCodex CLI 0.160.0,一次坐下GPT-6 Luna43.2
GitHub CopilotCopilot CLI 1.0.95,计划模式中的提示3,审查作为其自己的调用GPT-6 Luna,Auto 选择12.8
CursorCursor 3.23.23桌面应用,计划模式下的提示3Grok 4.723.0
Google AntigravityAntigravity CLI 1.3.5,跳过权限提示Gemini 3.8 Flash(高)43.2

代理特定指南

下面的每个指南都用一个工具在一个Word文档任务上运行这些步骤。


故障排除


有问题吗?

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

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

阅读更多

准备开始了吗?

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