컨버터 플러그인

Converter 플러그인은 Doconut을 문서 변환 서비스로 전환합니다. 공개 DocumentConverter 파사드 뒤의 엔진을 제공하고, 선택적으로 자체 HTTP 계약을 가진 삽입형 위젯을 제공하므로 C#, 위젯, 혹은 직접 작성한 프런트엔드에서 문서를 변환할 수 있습니다.

패키지 설치

최신 안정 버전의 Converter 플러그인을 설치합니다:

dotnet add package Doconut.NET6.Converter

현재 26.7.0 릴리스에 플러그인을 고정하려면 버전을 별도로 지정합니다:

dotnet add package Doconut.NET6.Converter --version 26.7.0

Converter 패키지는 Doconut.NET6와 동일한 버전을 유지해야 합니다. 패키지 ID는 Doconut.NET6.Converter; .26.7.0은 다운로드된 .nupkg 파일 이름에만 나타납니다.

플러그인 등록

AddConverter() 메서드는 없습니다 — Doconut의 플러그인 모델은 일관됩니다. 모든 플러그인(Converter 포함)은 동일한 방식으로 등록됩니다: AddDoconut() 내부에서 AddPlugin<TPlugin>()를 호출합니다. ConverterPlugin은 자체 NuGet 패키지 Doconut.NET6.Converter에 포함되어 있으며, 기본 뷰어 패키지와 함께 설치됩니다.

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

이 호출은 라이선스가 없거나, 레거시 TRIAL 파일이 있거나, Converter 기능을 부여하지 않는 비임시 라이선스가 있을 경우 시작 시 예외를 발생시킵니다(InvalidOperationException). 임시 Demo/NFR 등록은 허용되며, 기간이 만료된 후에도 워터마크가 적용된 출력으로 변환은 계속 사용할 수 있습니다. 무료 티어는 존재하지 않습니다. 라이선스 로드 방법은 라이선스 설정 문서를 참고하세요.

C#에서 변환하기

모든 변환은 0 위치에 설정된 MemoryStream을 반환하므로 즉시 읽거나 복사할 수 있습니다. DocumentConverter를 DI에서 필요할 때마다 가져오세요 — 설계상 상태가 없으므로 단일 인스턴스를 요청 간에 재사용해도 안전합니다.

// Inject DocumentConverter; its constructor is internal, so never `new` it.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension includes the leading dot. password is null unless the document is protected.
Stream png = await converter.ConvertAsync(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

잘못하기 쉬운 두 가지 세부 사항: 스트림 오버로드에서 sourceExtension은 앞에 점(".xlsx"처럼)을 포함해야 합니다 — 변환기는 이를 포맷 카탈로그와 비교하고, 점이 없는 확장자는 인식되지 않습니다. 또한 이름과 달리 WordToHtmlAsync는 Task<Stream>을 반환하며 Task<string>이 아닙니다 — HTML 문서(이미지는 Base64로 삽입)를 스트림 형태로 받게 됩니다. 이는 다른 모든 변환 결과와 동일합니다.

대상 포맷

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp

모든 소스가 모든 대상으로 변환되는 것은 아닙니다 — 플러그인은 각 소스 포맷군(Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, web document)을 자체 허용 대상 집합에 매핑합니다. UI의 대상 목록을 이 enum으로 하드코딩하지 마세요: ?convert=open 호출은 실제 allowedTargets를 반환하며, 이를 기반으로 선택기를 구성해야 합니다.

삽입형 위젯

위젯의 ?convert=open|run|download 엔드포인트는 기본적으로 비활성화되어 있으며, 선택적으로 활성화할 수 있습니다 — 기본 보안 설정입니다. 플러그인 등록과 함께 서버 측에서 활성화하세요:

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

<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
  Doconut.convert('#doconut-convert', { basePath: '/doconut', resPath: '/doconut-res', maxUploadMb: 25 });
</script>

AddConverterWidget()을 호출하지 않으면 세 개의 ?convert= 엔드포인트가 404를 반환합니다 — 하지만 JS 파일 자체는 여전히 제공됩니다(정적 리소스로 포함됨; 엔드포인트만 차단됨). AddConverterWidget()은 여전히 Converter 플러그인이 등록되고 Converter 권한을 부여하는 라이선스가 있어야 하며, 자체적으로 변환 권한을 부여하지는 않습니다.

위젯 커스터마이징

Doconut.convert(selector, options)에 전달되는 초기 옵션:

콜백:

Doconut.convert()는 위젯 인스턴스 자체를 반환합니다 — 이를 보관해 두고 프로그래밍적으로 위젯을 제어하세요:

const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
conv.reset();         // 유휴/드롭 화면으로 복귀; onReady를 다시 발생시키지 않음
conv.loadFile(file);  // File 객체로 흐름 시작; 현재 유휴 상태가 아니면 무시
conv.destroy();       // 리스너 제거, 마운트 비우기; 이후 인스턴스는 사용할 수 없음

자체 프런트엔드 구축

위젯은 이 HTTP 계약을 위한 클라이언트에 불과합니다 — 직접 HTTP 계약을 사용해 다른 UX를 구현할 수 있습니다. 세 경로 모두 UseDoconut()이 마운트된 ASP.NET 브랜치 아래에 존재합니다(보통 /doconut):

업로드된 소스 바이트는 서버 측에 30분 TTL로 보관됩니다; 이 기간이 지나면 run은 404를 반환하고 파일을 다시 열어야 합니다. 변환 결과도 동일한 보관소에 저장되며, downloadToken은 변환이 완료될 때 새 30분 창을 가집니다. resultToken은 뷰어 세션 캐시 수명을 따르는 일반 뷰어 세션 토큰입니다.

open 응답의 sourceExt는 앞에 점이 없습니다(예: "docx"). 이는 DocumentConverter.ConvertAsync의 sourceExtension 매개변수와는 반대이며, 후자는 점을 포함해야 합니다.

오류 유형 (라우트별)

리소스 소유권

컨버터는 0 위치에 설정된 MemoryStream을 반환합니다. 호출자는 해당 스트림을 복사하거나 내용을 반환한 뒤 반드시 Dispose해야 합니다. DocumentConverter 서비스 자체는 상태가 없으며 DI에서 해결되므로 직접 생성하거나 Dispose하지 마세요.

웹 위젯의 경우 업로드와 다운로드 보관소는 각각 독립적인 30분 TTL을 가집니다. 뷰어 resultToken은 뷰어 세션 수명을 따릅니다. 뷰어 결과를 닫아도 아직 유효한 다운로드 보관소는 삭제되지 않으며, 브라우저 위젯을 리셋해도 TTL이 연장되지 않습니다.

문제 해결

워터마크 처리

ConverterPlugin이 등록된 경우, 호스트 라이선스는 다음 세 가지 상태 중 하나에 해당합니다:

두 호출 경로 모두 동일한 규칙으로 플래그를 계산합니다: DocumentConverter C# 파사드는 라이선스의 IsViewerLicensed와 IsTemporary 상태를 내부적으로 확인하고, 위젯의 ?convert=run 핸들러는 동일한 체크(IsViewerLicensed && !IsTrial && !IsTemporary)를 수행해 반환된 watermarked 필드를 채웁니다. 평가 라이선스로 통합을 구축하고 최종 구매 전까지 엔드‑투‑엔드 테스트를 수행할 수 있으며, 차이점은 출력 바이트에 워터마크가 포함되는지 여부뿐입니다.