如何使用流和异步在C#中加载和节省Word文档

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

IronWord 2026.10.1+ 引入了直接从并保存到任何 System.IO.Stream 的功能,并提供了异步方法。 加载和保存先前通过文件路径和字节数组进行。 通过网络上传、从blob存储下载或在HTTP响应中返回的.docx文件无需接触磁盘,因此无服务器函数和Web端点完全保存在内存中。

三种进入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. 无截断:一个已重复使用的流,如果已保存了较长的文档,在新的内容后保持其旧的结尾字节,导致得到一个损坏的.docx,因此在保存前用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文档以季度供应商备忘录为标题,包含两个段落,作为上传内容发送到端点
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文档显示季度供应商备忘录,并在末尾附加了一个机密段落

异步方法实际做了什么?

只有文件或流I/O是异步且可取消的。 解析已加载文档和序列化已保存文档是同步的、受CPU限制的步骤,CancellationToken无法中断。 在进行这些工作之前以及I/O调用周围会检查标记。

保存之前的报告是什么样子?

report.docx包含一个标题和两个段落。

Word文档report.docx以Q3运营报告为标题,保存异步前包含两个段落
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运营报告,并在段落中附加了附录

取消对于文件保存安全吗?

仅当标记在调用开始时已经取消时取消才安全。 在这种情况下,路径保存会在打开目标文件之前抛出,因此现有文件不会被影响。

开始写入后:取消的保存可能会让文件为空或部分写入,旧内容消失,流部分写入

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刚刚发布