Doconut과 함께 .NET에서 서버 측 문서 변환

소개

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

Abstract document formats flowing through a conversion pipeline into one normalized output

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

일치하는 패키지 설치

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

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

두 패키지는 동일한 릴리스 버전을 사용해야 합니다. 재현 가능한 빌드가 중요한 경우 프로젝트 파일에 버전을 고정하거나 두 명령에 동일한 --version 값을 전달하십시오.

Converter 플러그인 등록

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

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

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

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 열거형을 제공하지만, 모든 소스 형식이 모든 대상으로 변환될 수 있는 것은 아닙니다. 사용자 인터페이스는 업로드된 소스에 대해 허용된 대상만 표시하고, 모든 열거형 값을 보여주지 않아야 합니다.

Doconut의 선택적 변환기 위젯을 사용할 경우, 응답에 포함된 allowedTargets를 현재 파일에 대한 진실된 소스로 활용하십시오.

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

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

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

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

보안 클레임을 정확히 유지

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

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

운영 체크리스트

Doconut.NET8와 Doconut.NET8.Converter 버전을 일치시킵니다.
서비스 구성 중 ConverterPlugin을 등록합니다.
의존성 주입을 통해 DocumentConverter를 해결합니다.
스트림 소스 확장자에 선행 점을 포함합니다.
소스 및 결과 스트림을 폐기합니다.
취소와 애플리케이션 수준 파일 크기 제한을 사용합니다.
모든 소스‑대상 조합이 가능한 것이 아님을 검증합니다.
대표 파일로 정확도와 리소스 사용량을 테스트합니다.
저장, 권한 부여, 감사 및 보존 결정을 애플리케이션 코드에 포함합니다.

공식 Doconut Converter Plugin 개요와 현재 제품 및 통합 정보를 보려면 Doconut documentation 을 참고하십시오.