如何使用流和異步在C#中載入和儲存Word文件

Ahmad Sohail
Ahmad Sohail
已更新: 2026年10月7日

IronWord 2026.10.1+引入了直接從和儲存到任何System.IO.Stream的方法,並支援兩者的異步方法。 載入和儲存以前是透過檔案路徑和位元組陣列來完成的。 作為網路上傳到達、從Blob儲存中下載,或在HTTP回應中返回的.docx從未接觸過磁碟,因此無伺服器功能和網頁端點都完全在記憶體中運行。

三個進入WordDocument的入口點涵蓋了每一種情況:當.docx在磁碟上時使用檔案路徑、當位元組已經在流動時使用流、當一切都已在記憶體中時使用位元組陣列。

快速入門:從流載入和儲存Word文件

將任何可讀流傳遞給WordDocument構造函數,然後如載入和儲存流示例中所示,儲存到另一個流中。

  1. 1使用 IronWord 安裝 NuGet Package Manager

    PM > Install-Package IronWord

  2. 2複製並運行這段程式碼。

    using var input = File.OpenRead("source.docx");
    var doc = new WordDocument(input);
    
    using var output = new MemoryStream();
    doc.Save(output);
    C#
  3. 3部署到您的生產環境進行測試

    立即在您的項目中開始使用 IronWord,並使用 免費試用
    arrow pointer

我應該使用哪種載入和儲存方法重載?

選擇與數據所在位置相匹配的重載。

翻譯方法方向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如何處理呼叫者的流。

  1. 流擁有權:IronWord從不關閉呼叫者的流,因此流由呼叫者持有和處理
  2. 載入:從當前位置讀取到結束,並將流留在末尾
  3. 儲存:在當前位置寫入
  4. 無截短:已重複使用的流已經保存了更長的文件,它的舊結尾位元組在新內容後保持不變,因此在儲存前使用SetLength(0)重設它
  5. 不支援尋找的流:同時作為來源和目標支援,因為載入和儲存都不尋找
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");
C#

如何使用流在ASP.NET Core中?

ASP.NET Core: new WordDocument(Request.Body) 和 doc.Save(Response.Body) 在Kestrel的默認設定下會拋擲異常,因此使用 LoadAsync 和 SaveAsync

上傳的文件是什麼樣的?

上傳的是一份有標題和兩段的短供應商備忘錄。

Word文檔標題為Quarterly Vendor Memo,內含兩段文字,作為上傳傳至端點
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();
C#

端點返回了什麼?

端點返回相同的備忘錄並附加了一段CONFIDENTIAL段落。

Word文檔由端點返回,顯示Quarterly Vendor Memo,附加一段CONFIDENTIAL段落在末尾

異步方法實際上做了什麼?

只有文件或流I/O是異步且可取消的。 解析已載入的文檔和序列化已儲存的文檔是同步且CPU密集的步驟,CancellationToken無法中斷。 在進行此工作之前以及進行I/O呼叫周圍檢查令牌。

儲存前報告是什麼樣的?

report.docx 包含標題和兩段文字。

Word文檔report.docx標題為Q3 Operations Report,含有兩段文字,儲存前
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");
C#

更新的報告是什麼樣的?

report-updated.docx 升級為加上的日期附錄行,且report.docx保持不變。

Word文檔report-updated.docx顯示Q3 Operations Report,附錄加在包括追加的段落

取消檔案儲存是安全的嗎?

只有在呼叫開始時令牌已被取消的情況下,取消才是安全的。 在那種情況下,路徑儲存會在目標文件開啟之前拋擲,從而不影響已存在的文件。

寫入開始後: 被取消的儲存可能會使文件空白或部分被寫入,舊內容消失,而流(如果使用的話)也可能部分被寫入

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 技術。他對建立可擴展的軟體解決方案有著濃厚的興趣,並樂於探索如何在實際應用中實現設計與功能的完美結合。

閱讀更多

準備好開始了嗎?

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