如何使用流和異步在C#中載入和儲存Word文件
IronWord 2026.10.1+引入了直接從和儲存到任何System.IO.Stream的方法,並支援兩者的異步方法。 載入和儲存以前是透過檔案路徑和位元組陣列來完成的。 作為網路上傳到達、從Blob儲存中下載,或在HTTP回應中返回的.docx從未接觸過磁碟,因此無伺服器功能和網頁端點都完全在記憶體中運行。
三個進入WordDocument的入口點涵蓋了每一種情況:當.docx在磁碟上時使用檔案路徑、當位元組已經在流動時使用流、當一切都已在記憶體中時使用位元組陣列。
將任何可讀流傳遞給WordDocument構造函數,然後如載入和儲存流示例中所示,儲存到另一個流中。
-
1使用 IronWord 安裝 NuGet Package Manager
-
2複製並運行這段程式碼。
using var input = File.OpenRead("source.docx"); var doc = new WordDocument(input); using var output = new MemoryStream(); doc.Save(output);C# -
3部署到您的生產環境進行測試
立即在您的項目中開始使用 IronWord,並使用 免費試用
最小工作流程(5 個步驟)
我應該使用哪種載入和儲存方法重載?
選擇與數據所在位置相匹配的重載。
| 翻譯方法 | 方向 | I/O | 異步 |
|---|---|---|---|
WordDocument(string filePath) | 載入 | 文件 | 無 |
WordDocument(byte[] bytes) | 載入 | None | 無 |
WordDocument(Stream stream) | 載入 | 流 | 無 |
WordDocument.LoadAsync(string, CancellationToken) | 載入 | 文件 | 是 |
WordDocument.LoadAsync(Stream, CancellationToken) | 載入 | 流 | 是 |
Save() 返回 byte[] | 儲存 | None | 無 |
Save(string filePath) | 儲存 | 文件 | 無 |
Save(Stream stream) | 儲存 | 流 | 無 |
SaveAs(string filePath) | 儲存 | 文件 | 無 |
SaveAsync(string, CancellationToken) | 儲存 | 文件 | 是 |
SaveAsync(Stream, CancellationToken) | 儲存 | 流 | 是 |
SaveAsAsync(string, CancellationToken) | 儲存 | 文件 | 是 |
位元組陣列在設計上保持同步:從位元組構建和序列化為位元組陣列不執行I/O,因此無需等待。 要完全在記憶體中生成文檔並以位元組的形式獲取它,請調用byte[] Save()。
儲存需要有效的IronWord授權,與其他所有儲存路徑相同。
流合約是什麼?
五條規則管理IronWord如何處理呼叫者的流。
- 流擁有權:IronWord從不關閉呼叫者的流,因此流由呼叫者持有和處理
- 載入:從當前位置讀取到結束,並將流留在末尾
- 儲存:在當前位置寫入
- 無截短:已重複使用的流已經保存了更長的文件,它的舊結尾位元組在新內容後保持不變,因此在儲存前使用
SetLength(0)重設它 - 不支援尋找的流:同時作為來源和目標支援,因為載入和儲存都不尋找
using IronWord;
using IronWord.Models;
// Build a document entirely in memory
var doc = new WordDocument();
doc.AddParagraph(new Paragraph(new TextContent("Invoice #1042")));
doc.AddParagraph(new Paragraph(new TextContent("Total: $2,450.00")));
// Save to a MemoryStream
using var ms = new MemoryStream();
doc.Save(ms);
// Reset the position before handing the stream to another consumer
ms.Position = 0;
// Print the document size
Console.WriteLine($"Document size: {ms.Length} bytes");
如何使用流在ASP.NET Core中?
ASP.NET Core: new WordDocument(Request.Body) 和 doc.Save(Response.Body) 在Kestrel的默認設定下會拋擲異常,因此使用 LoadAsync 和 SaveAsync
上傳的文件是什麼樣的?
上傳的是一份有標題和兩段的短供應商備忘錄。

