Como Carregar e Salvar Documentos do Word com Streams e Async em C#
IronWord 2026.10.1+ introduz carregamento direto de e salvamento em qualquer System.IO.Stream, junto com métodos assíncronos para ambos. Carregar e salvar anteriormente funcionavam por meio de caminhos de arquivo e matrizes de bytes. Um .docx que chega como um upload na web, desce do armazenamento em blob ou é enviado de volta em uma resposta HTTP nunca precisa tocar no disco, então funções serverless e endpoints na web permanecem completamente na memória.
Três pontos de entrada no WordDocument cobrem todos os cenários: um caminho de arquivo quando o .docx está no disco, um stream quando os bytes já estão fluindo, e uma matriz de bytes quando tudo já está na memória.
Passe qualquer stream legível para o construtor WordDocument e depois salve em outro stream, como no exemplo de carregar e salvar com streams.
-
1Instale o IronWord com NuGet Package Manager
-
2Copie e execute este trecho de código.
using var input = File.OpenRead("source.docx"); var doc = new WordDocument(input); using var output = new MemoryStream(); doc.Save(output);C# -
3Implante para testar em seu ambiente de produção.
Comece a usar o IronWord em seu projeto hoje com uma avaliação gratuita
Fluxo de trabalho mínimo (5 etapas)
Qual Sobrecarga de Carregar e Salvar Devo Usar?
Escolha a sobrecarga que corresponde aonde os dados estão.
| Método | Direção | E/S | Async |
|---|---|---|---|
WordDocument(string filePath) | Carregar | Arquivo | Não |
WordDocument(byte[] bytes) | Carregar | None | Não |
WordDocument(Stream stream) | Carregar | Fluxo | Não |
WordDocument.LoadAsync(string, CancellationToken) | Carregar | Arquivo | Sim |
WordDocument.LoadAsync(Stream, CancellationToken) | Carregar | Fluxo | Sim |
Save() retorna byte[] | Salvar | None | Não |
Save(string filePath) | Salvar | Arquivo | Não |
Save(Stream stream) | Salvar | Fluxo | Não |
SaveAs(string filePath) | Salvar | Arquivo | Não |
SaveAsync(string, CancellationToken) | Salvar | Arquivo | Sim |
SaveAsync(Stream, CancellationToken) | Salvar | Fluxo | Sim |
SaveAsAsync(string, CancellationToken) | Salvar | Arquivo | Sim |
As matrizes de bytes permanecem síncronas por design: construir a partir de bytes e serializar para uma matriz de bytes não realiza E/S, então não há nada para aguardar. Para produzir um documento inteiramente na memória e obtê-lo como bytes, chame byte[] Save().
Salvar requer uma licença válida do IronWord, assim como qualquer outro caminho de salvamento.
O Que é o Contrato de Stream?
Cinco regras regem como o IronWord trata o stream de um chamador.
- Propriedade do stream: O IronWord nunca fecha o stream do chamador, então o chamador é o proprietário e o descarta
- Carregamento: lê da posição atual até o fim e deixa o stream no final
- Salvar: escreve na posição atual
- Sem truncamento: um stream reutilizado que já mantinha um documento mais longo mantém seus antigos bytes de término após o novo conteúdo, resultando em um .docx corrompido, então reinicie com
SetLength(0)antes de salvar - Streams não busqueáveis: suportados como fonte e alvo, já que nem carregar nem salvar buscam
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");
Como Uso Streams no ASP.NET Core?
ASP.NET Core: new WordDocument(Request.Body) e doc.Save(Response.Body) lançam exceção sob o padrão do Kestrel, então use LoadAsync e SaveAsync
Como é o Document Upload?
O upload é um breve memorando de fornecedor com um título e dois parágrafos.

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();
O Que o Endpoint Retorna?
O endpoint retorna o mesmo memorando com um parágrafo CONFIDENTIAL adicionado.

