컨버터 플러그인

45가지 대상 형식으로 문서 변환

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

구분사용 시기
DocumentConverter (C#)브라우저 없이 서버에서 변환합니다
드롭인 위젯 (doconutConverter.js)페이지에 바로 사용할 수 있는 업로드, 변환, 다운로드 화면을 원할 때
HTTP 엔드포인트 (?convert=open|run|download)문서화된 서버 계약을 기준으로 자체 변환 UI를 구축하고 싶을 때

패키지 설치

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

bash
dotnet add package Doconut.NET6.Converter

이 문서에서 설명하는 릴리스에 플러그인을 고정하려면, 버전을 별도로 전달합니다:

bash
dotnet add package Doconut.NET6.Converter --version 26.10.0

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

플러그인의 라이선스 파일인 Doconut.Viewer.Converter.lic는 Doconut.Viewer.lic와 동일한 폴더에 두어야 하며, 뷰어 라이선스와 함께 읽힙니다.

플랫폼. 플러그인은 Doconut.NET6가 실행되는 모든 환경에서 동작합니다: Windows와 x64용 glibc 기반 Linux (Alpine이나 기타 musl 기반 배포판 제외). Linux에서는 첫 번째 문서를 열기 전에 폰트 설정 라이브러리를 설치하십시오:

bash
apt-get update && apt-get install -y libfontconfig1

RHEL, Fedora 및 유사 배포판에서는 패키지가 fontconfig입니다. 이를 설치하지 않으면 문서 열기가 The system library libfontconfig1 is missing. Install it (Debian/Ubuntu: apt-get install -y libfontconfig1) and see the Linux section of the Doconut documentation. 오류로 실패합니다.

플러그인 등록

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

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

C# 파사드가 필요로 하는 것은 여기까지입니다. 위젯과 그 HTTP 엔드포인트는 별도의 선택적 기능이며, AddConverterWidget()입니다 (참조 드롭인 위젯).

플러그인은 Converter 기능을 부여하는 라이선스가 필요합니다. 라이선스가 없으면, AddDoconut()는 앱이 요청을 처리하기 전에 시작 시 InvalidOperationException를 발생시킵니다:

text
The Converter plugin is registered via AddPlugin but no active license grants Converter. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.

라이선스가 없거나, 레거시 TRIAL 파일이 있거나, Converter가 없는 라이선스이거나, 버전 기간 외에 사용된 유료 라이선스인 경우 모두 오류를 발생시킵니다. 임시 Demo/NFR 라이선스는 허용됩니다. 무료 무제한 티어는 없습니다. 라이선스 로드 방법은 라이선스 설정에서 확인하십시오.

라이선스 및 워터마크

라이선스 상태시작 시변환 결과
버전 기간 내에 Converter를 부여하는 유료 뷰어 라이선스시작깨끗함 — watermarked: false
활성 임시 (Demo/NFR) 라이선스시작변환 시 평가 워터마크 — watermarked: true
만료된 임시 (Demo/NFR) 라이선스시작변환 시 평가 워터마크 — watermarked: true
라이선스 없음, 레거시 TRIAL 파일, Converter가 없는 라이선스, 또는 버전 기간 외의 유료 라이선스AddDoconut() 오류 발생—

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

DICOM 소스 (.dcm, .ima)도 Dicom 기능이 필요합니다. 이 기능이 없으면, ConvertAsync는 LicenseException (Converting '.dcm' requires the Dicom capability license.)를 발생시키고 위젯의 open는 403로 응답합니다.

C#에서 사용하기

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

csharp
// DocumentConverter를 주입하십시오; 해당 생성자는 internal이므로 절대로 `new` 하지 마세요.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);
csharp
// sourceExtension에는 앞에 점이 포함됩니다. 문서가 보호되지 않은 경우 password는 null입니다.
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);
csharp
Stream html = await converter.WordToHtmlAsync("report.docx", ct);
csharp
// html: Word 문서로 다시 변환할 HTML을 보유한 Stream이며, 예를 들어 WordToHtmlAsync의 결과와 같습니다.
Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

