컨버터 플러그인

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

패키지 설치

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

dotnet add package Doconut.NET8.Converter

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

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

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

플러그인 등록

AddConverter() 메서드는 없습니다 — Doconut의 플러그인 모델은 일관됩니다. Converter를 포함한 모든 플러그인은 동일한 방식으로 등록됩니다: AddDoconut() 내부에서 AddPlugin<TPlugin>()를 호출합니다. ConverterPlugin는 자체 NuGet 패키지인 Doconut.NET8.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를 해결하십시오 — 설계상 상태가 없으므로 단일 인스턴스를 요청 간에 안전하게 재사용할 수 있습니다.

// DocumentConverter를 주입하십시오; 그 생성자는 internal이며, 절대 `new` 하지 마세요.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension에는 앞에 점이 포함됩니다. password는 문서가 보호된 경우가 아니면 null입니다.
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", "xlsx"가 아님)을 포함해야 합니다 — 변환기는 이를 포맷 카탈로그와 비교하고, 점 없이 확장자는 해결되지 않습니다. 또한 이름과 달리 WordToHtmlAsync는 Task<string>가 아니라 Task<Stream>를 반환합니다 — 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, 웹 문서)를 자체 고정된 허용 대상 집합에 매핑합니다. 이 열거형을 UI의 대상 목록에 하드코딩하지 마십시오: ?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();         // idle/drop 화면으로 돌아갑니다; onReady를 다시 호출하지 않습니다
conv.loadFile(file);  // File 객체로 흐름을 시작합니다; 현재 idle 상태가 아니면 아무 동작도 하지 않습니다
conv.destroy();       // 리스너를 제거하고, mount를 비웁니다; 이후 인스턴스를 사용할 수 없습니다

자체 사용자 인터페이스 구축

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

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

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

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

리소스 소유권

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

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

문제 해결

워터마킹

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

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