O Que os Métodos Assíncronos Realmente Fazem?
Somente o E/S de arquivos ou streams é assíncrono e cancelável. Analisar um documento carregado e serializar um salvo são etapas síncronas, baseadas em CPU, que o CancellationToken não pode interromper. O token é verificado antes desse trabalho e em torno das chamadas de E/S.
Como o Relatório Se Parece Antes de Salvar?
report.docx contém um título e dois parágrafos.

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");
Como o Relatório Atualizado Se Parece?
report-updated.docx ganha a linha do apêndice datado, e report.docx permanece inalterado.

O Cancelamento é Seguro para Salvamentos de Arquivo?
O cancelamento é seguro somente se o token já estiver cancelado quando a chamada começar. Nesse caso, um salvamento por caminho lança exceção antes que o arquivo de destino seja aberto, então um arquivo existente não é alterado.
Depois que a escrita começa: um salvamento cancelado pode deixar o arquivo vazio ou parcialmente escrito, com seu conteúdo antigo perdido, e um stream parcialmente escrito
O WordDocument é Seguro para Threads?
Não. Uma única instância WordDocument não é segura para threads. Não execute operações de salvamento simultaneamente na mesma instância: Task.WhenAll(doc.SaveAsync(pathA), doc.SaveAsync(pathB)) produz comportamento indefinido.
Perguntas frequentes
Como eu carrego um documento do Word de um stream em C# usando IronWord?
Passe qualquer stream legível, como um MemoryStream ou um arquivo enviado, para o construtor WordDocument. IronWord lê o documento a partir da posição atual do stream até o final.
Como posso salvar um documento do Word em um stream com IronWord?
Chame Save com qualquer stream gravável, como um MemoryStream, para gravar o documento sem salvá-lo no disco. IronWord grava o documento na posição atual do stream.
Posso carregar e salvar documentos do Word de forma assíncrona em C#?
Sim. IronWord fornece LoadAsync para caminhos de arquivos e streams, além de SaveAsync e SaveAsAsync para salvamento, de modo que o código de aplicação assíncrona não bloqueie um thread em I/O de arquivo.
IronWord fecha o stream após carregar ou salvar um documento?
Não. IronWord nunca fecha o stream do chamador. A aplicação que abriu o stream é proprietária dele e responsável por descartá-lo.
Por que meu documento do Word salvo está corrompido quando reutilizo um stream?
Salvar em um stream que já contém um documento mais longo deixa seus bytes finais antigos no lugar, o que corrompe a saída. Redefina ou trunque o stream antes de salvar nele novamente.
Um CancellationToken pode parar o IronWord enquanto ele carrega ou salva um documento?
O token cancela apenas o I/O de arquivo ou stream. Analisar um documento carregado e serializar um salvo são etapas síncronas que o token não pode interromper.
Existe um método assíncrono para carregar ou salvar arrays de bytes no IronWord?
Não, por design. O carregamento de um array de bytes e o salvamento em um não envolvem I/O, então IronWord mantém o construtor síncrono do array de bytes e o método Save para esses casos em memória.
Um WordDocument é seguro para threads no IronWord?
Não. Uma única instância do WordDocument não é segura para threads, portanto, não execute operações de salvamento simultaneamente no mesmo documento, por exemplo, com Task.WhenAll.
Posso carregar um documento do Word de um upload sem salvá-lo no disco primeiro?
Sim. Passe o stream do upload diretamente para o construtor WordDocument ou LoadAsync, edite o documento na memória e salve-o de volta em um stream, de modo que o arquivo nunca toque o disco.
Salvar um documento do Word em um stream requer uma licença IronWord?
Sim. Salvar em um stream requer uma licença IronWord válida, da mesma forma que salvar em um caminho de arquivo ou um array de bytes.
Ahmad é um desenvolvedor full-stack com uma sólida base em C#, Python e tecnologias web. Ele tem um grande interesse em construir soluções de software escaláveis e gosta de explorar como design e funcionalidade se encontram em aplicações do mundo real.