쉽게 실수하기 쉬운 두 가지 세부 사항이 있습니다: 스트림 오버로드에서 sourceExtension는 앞에 점(".xlsx", "xlsx"가 아니라)을 포함해야 합니다 — 변환기는 이를 포맷 카탈로그와 비교하며, 점 없는 확장자는 해결되지 않습니다. 그리고 이름과 달리 WordToHtmlAsync는 Task<Stream>를 반환하고, Task<string>가 아닙니다 — HTML 문서(이미지가 Base64로 포함됨)를 스트림으로 얻으며, 이는 다른 모든 변환 결과와 동일합니다.

호출자는 반환된 스트림을 소유하며, 복사하거나 내용물을 반환한 후에 이를 폐기해야 합니다. DocumentConverter 서비스 자체는 의존성 주입을 통해 해결됩니다; 직접 생성하거나 폐기하지 마십시오.

대상 포맷

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

text
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

모든 소스가 모든 대상으로 변환되는 것은 아닙니다 — 플러그인은 각 소스의 포맷 패밀리(Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project/Task, PSD, 웹 문서, DICOM)를 자체 고정된 허용 대상 집합에 매핑합니다. DICOM 소스(.dcm, .ima)를 변환하려면 Dicom 기능을 부여하는 라이선스도 필요합니다; 해당 대상은 Pdf, Png, Jpeg, Bmp, Tiff 및 Gif입니다. 이 enum을 UI의 대상 목록으로 하드코딩하지 마십시오: ?convert=open는 방금 업로드된 파일에 대한 실제 allowedTargets를 반환하며, 이것이 선택기를 구동해야 합니다.

위젯 삽입

엔드포인트 활성화

위젯의 ?convert=open|run|download 엔드포인트는 기본적으로 옵트인이며 비활성화되어 있습니다 — 기본적으로 보안이 적용됩니다. 플러그인 등록과 함께 서버 측에서 이를 활성화하십시오:

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

AddConverterWidget()에 인수를 제공하지 않으면 기본값(MaxUploadMb = 25)으로 위젯을 활성화합니다. 이는 자체적으로 변환 권한을 부여하지 않으며, AddPlugin<ConverterPlugin>()가 필요하거나, AddDoconut()가 예외를 발생시킵니다:

text
AddConverterWidget() was called but the Converter plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() (the widget needs it), or remove the AddConverterWidget() call.

AddConverterWidget()가 없으면, 세 개의 ?convert= 엔드포인트는 404를 응답합니다 — 그러나 JS 파일 자체는 여전히 제공됩니다(이는 단순히 포함된 정적 리소스이며, 통신하는 엔드포인트만이 제한됩니다).

삽입하기

html
<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>

Doconut.convert(selectorOrElement, options)은 CSS 선택자 또는 요소를 받아 마운트를 찾지 못하면 예외를 발생시키고, 핸들을 반환합니다. 위젯은 파일을 업로드하고, 1페이지 미리보기를 표시하며, 사용자가 allowedTargets 중 하나를 선택하도록 하고, 변환 후 가능하면 결과를 미리보고, 다운로드를 제공합니다.

옵션

옵션유형기본값비고
basePathstring/doconut?convert= 엔드포인트의 기본 경로; 실제로 마운트된 ASP.NET 브랜치인 UseDoconut() 와 일치해야 합니다 (보통 MiddlewarePath 를 통해 조정됩니다)
resPathstring/doconut-res다른 Doconut 위젯과의 구성 일관성을 위해 허용됩니다; 변환기 위젯은 현재 이를 사용해 URL을 생성하지 않습니다
maxUploadMbnumber25클라이언트 측 사전 검사만 수행합니다 — 업로드 전에 파일이 너무 큰 경우 거부합니다. 서버는 자체 제한을 독립적으로 적용하며 초과 시 413 로 응답합니다
licenseUrlstring | nullnull설정하면 결과 화면의 워터마크 알림을 이 URL에 대한 링크로 변환합니다
labelsobject{}위젯의 영어 기본 문자열(드롭 텍스트, 버튼, aria‑live 알림, 오류 메시지)의 일부를 재정의합니다

콜백