using IronWord;
using IronWord.Models;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
var app = WebApplication.Create();
// Upload a .docx, append a confidentiality notice, and return the modified document
app.MapPost("/add-notice", async (HttpRequest request) =>
{
// Load the request body asynchronously
var doc = await WordDocument.LoadAsync(request.Body);
// Append a confidentiality notice
doc.AddParagraph(new Paragraph(new TextContent("CONFIDENTIAL")));
// Set the download headers
var response = request.HttpContext.Response;
response.ContentType =
"application/vnd.openxmlformats-officedocument.wordprocessingml.document";
response.Headers.ContentDisposition = "attachment; filename=modified.docx";
// Save to the response body asynchronously
await doc.SaveAsync(response.Body);
return Results.Empty;
});
app.Run();
端點返回了什麼?
端點返回相同的備忘錄並附加了一段CONFIDENTIAL段落。

異步方法實際上做了什麼?
只有文件或流I/O是異步且可取消的。 解析已載入的文檔和序列化已儲存的文檔是同步且CPU密集的步驟,CancellationToken無法中斷。 在進行此工作之前以及進行I/O呼叫周圍檢查令牌。
儲存前報告是什麼樣的?
report.docx 包含標題和兩段文字。

using IronWord;
using IronWord.Models;
// Load a document from disk asynchronously
var doc = await WordDocument.LoadAsync("report.docx");
// Append a dated paragraph
doc.AddParagraph(new Paragraph(
new TextContent("Appendix added on " + DateTime.Now.ToString("yyyy-MM-dd"))));
// Save to a new path, leaving the original untouched
await doc.SaveAsAsync("report-updated.docx");
更新的報告是什麼樣的?
report-updated.docx 升級為加上的日期附錄行,且report.docx保持不變。

取消檔案儲存是安全的嗎?
只有在呼叫開始時令牌已被取消的情況下,取消才是安全的。 在那種情況下,路徑儲存會在目標文件開啟之前拋擲,從而不影響已存在的文件。
寫入開始後: 被取消的儲存可能會使文件空白或部分被寫入,舊內容消失,而流(如果使用的話)也可能部分被寫入
WordDocument 是在執行緒安全的嗎?
不。單個WordDocument實例不是執行緒安全的。 不要對相同的實例並發執行儲存操作:Task.WhenAll(doc.SaveAsync(pathA), doc.SaveAsync(pathB))會產生未定義的行為。
常見問題
如何在C#中使用IronWord從流中裝載Word文件?
將任何可讀的流,例如MemoryStream或上傳的文件,傳遞給WordDocument構造函數。IronWord從流的當前位置讀取文件到結尾。
如何使用IronWord將Word文件儲存到流中?
調用Save並傳入任何可寫的流,例如MemoryStream,以在不將文件儲存到磁碟的情況下降寫文件。IronWord在流的當前位置寫入文件。
我可以在C#中非同步地裝載和儲存Word文件嗎?
可以。IronWord提供LoadAsync用於文件路徑和流,另外還有SaveAsync和SaveAsAsync用於儲存,因此非同步應用程式代碼不會因文件I/O而阻塞線程。
IronWord在裝載或儲存文件後會關閉流嗎?
不。IronWord永遠不會關閉調用者的流。打開流的應用程序擁有它,並負責處理它。
為什麼我重新使用流時儲存的Word文件損壞了?
儲存到已經持有較長文件的流中會保留其舊的尾部位元組,這會損壞輸出。在再次儲存之前重設或截斷流。
CancellationToken能在IronWord裝載或儲存文件時停用它嗎?
該標記僅取消文件或流I/O。解析已裝載的文件和序列化儲存的文件是同步步驟,該標記無法中斷。
IronWord是否有非同步的方法來裝載或儲存位元組數組?
沒有,這是有意設計的。從位元組數組裝載和儲存到位元組數組不涉及I/O,因此IronWord對於這些記憶體中的情況保持同步的位元組數組構造函數和Save方法。
IronWord中的WordDocument是執行緒安全的嗎?
不是。單個WordDocument實例不是執行緒安全的,因此不要對相同的文件同時運行儲存操作,例如使用Task.WhenAll。
我可以不先將文件儲存到磁碟中,而直接從上傳中裝載Word文件嗎?
可以。直接將上傳的流傳遞給WordDocument構造函數或LoadAsync,然後在記憶體中編輯文件,然後將其儲存回流中,這樣文件不會觸及磁碟。
將Word文件儲存到流中需要IronWord授權嗎?
是的。將文件儲存到流中需要有效的IronWord授權,與儲存到文件路徑或位元組數組相同。
Ahmad 是一位全端開發人員,精通 C#、Python 和 Web 技術。他對建立可擴展的軟體解決方案有著濃厚的興趣,並樂於探索如何在實際應用中實現設計與功能的完美結合。