將IronWord與AI程式設計助理一起使用
IronWord是Iron Software的.NET DOCX程式庫。 它允許您在不使用Microsoft Office的情況下在Word文件中創建、編輯、樣式化和構建表格,並讀取文本。自2023年12月以來,NuGet上提供的IronWord包含公共指南和程式碼範例。
當前範例不反映2026.10.4版本的行為。在此版本中,文本元素的大小、顏色和重量為只讀。 文件全域替換不影響表格單元格,文件全域文本提取不包括表格。
有兩種類型的AI程式設計工具。
- 助理在編輯器內運作。 它們完成行或重寫方法,類似於GitHub Copilot的內聯建議。
- 代理管理完整的任務,如編輯多個文件、運行構建和程式,以及返回結果以進行審查,類似於Claude Code、Cursor、ChatGPT Codex和Google Antigravity。
無論任務是添加文本、樣式化、構建表格、替換佔位符還是提取文本,兩種類型的設置相同。 安裝IronWord程式包,從環境變量中讀取金鑰,提供助理IronWord的機器可讀文檔,在任務計為完成之前重新打開每個已保存的DOCX。
如何將IronWord與AI程式設計助理一起使用
- 從NuGet獲取IronWord程式包
- 在第一次保存之前從
IronWord_LICENSE_KEY分配IronWord.License.LicenseKey - 在助理寫碼之前提供IronWord的llms.txt索引
- 在您的助理加載的指令文件中記錄IronWord規則
- 將一次性設定提示粘貼到新會話中
- 構建專案,重新打開每個已保存的DOCX,並比較其文本與輸入
我的AI助理不能自己處理Word文件嗎?
沒有文檔時,助理從訓練數據中寫IronWord程式碼,其中還涵蓋其他DOCX程式庫和較舊的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.
從終端固定版本。
dotnet add package IronWord --version 2026.10.4
單一套件支援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,免費試用。
在啟動時設置密鑰,一次即可,在任何IronWord調用之前。 從環境變數讀取它以避免在存儲庫中出現。
IronWord.License.LicenseKey = Environment.GetEnvironmentVariable("IRONWORD_LICENSE_KEY");
當分配的密鑰有效時IronWord.License.IsLicensed為真,而IronWord.License.IsValidLicense會測試密鑰字串。 異常類不是公開的,所以捕獲Exception並讀取其消息。
步驟 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.
獲得回答“未記錄”的許可後,助理有選擇,而不是在做出方法時選擇編造。
步驟 4:將IronWord上下文添加到您的專案中
在聊天中鍵入的指令會在會話結束時消失,因此請將IronWord規則保存在您的工具加載的專案文件中。 該文件是Claude Code的CLAUDE.md,ChatGPT Codex的AGENTS.md,GitHub Copilot的.github/copilot-instructions.md,.cursor/rules/中的.mdc文件或Cursor的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.
技能文件至少在七個地方與測量值不一致。 其單文件範例仍然使用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.
步驟 6:產生可運行程式碼的提示模式
指定段落、樣式和表格。
含糊 使用IronWord創建一個Word報告。
更好 將標題作為其自己的段落添加,其運行的TextStyle設置為20點Calibri粗體,使用
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.
使用IronWord提取文本
在2026.10.4中,提取調用返回不同的結果。
- 文件的文本提取以無分隔符連接正文段落,不返回表格文本。
- 其段落列表保存正文段落和每個表格單元格段落,按文檔順序排列。
- 表格行保存類型為介面的單元格,因此將每個單元格轉型為
TableCell以讀取其文本。 - 單元格自身的文本提取以無分隔符連接其段落。
對於一個標題、一個正文段落和一個四行表格的報告,段落列表返回10個條目,其中8個是表格單元格。 單元格段落有一個TableCell父類,因此讀者可以將正文文本與表格文本分開。 文本提取指南顯示如何讀取單元格。
使用IronWord替換佔位符
已加載的公告在兩個正文段落和一個表格單元格中持有CUSTOMER_NAME,第一個正文副本被分成兩個運行。 IronWord 2026.10.4在記憶體中以三種方式替換了它。
| 替換調用 | 正文段落 | 表格單元 |
|---|---|---|
ReplaceText 在文件上 | 替換,包括跨運行的副本 | 未更改 |
ReplaceText 在Paragraphs的每個條目上 | 已替換 | 已替換 |
ReplaceText 在每個表格單元格上 | 未更改 | 已替換 |
在已加載文件中替換了分割的副本,因為IronWord在加載時合併相鄰的純文本運行。 從兩個運行構建的內存段落也在分割處替換。 對於MERGEFIELD範本,郵件合併指南涵蓋了單獨的合併API。
可重現的結果
整個測試是下面的提示,助理寫出所有的程式碼。 打開一個空文件夾,從那裡開始新的會話,然後粘貼提示。 然後根據“符合標準”的標準比較結果。
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.
輸出
運行未編輯的往返表列出了所有11個文件和50行的測量值。 report.docx是POST /documents返回的文件。
- 每個替換前的公告包含3個佔位符,問候語被拆分成“Dear CUSTOMER_”和“NAME,”運行。
- 每個保存的公告不包含佔位符,其問候語保持兩個運行,第二個運行有逗號。
- 所有11個文件都通過了步驟6檢查,每個標題的粗體為40半點。
- 50行中第一次提取端點匹配,所以步驟10修復循環從未運行。
- Claude Code發現在測試文件中發現的字體大小和第二次保存行為並每次建構了兩次公告。
- 提取端點從段落列表中丟失表格單元格段落,並逐行讀取單元格。
- 文檔提示沒有更改任何程式碼,並僅在API參考中找到TableCell.Paragraphs。
- 步驟5將其規則和測量的行為寫入新的CLAUDE.md。
- 自檢在11個文件中匹配所有87個段落和單元格。
- 我們自己對已保存文件的檢查符合每個要求。
- 釋放構建的開始返回相同9個響應。
- 一些步驟與頁面上運行的不同。 步驟1、3、5和7的提示在接受提示後出現在同場會話中。 在接受提示期間,Claude Code已經啟動的API阻止了重新構建,因此Claude Code重啟並再次匹配50個中的50個。
什麼過關
- 項目在Release中構建,未進行手動更改。
- 當您自己測量保存的文件時,步驟6數值和50行匹配均可再現。
- 項目文件夾中的沒有出現授權密鑰。
運行記錄
- 一台運行Windows 11 x64的桌面,搭載Core i9-14900KF處理器和64 GB記憶體,運行了每次測試。
- 每個專案針對.NET 9.
- 在2026.10.1上運行
IronWord。隨後的提示固定在2026.10.4上,發佈於2026年10月12日,通過將SixLabors.ImageSharp遷移到.NET 8及更高版本的4.1.3來解決CVE-2026-106110到CVE-2026-106116。 - 2026.10.4公開的API和2026.10.1公開的API相同,見到的XML文件也相同,且在.NET 9下的2026.10.4中進行的32次探查運行給出了與2026.10.1相同的結果。
- 五個工具指南中的測試專案運行在xUnit上,Antigravity使用SixLabors.ImageSharp縮放其縮圖,IronWord通過IronSoftware.System.Drawing引用該縮圖。
- 持續時間計算每個指南頁上每個提示的記錄時間。 本指南的行程只計算接受提示。
- 最後測試 2026年10月15日,指南、GitHub Copilot、Claude Code、Google Antigravity和ChatGPT Codex,Cursor是2026年10月12日。
| 指南 | 助手和版本 | 模型 | 時長(分鐘) |
|---|---|---|---|
| 此指南 | Claude Code 2.1.277,一次會話,允許提示關閉 | Claude Opus 5 | 16.2 |
| Claude Code | Claude Code 2.1.277,opusplan別名,計劃模式的提示3 | Claude Sonnet 5,計畫提示3包括Claude Opus 5 | 35.4 |
| ChatGPT Codex | Codex CLI 0.160.0,在一次會議中 | GPT-6 Luna | 43.2 |
| GitHub Copilot | Copilot CLI 1.0.95,計劃模式下的提示3,審查是其本身的調用 | GPT-6 Luna,由Auto為其撰寫 | 12.8 |
| Cursor | Cursor 3.23.23 桌面應用程式,計劃模式的提示3 | Grok 4.7 | 23.0 |
| Google Antigravity | Antigravity CLI 1.3.5,跳過權限提示 | Gemini 3.8 Flash (High) | 43.2 |
代理特定指南
下述每個指南與一個工具在一個Word文件任務上運行這些步驟。
- 使用 IronWord 和 Claude Code 合併 MERGEFIELD 模板中的一批更新信函,重複表格行的區域
- 使用 IronWord 和 ChatGPT Codex 重新命名合同資料夾中的公司,每份合同有一行CSV
- 使用 IronWord 和 GitHub Copilot 服務於一個Visual Studio解決方案中,該解決方案構建具有數據表的樣式化DOCX文件
- 使用 IronWord 和 Cursor 將供應商表單讀取器從OpenXML SDK遷移,通過文檔鏈接和提交的專案規則指導
- 使用 IronWord 和 Google Antigravity 創建一個Blazor評審頁面,該頁面列出嵌入在上傳的驗收報告中的照片,並在沙盒化瀏覽器中檢查
疑難排解
- IronWord 許可證在 web.config 中 如果配置中設置的密鑰未應用
- IronWord 與 DocumentFormat.OpenXml 如果OpenXML SDK也被直接引用
- SaveAs後標題消失 當模板一旦其佔位符被替換後失去標題
問題?
如果您有任何疑問,請聯繫support@ironsoftware.com
Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。