콜백발생 시점페이로드
onReady()위젯이 대기/드롭 화면을 렌더링했을 때—
onSourceLoaded({ token, pages, sourceExt, allowedTargets })?convert=open 성공 시소스 세션 토큰, 페이지 수, 소스 확장자(점 없이), 허용 대상 목록
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target })?convert=run 성공 시run 응답과 동일한 필드에 요청된 target 를 추가
onDownload({ downloadName, downloadToken })사용자가 다운로드 링크를 클릭했을 때브라우저의 기본 다운로드와 함께 발생합니다 — 이를 가로채거나 대체하지 않습니다
onError({ phase, message })열기 또는 실행 요청이 실패했을 때phase 은 'open' 또는 'run' 입니다; message 은 정제된 서버 오류(또는 업로드 크기 사전 검사에 대한 클라이언트 측 메시지)입니다

예외를 발생시키는 콜백은 잡혀서 로그에 기록되며, 위젯의 흐름을 깨지 않습니다.

명령형 핸들

Doconut.convert() 은 위젯 인스턴스 자체를 반환합니다 — 이를 보관하여 위젯을 프로그래밍 방식으로 제어하세요:

javascript
const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
const file = document.querySelector('#picker').files[0]; // 자신의 <input type="file" id="picker">에서 가져온 파일
conv.reset();         // idle/drop 화면으로 돌아갑니다; onReady를 다시 호출하지 않습니다
conv.loadFile(file);  // File 객체로 흐름을 시작합니다; 현재 idle 상태가 아닐 경우 아무 작업도 하지 않습니다
conv.destroy();       // 리스너를 제거하고, 마운트를 비웁니다; 이후 이 인스턴스는 사용할 수 없습니다

레이블

모든 문자열은 영어 기본값을 가지고 있습니다; labels 은 일부를 재정의하고 나머지는 영어 그대로 유지됩니다. 런타임에 변경되는 조각은 {placeholders} 를 사용하며, 예를 들어 uploading: 'Uploading {name}…' 와 pages: '{n} pages' 가 있습니다.

키영어 기본값
dropPromptDrag & drop a document here
dropHintPDF, Word, Excel, PowerPoint, images and more
chooseFileChoose file
uploadingUploading {name}…
page / pages1 page / {n} pages
noTargetsNo conversion targets are available for this file.
convertTo / convertConvert to / Convert
convertingConverting to {target}…
readyToDownloadReady to download
download / convertAnotherDownload / Convert another
watermarkNoticeOutput is watermarked — get a license to remove it.
retryRetry
genericErrorSomething went wrong. Please try again.
sizeLimitThat file is larger than the {mb} MB upload limit. Please choose a smaller file.
serverErrorThe server could not process this request. Please try again.
networkErrorCould not reach the server. Please check your connection and try again.

추가 키는 드롭 영역의 aria-label (dropAriaLabel), 미리보기 alt 텍스트 (previewAlt, resultAlt), licenseUrl 와 함께 사용되는 워터마크 알림의 연결된 형태 (watermarkNoticePrefix, watermarkNoticeLink, watermarkNoticeSuffix), 읽을 수 없는 응답 (badResponse) 및 aria-live 알림 (annReady, annUploading, annLoaded, annLoadedNoTargets, annConverting, annDone, annError)을 포함합니다.

서버에서 전달된 JSON 오류는 서버가 작성한 그대로 표시됩니다; serverError 은 실패한 응답에 JSON 오류가 없을 때만 사용되며, 예를 들어 비활성화된 위젯의 404 와 같습니다.

테마 지정

위젯은 dcw 클래스를 마운트 요소에 추가하고 CSS 사용자 정의 속성에서 색상, 반경 및 글꼴을 읽어 내부를 건드리지 않고도 테마를 적용할 수 있습니다:

css
#doconut-convert.dcw {
  --dcw-accent: #6b46c1;
  --dcw-radius: 12px;
  --dcw-font: "Inter", system-ui, sans-serif;
}

기본값: --dcw-accent: #2b6cb0, --dcw-bg: #ffffff, --dcw-fg: #1a202c, --dcw-muted: #718096, --dcw-border: #cbd5e0, --dcw-radius: 8px, 그리고 --dcw-font에 대한 시스템 UI 글꼴.

직접 프런트엔드 구축

위젯은 이 HTTP 계약을 위한 클라이언트일 뿐이며 — 다른 사용자 경험을 위해 직접 프런트엔드를 구축할 수 있습니다. 세 개의 라우트는 모두 UseDoconut()가 마운트되는 ASP.NET 브랜치 아래에 위치하며(보통 /doconut), AddConverterWidget()가 호출될 때까지 404를 반환합니다. 오류는 JSON 본문을 포함하며, { "error": "..." }, 표에 "status only"라고 명시된 경우를 제외합니다. 알 수 없는 ?convert= 값은 400를 반환합니다.

