Doconut을 사용한 .NET 서버 측 문서 변환

소개

서버 측 문서 변환을 사용하면 애플리케이션이 Microsoft Office를 자동화하거나 소스를 별도의 온라인 변환 서비스에 전송하지 않고도 정규화된 출력물을 생성할 수 있습니다. 이는 문서 포털, 백그라운드 작업 및 제어된 내보내기 워크플로를 단순화할 수 있지만, 호스트 애플리케이션은 여전히 접근 제어, 저장, 보존, 모니터링 및 결과 전달을 담당합니다.

변환 파이프라인을 통해 흐르는 추상 문서 형식이 하나의 정규화된 출력으로 변환되는 모습

Doconut의 .NET 8 Converter 플러그인은 의존성 주입된 DocumentConverter 서비스를 통해 변환 기능을 제공합니다. 이 가이드는 현재 등록 및 API 모델에 초점을 맞추며 변환을 뷰어 세션에 연결하는 것을 피합니다.

일치하는 패키지 설치

기본 뷰어와 변환기 패키지를 설치합니다:

dotnet add package Doconut.NET8
dotnet add package Doconut.NET8.Converter

두 패키지를 동일한 릴리스 버전으로 유지하십시오. 재현 가능한 빌드가 중요할 경우 프로젝트 파일에 버전을 고정하거나 두 명령에 동일한 --version 값을 전달하십시오.

변환기 플러그인 등록

플러그인은 AddDoconut 옵션 콜백 내부에서 등록됩니다. 별도의 AddConverter() 등록 메서드는 없습니다:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

애플리케이션은 변환기 기능을 허용하는 라이선스를 사용해야 합니다. 변환 작업을 수락하기 전에 시작 및 라이선스 오류를 해결하십시오; 이러한 오류를 백그라운드 큐로 미루면 진단이 어려워집니다.

C#에서 파일 변환

DocumentConverter를 변환 요청을 담당하는 엔드포인트 또는 서비스에 주입합니다. 변환기의 생성자는 내부이며, 애플리케이션 코드에서 직접 인스턴스화해서는 안 됩니다.

app.MapPost("/api/convert", async (
    DocumentConverter converter,
    CancellationToken ct) =>
{
    await using Stream pdf = await converter.ConvertAsync(
        "documents/contract.docx",
        ConversionTarget.Pdf,
        ct: ct);

    using var copy = new MemoryStream();
    await pdf.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "contract.pdf");
});

반환된 스트림은 탐색 가능하며 시작 위치에 있습니다. 호출자가 이를 소유하며, 복사하거나 내용을 반환한 후에 스트림을 해제해야 합니다.

업로드된 스트림 변환

스트림 오버로드는 소스 확장자를 필요로 합니다(선행 점 포함). 변환기가 이를 사용해 소스 형식을 결정하기 때문입니다:

app.MapPost("/api/convert-upload", async (
    IFormFile file,
    DocumentConverter converter,
    CancellationToken ct) =>
{
    var extension = Path.GetExtension(file.FileName);
    await using var source = file.OpenReadStream();
    await using Stream output = await converter.ConvertAsync(
        source,
        extension,
        ConversionTarget.Pdf,
        password: null,
        ct: ct);

    using var copy = new MemoryStream();
    await output.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "converted.pdf");
});

파일명과 확장자를 신뢰할 수 없는 입력으로 취급하십시오. 업로드 제한을 적용하고, 소스 유형을 검증하며, 요청 사용자를 인증하고, 제출된 파일명을 저장 경로로 사용하지 않도록 합니다.

실제 기능에 따른 대상 선택

플러그인은 ConversionTarget 열거형을 제공하지만, 모든 소스 형식이 모든 대상으로 변환될 수 있는 것은 아닙니다. 사용자 정의 UI는 모든 열거형 값을 표시하기보다 업로드된 소스에 허용된 대상만 보여줘야 합니다.

Doconut의 선택적 변환기 위젯을 사용할 때, 응답에 allowedTargets가 포함됩니다. 해당 응답을 현재 파일에 대한 진실된 정보원으로 사용하십시오.

백그라운드 변환을 애플리케이션 워크플로로 설계

변환기는 애플리케이션 서비스나 큐 작업자에서 호출될 수 있습니다. 견고한 작업은 일반적으로 다음을 포함합니다:

소스와 원하는 대상을 기록하는 인증된 요청.
원시 자격 증명이 아닌 애플리케이션 작업 ID를 포함하는 큐 메시지.
인증된 스토리지 추상화를 통해 소스를 가져오는 작업자.
취소 가능한 제한된 변환 작업.
명시적인 보존 규칙을 가진 내구성 있는 출력 저장소.
내부 경로나 민감한 예외 세부 정보를 노출하지 않는 상태 업데이트.

작업자 수를 결정하기 전에 대표적인 문서로 동시성을 측정하십시오. 변환 비용은 소스 형식, 문서 복잡도, 글꼴, 이미지 및 출력 대상에 따라 달라집니다.

보안 주장 정확히 유지

.NET 애플리케이션 내에서 변환기를 실행한다는 것은 변환 작업에 Microsoft Office 자동화나 별도의 온라인 변환 API가 필요하지 않음을 의미합니다. 그러나 이는 전체 시스템에 대한 프라이버시, 규정 준수, 삭제 또는 암호화를 자동으로 보장하지는 않습니다.

이러한 속성은 애플리케이션이 사용자를 인증하고, 소스 파일을 가져오며, 스토리지를 구성하고, 로그를 보호하며, 출력을 배포하고, 임시 또는 보존 데이터를 제거하는 방식에 따라 달라집니다.

운영 체크리스트

Doconut.NET8와 Doconut.NET8.Converter 버전을 일치시킵니다.
서비스 구성 중에 ConverterPlugin을 등록합니다.
의존성 주입을 통해 DocumentConverter를 해결합니다.
스트림 소스 확장자에 선행 점을 포함합니다.
소스 및 결과 스트림을 해제합니다.
취소와 애플리케이션 수준 파일 크기 제한을 사용합니다.
모든 조합이 작동한다고 가정하지 말고 소스-대상 지원을 검증합니다.
대표 파일로 정확도와 자원 사용을 테스트합니다.
스토리지, 인증, 감사 및 보존 결정을 애플리케이션 코드에 유지합니다.

공식 Doconut Converter Plugin 개요와 Doconut documentation 문서를 확인하여 최신 제품 및 통합 정보를 확인하십시오.