컨버터 플러그인

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

패키지 설치

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

dotnet add package Doconut.NETStandard.Converter

플러그인을 현재 26.8.0 릴리스에 고정하려면 버전을 별도로 전달하세요:

dotnet add package Doconut.NETStandard.Converter --version 26.8.0

컨버터 패키지를 Doconut.NETStandard와 동일한 버전으로 유지하십시오. 패키지 ID는 Doconut.NETStandard.Converter이며, .26.8.0는 다운로드된 .nupkg 파일 이름에만 나타납니다.

플러그인 등록

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

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

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

C#에서 변환

각 변환은 0 위치에 설정된 탐색 가능한 MemoryStream를 반환하며, 즉시 읽거나 복사할 수 있습니다. 필요에 따라 DI에서 DocumentConverter를 해결하십시오 — 설계상 상태가 없으므로 단일 인스턴스를 요청 간에 안전하게 재사용할 수 있습니다.

viewer.Converter.GetConverter()는 여기서 존재하지 않습니다. 변환은 더 이상 뷰어 인스턴스를 통해 접근되지 않으며, 대신 Doconut.DocumentConverter를 주입하십시오.

// DocumentConverter를 주입합니다; 생성자는 internal이므로 절대 `new` 하지 마세요.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension에는 앞에 점이 포함됩니다. 문서가 보호되지 않은 경우 password는 null입니다.
Stream png = await converter.ConvertAsync(stream, ".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", "xlsx"이 아님)을 포함해야 합니다 — 변환기는 이를 형식 카탈로그와 비교하며, 점 없이 확장자는 해결되지 않습니다. 또한 이름과 달리 WordToHtmlAsync는 Task<Stream>를 반환하고, Task<string>가 아닙니다 — HTML 문서(이미지는 Base64로 삽입)를 스트림으로 얻으며, 이는 다른 모든 변환 결과와 동일합니다.

대상 형식

ConversionTarget (네임스페이스 Doconut.Configs.Conversion)에는 45개의 멤버가 있습니다:

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp, Msg, Eml, Emlx, Mhtml,
Xlsm, Xlsb, Ppt, Docm, Dot, Dotx, Dotm, Vsdx, Vssx, Vstx, Vsdm, Vssm, Vstm,
Vdx, Vsx, Vtx, Ico

이 열거형은 모든 소스 패밀리를 포괄합니다. 이전 라이브러리에는 패밀리별 *ConfigConverter 타입이 있었으며 — WordConfigConverter, ExcelConfigConverter 등 — 각각 고유한 중첩 EnTargetFormat 열거형과 입력을 위한 SourceFormatConverter 열거형이 있었습니다. 이 모든 것이 사라졌으며, 마이그레이션 가이드를 참고하십시오.

모든 소스가 모든 대상으로 변환되는 것은 아닙니다 — 플러그인은 각 소스의 형식 패밀리(Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, 웹 문서)를 고정된 허용 대상 집합에 매핑합니다. 이 열거형을 UI의 대상 목록으로 하드코딩하지 마십시오: ?convert=open는 방금 업로드된 파일에 대한 실제 allowedTargets를 반환하며, 이는 선택기를 구동하는 데 사용되어야 합니다.

Drop-in 위젯

위젯의 ?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();         // idle/drop 화면으로 돌아갑니다; onReady를 다시 호출하지 않습니다
conv.loadFile(file);  // File 객체로 흐름을 시작합니다; 현재 idle 상태가 아닐 경우 아무 동작도 하지 않습니다
conv.destroy();       // 리스너를 제거하고, 마운트를 비웁니다; 이후 인스턴스를 사용할 수 없습니다

자체 프론트엔드 구축

위젯은 이 HTTP 계약을 위한 클라이언트일 뿐입니다 — 다른 UX를 위해 직접 프론트엔드를 구축하십시오. 세 개의 라우트 모두 UseDoconut() 가 마운트되는 ASP.NET 브랜치 아래에 위치합니다 (보통 /doconut).

업로드된 소스 바이트는 서버 측에 30분 TTL로 저장됩니다; 이 기간이 지나면 run 가 404 로 응답하고 파일을 다시 열어야 합니다. 변환된 결과도 동일한 저장소에 존재하며 — 변환이 완료되면 downloadToken 가 자체 30분 창을 갖게 됩니다 — 반면 resultToken 은 뷰어 세션 캐시의 수명을 따르는 일반적인 뷰어 세션 토큰이며, 저장소와는 독립적입니다.

open 응답의 sourceExt 은 선행 점이 없습니다 (예: "docx") — 이는 DocumentConverter.ConvertAsync 의 sourceExtension 매개변수와 반대 규칙이며, 해당 매개변수는 점이 필요합니다.

실패 모드 (라우트별 그룹화):

리소스 소유권

컨버터는 위치가 0인 seekable MemoryStream 를 반환합니다. 호출자는 해당 스트림을 소유하며 복사하거나 내용을 반환한 후에 이를 해제해야 합니다. DocumentConverter 서비스 자체는 상태가 없으며 의존성 주입을 통해 해결됩니다; 서비스를 직접 생성하거나 해제하지 마세요.

웹 위젯의 경우, 업로드와 다운로드 스태시가 각각 독립적인 30분 TTL을 가집니다. 대신 뷰어 resultToken 는 뷰어 세션 수명을 따릅니다. 뷰어 결과를 닫아도 아직 유효한 다운로드 스태시가 삭제되지 않으며, 브라우저 위젯을 재설정해도 두 TTL 중 어느 것도 연장되지 않습니다.

문제 해결

워터마킹

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

두 호출 경로 모두 동일한 규칙에서 플래그를 계산합니다: DocumentConverter C# 파사드는 라이선스의 IsViewerLicensed 및 IsTemporary 상태로부터 내부적으로 이를 파생하며, 위젯의 ?convert=run 핸들러는 동등한 검사를 (IsViewerLicensed && !IsTrial && !IsTemporary) 수행하여 반환되는 watermarked 필드를 채웁니다. 구매 전 평가 라이선스로 통합을 구축하고 엔드투엔드 테스트를 수행할 수 있습니다 — 출력 바이트만 변경됩니다.