라우트목적성공 응답
POST ?convert=open (멀티파트, 하나의 파일)소스 문서를 업로드하고 미리 보기를 위해 엽니다200 — { token, pages, sourceExt, allowedTargets }
POST ?token=<token>&convert=run&target=<ext>저장된 소스를 target(으)로 변환합니다200 — { downloadToken, resultToken, resultPages, downloadName, watermarked }
GET ?convert=download&token=<downloadToken>변환된 파일을 스트리밍합니다200 — 파일 바이트, Content-Disposition: attachment, Cache-Control: no-store

sourceExt은 open 응답에 선행 점이 없습니다(예: "docx") — DocumentConverter.ConvertAsync의 sourceExtension 매개변수와는 반대 규칙이며, 이 매개변수는 점을 필요로 합니다. allowedTargets은 소문자 대상 이름("pdf", "html", …)을 나열합니다; 이 중 하나를 target로 전달하면 대소문자를 구분하지 않고 매치됩니다. open은 멀티파트 본문의 첫 번째 파일을 사용합니다.

결과를 미리 볼 수 없을 때 resultToken은 null이며, resultPages은 0입니다. downloadName은 대상 확장자를 가진 소스 파일 이름입니다.

미리보기 이미지는 표준 뷰어 이미지 라우트인 {basePath}?token={token}&page=1&thumb=1&width={px}를 사용하며, open에서 온 token 또는 run에서 온 resultToken와 함께 사용됩니다. 위젯은 width=240을 요청합니다.

업로드된 소스 바이트는 서버 측에 저장되며 마지막으로 읽힌 후 30분 동안 유지됩니다; 이 기간이 지나면 run이 404을 반환하고 파일을 다시 열어야 합니다. 변환된 결과도 동일한 저장소에 존재하며 — 변환이 완료되면 downloadToken은 자체 30분 유효 기간을 갖습니다 — 반면 resultToken은 결과 미리보기를 위한 일반 뷰어 세션 토큰입니다. 결과를 미리볼 수 있을 때 downloadToken와 resultToken은 동일한 값입니다. 뷰어 결과를 닫아도 아직 유효한 다운로드 저장소는 삭제되지 않으며, 브라우저 위젯을 재설정해도 두 기간 중 어느 것도 연장되지 않습니다.

실패 모드, 라우트별로 그룹화:

라우트상태시점본문
any404위젯이 활성화되지 않았습니다(AddConverterWidget()가 호출되지 않음) — 세 라우트 중 어느 것도 디스패치되기 전에 확인됩니다상태만
any405잘못된 HTTP 메서드(open/run는 POST가 필요하고, download는 GET가 필요합니다)상태만
open400멀티파트 업로드가 아닙니다Expected a multipart file upload.
open400파일이 없거나 비어 있습니다No file uploaded.
open400변환할 수 없는 소스 확장자This file type cannot be converted.
open403파일 유형에 라이선스가 제공하지 않는 기능이 필요합니다 (Dicom 없는 DICOM 파일)Converting this file type requires the Dicom capability license.
open413MaxUploadMb을 초과하는 업로드 파일, Content-Length와 비교 및 업로드가 읽히는 동안 확인됩니다File is too large.
run400잘못된 토큰 (GUID가 아님)Invalid token.
run400target이(가) ConversionTarget로 구문 분석되지 않음Unknown target format.
run400target이(가) 소스의 allowedTargets에 없습니다That target format is not available for this file.
run404저장된 업로드가 만료되었거나 토큰이 열리지 않았습니다Upload expired — please re-open the file.
open, run500내부 처리 실패정제된 메시지 — 다른 모든 Doconut 오류 경로와 동일하게 정제되며, 내부 세부 정보를 절대 노출하지 않습니다
download400잘못된 토큰 (GUID가 아님)상태만
download404알 수 없거나 만료된 다운로드 토큰상태만

fetch와(과) 함께하는 전체 라운드 트립:

