Como Carregar e Salvar Documentos do Word com Streams e Async em C#

Ahmad Sohail
Ahmad Sohail
Atualizado: 7 de outubro de 2026

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.

Início Rápido: Carregar e Salvar um Documento do Word de um Stream

Passe qualquer stream legível para o construtor WordDocument e depois salve em outro stream, como no exemplo de carregar e salvar com streams.

  1. 1Instale o IronWord com NuGet Package Manager

    PM > Install-Package IronWord

  2. 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#
  3. 3Implante para testar em seu ambiente de produção.

    Comece a usar o IronWord em seu projeto hoje com uma avaliação gratuita
    arrow pointer

Qual Sobrecarga de Carregar e Salvar Devo Usar?

Escolha a sobrecarga que corresponde aonde os dados estão.

MétodoDireçãoE/SAsync
WordDocument(string filePath)CarregarArquivoNão
WordDocument(byte[] bytes)CarregarNoneNão
WordDocument(Stream stream)CarregarFluxoNão
WordDocument.LoadAsync(string, CancellationToken)CarregarArquivoSim
WordDocument.LoadAsync(Stream, CancellationToken)CarregarFluxoSim
Save() retorna byte[]SalvarNoneNão
Save(string filePath)SalvarArquivoNão
Save(Stream stream)SalvarFluxoNão
SaveAs(string filePath)SalvarArquivoNão
SaveAsync(string, CancellationToken)SalvarArquivoSim
SaveAsync(Stream, CancellationToken)SalvarFluxoSim
SaveAsAsync(string, CancellationToken)SalvarArquivoSim

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.

  1. Propriedade do stream: O IronWord nunca fecha o stream do chamador, então o chamador é o proprietário e o descarta
  2. Carregamento: lê da posição atual até o fim e deixa o stream no final
  3. Salvar: escreve na posição atual
  4. 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
  5. 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");
C#

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.

Documento do Word intitulado Memorando Trimestral de Fornecedor com dois parágrafos, enviado ao endpoint como o upload
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#

O Que o Endpoint Retorna?

O endpoint retorna o mesmo memorando com um parágrafo CONFIDENTIAL adicionado.

Documento do Word retornado pelo endpoint mostrando o Memorando Trimestral de Fornecedor com um parágrafo CONFIDENCIAL adicionado no final

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.

Documento Word report.docx intitulado Relatório de Operações Q3 com dois parágrafos, antes do salvamento assíncrono
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#

Como o Relatório Atualizado Se Parece?

report-updated.docx ganha a linha do apêndice datado, e report.docx permanece inalterado.

Documento Word report-updated.docx mostrando o Relatório de Operações Q3 com um Apêndice adicionado no parágrafo

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.

Leia Mais

Pronto para começar?

Downloads no NuGet 62,392Versão:2026.11recém-lançado