Streams 및 Async로 Word 문서 로드 및 저장하는 방법 (C#)

아흐마드 소하일
Ahmad Sohail
업데이트됨: 2026년 10월 7일

IronWord 2026.10.1+는 모든 System.IO.Stream에서 직접 로드하고 저장할 수 있는 기능과 함께 비동기 메서드를 도입합니다. 이전에는 파일 경로 및 바이트 배열을 통해 로드 및 저장이 이루어졌습니다. 웹 업로드로 도착한 .docx가 blob 저장소에서 내려오거나 HTTP 응답으로 다시 나갈 때 디스크에 닿을 필요가 없으므로 서버리스 함수와 웹 엔드포인트는 메모리 내에서 완전히 처리됩니다.

WordDocument에 대한 세 가지 진입점은 모든 시나리오를 다룹니다: .docx가 디스크에 있을 때는 파일 경로, 이미 바이트가 흐르고 있을 때는 스트림, 모든 것이 이미 메모리에 있을 때는 바이트 배열입니다.

빠른 시작: 스트림에서의 Word 문서 로드 및 저장

읽을 수 있는 스트림을 WordDocument 생성자에게 전달한 다음, 스트림 예제를 통한 로드 및 저장처럼 다른 스트림에 저장하세요.

  1. 1IronWord를 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

어떤 로드 및 저장 오버로드를 사용해야 하나요?

데이터가 어디에 있는지에 맞는 오버로드를 선택하세요.

방법방향입출력비동기
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: Kestrel의 기본값에서 new WordDocument(Request.Body)과 doc.Save(Response.Body)가 예외를 발생시키므로 LoadAsync과 SaveAsync을 사용하세요.

업로드된 문서는 어떻게 보이나요?

업로드된 내용은 제목과 두 개의 단락이 있는 짧은 공급업체 메모입니다.

제목이 Quarterly Vendor Memo로 된 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 문서는 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는 변경되지 않았습니다.

부록이 추가된 단락이 있는 Q3 Operations Report가 표시된 Word 문서 report-updated.docx

파일 저장의 취소는 안전한가요?

취소는 호출이 시작될 때 이미 토큰이 취소된 경우에만 안전합니다. 이 경우 경로 저장은 대상 파일을 열기 전에 예외를 발생시키므로 기존 파일이 영향을 받지 않습니다.

작성 시작 후: 취소된 저장은 파일을 비워두거나 일부 작성된 상태로 두어 이전의 내용이 사라지며 스트림이 일부 작성된 상태가 될 수 있습니다.

WordDocument는 스레드 안전한가요?

아니요. 단일 WordDocument 인스턴스는 스레드 안전하지 않습니다. 동일한 인스턴스에 대해 저장 작업을 동시에 실행하지 마세요: Task.WhenAll(doc.SaveAsync(pathA), doc.SaveAsync(pathB))은 정의되지 않은 동작을 초래합니다.

자주 묻는 질문

IronWord를 사용하여 C# 스트림에서 Word 문서를 어떻게 로드합니까?

MemoryStream이나 업로드된 파일과 같은 모든 읽기 가능한 스트림을 WordDocument 생성자에 전달하세요. IronWord는 스트림의 현재 위치에서 끝까지 문서를 읽습니다.

IronWord로 Word 문서를 스트림에 어떻게 저장할 수 있습니까?

저장 경로가 아닌 MemoryStream과 같은 모든 쓰기 가능한 스트림에 문서를 기록하려면 Save를 호출하세요. 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 라이선스가 필요하며, 파일 경로나 바이트 배열에 저장하는 것과 동일합니다.

아흐마드는 C#, Python 및 웹 기술에 탄탄한 기반을 갖춘 풀스택 개발자입니다. 그는 확장 가능한 소프트웨어 솔루션 구축에 깊은 관심을 가지고 있으며, 실제 응용 프로그램에서 디자인과 기능이 어떻게 조화를 이루는지 탐구하는 것을 즐깁니다.

더 읽기

시작할 준비 되셨나요?

NuGet 다운로드 수 62,392버전:2026.11방금 출시