javascript
// file: 변환할 파일, 예를 들어 <input type="file">에서.
async function convertFile(file) {
  const base = '/doconut';

  // 1. open: 파일을 업로드
  const form = new FormData();
  form.append('file', file, file.name);
  const openResp = await fetch(base + '?convert=open', { method: 'POST', body: form });
  if (!openResp.ok) throw new Error((await openResp.json()).error);
  const opened = await openResp.json();

  // 2. run: 허용되는 경우 PDF로 변환하고, 그렇지 않으면 첫 번째 허용된 대상으로 변환합니다
  const target = opened.allowedTargets.includes('pdf') ? 'pdf' : opened.allowedTargets[0];
  const runResp = await fetch(base + '?token=' + encodeURIComponent(opened.token) +
    '&convert=run&target=' + target, { method: 'POST' });
  if (!runResp.ok) throw new Error((await runResp.json()).error);
  const converted = await runResp.json();

  // 3. download: 브라우저가 따라갈 수 있는 일반 GET
  window.location.href = base + '?convert=download&token=' + encodeURIComponent(converted.downloadToken);
}

엔드포인트는 same-origin(동일 출처)입니다: 이 버전은 CORS를 지원하지 않습니다. UI와 위젯 스크립트를 Doconut과 동일한 출처에서 제공하거나, 두 /doconut 경로(미들웨어 경로와 리소스 경로)를 UI의 출처 아래에서 역프록시하십시오.

프로덕션에서

  1. 플러그인 설치 코어 패키지 옆에, 동일한 버전으로: dotnet add package Doconut.NET6.Converter.
  2. 라이선스 파일 추가 같은 폴더에 Doconut.Viewer.Converter.lic를 Doconut.Viewer.lic와 함께 넣으세요.
  3. 서버 제한 설정 MaxUploadMb in AddConverterWidget는 서버가 적용하는 제한이며; 위젯의 maxUploadMb는 클라이언트 측 검사일 뿐입니다. 두 값을 동일하게 유지하세요.
  4. UI를 Doconut 엔드포인트와 동일한 출처에서 제공하거나, 역프록시하십시오 (자세한 내용은 직접 프런트엔드 구축 참고).
  5. 변환 결과 정리 ConvertAsync가 반환하는 스트림은 풀링됩니다; 이를 정리하면 버퍼가 풀로 반환됩니다.

웹 팜

위젯은 open를 제공한 노드의 메모리에 각 업로드와 그 결과를 저장합니다. 스티키 세션이 없는 로드 밸런서 뒤에서는, 이후의 run, download 또는 프리뷰 요청이 다른 노드에 도달해 업로드를 찾지 못할 수 있습니다. AddDoconut() 이후에 공유된 암호화 위젯 스토어를 한 번 등록하십시오:

csharp
byte[] farmKey = Convert.FromBase64String(builder.Configuration["Doconut:FarmKey"]);

builder.Services.AddDoconutDistributedWidgets(store =>
{
    store.RootPath = @"\\fileshare\doconut";   // 모든 노드가 읽고 쓸 수 있는 폴더
    store.FarmKey = farmKey;                   // 최소 32바이트, 모든 노드에서 동일
    // store.Ttl = TimeSpan.FromMinutes(30);   // 업로드가 유지되는 시간 (기본값)
});
  • 단일 서버는 아무 것도 필요하지 않습니다: 이 호출이 없으면 인메모리 스토어가 사용됩니다.
  • 업로드와 결과는 공유 저장소에 보관 시 암호화됩니다 (AES-256, encrypt-then-MAC), 각 파일은 해당 토큰에 바인딩되어 하나의 토큰이 다른 파일을 읽을 수 없습니다.
  • 공유 저장소에서는 업로드 또는 결과가 작성된 후 Ttl 동안 보관됩니다; 읽는 행위는 해당 기간을 연장하지 않습니다.
  • FarmKey는 최소 32바이트이며 모든 노드에서 동일해야 합니다. 비밀 저장소에서 로드하십시오; 절대로 하드코딩하지 마세요. 등록은 RootPath가 없거나 FarmKey가 32바이트보다 짧을 때 ArgumentException를 발생시킵니다.
  • RootPath를 분산 뷰어가 사용하는 동일한 공유 위치로 지정하십시오.

API 참조

Facade와 위젯 옵션은 Doconut 네임스페이스에 있습니다; ConversionTarget는 Doconut.Configs.Conversion에 있습니다. ConverterPlugin는 Doconut.Plugins.Converter에 있습니다.

DocumentConverter

csharp
public sealed class DocumentConverter
{
    public Task<Stream> ConvertAsync(
        string filePath, ConversionTarget target,
        string? password = null, CancellationToken ct = default);

    public Task<Stream> ConvertAsync(
        Stream source, string sourceExtension, ConversionTarget target,
        string? password = null, CancellationToken ct = default);

    public Task<Stream> WordToHtmlAsync(string filePath, CancellationToken ct = default);

    public Task<Stream> HtmlToWordAsync(
        Stream htmlSource, ConversionTarget outputFormat = ConversionTarget.Docx,
        CancellationToken ct = default);
}

의존성 주입을 통해 해결됩니다; 생성자는 내부입니다. sourceExtension는 앞에 점이 포함됩니다. HtmlToWordAsync는 outputFormat가 ConversionTarget.Doc일 때 .doc 파일을 작성하고, 다른 값에 대해서는 .docx 파일을 작성합니다.

ConversionTarget

45개의 출력 형식은 대상 형식에서 확인할 수 있습니다.

ConverterWidgetOptions

csharp
public sealed class ConverterWidgetOptions
{
    public int MaxUploadMb { get; set; } = 25;
}

DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null)를 통해 설정하면, 호출을 체인할 수 있도록 DoconutOptions를 반환합니다.

문제 해결

증상원인해결 방법
AddDoconut() 예외 발생 The Converter plugin is registered via AddPlugin but no active license grants Converter.라이선스 없음, TRIAL 파일, Converter가 없는 라이선스, 또는 버전 기간 외의 유료 라이선스Converter를 부여하는 라이선스를 설치하거나, AddPlugin<ConverterPlugin>()를 제거하십시오
AddDoconut() 예외 발생 AddConverterWidget() was called but the Converter plugin is not registered.위젯이 플러그인 없이 활성화되었습니다options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>()를 추가하십시오
DocumentConverter 해결 시 No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>(). 예외 발생ConverterPlugin가 등록되지 않음AddDoconut() 안에 AddPlugin<ConverterPlugin>()를 추가하십시오
스트림 변환에서 형식이 지원되지 않음sourceExtension에 앞점이 없습니다".xlsx"를 전달하고, "xlsx"는 사용하지 마세요
ConvertAsync 예외 발생 Converting '.dcm' requires the Dicom capability license.DICOM 소스이며, 라이선스가 Dicom를 부여하지 않음Dicom를 부여하는 라이선스를 사용하십시오
출력이 워터마크가 적용됨라이선스가 임시(Demo/NFR)입니다Converter를 부여하는 유료 라이선스를 사용하십시오
위젯은 로드되지만 요청이 404로 응답합니다AddConverterWidget()가 호출되지 않았거나, basePath가 UseDoconut()가 마운트된 브랜치와 일치하지 않음AddConverterWidget()를 호출하십시오; basePath를 수정하십시오
open가 403 Converting this file type requires the Dicom capability license.에 응답합니다DICOM 업로드이며, 라이선스가 Dicom를 부여하지 않음Dicom를 부여하는 라이선스를 사용하십시오
open가 413 File is too large.에 응답합니다업로드가 MaxUploadMb를 초과합니다AddConverterWidget에서 MaxUploadMb를 발생시키세요; 위젯의 maxUploadMb는 클라이언트 측 검사일 뿐입니다
run가 400 That target format is not available for this file.에 응답합니다대상이 소스의 allowedTargets 중 하나가 아닙니다open에서 allowedTargets만 제공하십시오
run 또는 download가 404에 응답합니다 (Upload expired — please re-open the file.가 run에서)30분 창이 만료되었거나, 웹 팜 노드에 업로드가 없습니다파일을 다시 열어보세요; 팜에서는 AddDoconutDistributedWidgets를 등록하십시오
UI가 다른 출처에 있을 때 위젯이 실패합니다엔드포인트에 CORS 지원이 없습니다UI를 동일한 출처에서 제공하거나, Doconut 경로를 역프록시하십시오
테마가 적용되지 않음변수가 상위 요소나 마운트 내부 요소에 설정되어 있습니다; 위젯 자체의 .dcw 규칙이 마운트에 설정합니다마운트 자체를 대상으로: #doconut-convert.dcw 또는 #doconut-convert

이 페이지가 도움이 되었나요?