컨버터 플러그인
문서를 45개의 대상 형식으로 변환
Converter 플러그인은 Doconut을 문서 변환 서비스로 전환합니다. 공개 DocumentConverter 파사드 뒤의 엔진을 제공하고, — 선택적으로 — 자체 HTTP 계약을 가진 드롭인 위젯을 제공하므로 C#에서, 위젯에서, 혹은 직접 작성한 프런트엔드에서 문서를 변환할 수 있습니다.
| 구 구현 방식 | 사용 시기 |
|---|---|
DocumentConverter (C#) | 서버에서 변환하며 브라우저가 관여하지 않을 때 |
Drop-in widget (doconutConverter.js) | 페이지에 즉시 사용할 수 있는 업로드, 변환 및 다운로드 화면을 원할 때 |
HTTP endpoints (?convert=open|run|download) | 문서화된 서버 계약에 따라 자체 변환 UI를 구축하고자 할 때 |
패키지 설치
최신 안정 버전 Converter 플러그인을 설치합니다:
dotnet add package Doconut.NET8.Converter이 문서에서 설명하는 릴리스에 플러그인을 고정하려면, 버전을 별도로 전달하세요:
dotnet add package Doconut.NET8.Converter --version 26.10.0Converter 패키지를 Doconut.NET8와 동일한 버전으로 유지하십시오. 패키지 ID는
Doconut.NET8.Converter; .<version>는 다운로드된 .nupkg 파일 이름에만 나타납니다.
플러그인의 라이선스 파일인 Doconut.Viewer.Converter.lic는 Doconut.Viewer.lic와 같은 폴더에 두며, 뷰어 라이선스와 함께 읽힙니다.
플랫폼. 플러그인은 Doconut.NET8가 실행되는 모든 환경에서 동작합니다: Windows와 x64용 glibc 기반 Linux (Alpine이나 기타 musl 기반 배포판 제외). Linux에서는 첫 문서를 열기 전에 글꼴 구성 라이브러리를 설치하십시오:
apt-get update && apt-get install -y libfontconfig1RHEL, 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.NET8.Converter에 포함되어 기본 뷰어 패키지와 함께 설치됩니다.
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});이것이 C# 파사드가 필요로 하는 전부입니다. 위젯과 그 HTTP 엔드포인트는 별도의 선택적 기능인 AddConverterWidget()이며, 드롭인 위젯를 참조하십시오.
플러그인은 Converter 기능을 부여하는 라이선스가 필요합니다. 라이선스가 없으면, AddDoconut()는 애플리케이션이 요청을 처리하기 전에 시작 시 InvalidOperationException를 발생시킵니다:
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을 해결하십시오 — 설계상 상태가 없으므로 단일 인스턴스를 요청 간에 재사용해도 안전합니다.
// 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);// 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개의 멤버가 있습니다:
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입니다. 이 열거형을 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;
});
});AddConverterWidget()에 인수를 제공하지 않으면 기본값(MaxUploadMb = 25)으로 위젯을 활성화합니다. 이것만으로는 변환 권한을 부여하지 않으며, AddPlugin<ConverterPlugin>()이 필요하거나, AddDoconut()가 예외를 발생시킵니다:
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 파일 자체는 여전히 제공됩니다(이는 단순히 포함된 정적 리소스이며, 통신하는 엔드포인트만 제한됩니다).
삽입하기
<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 중 하나를 선택하도록 하고, 변환 후 가능하면 결과를 미리보며, 다운로드를 제공합니다.
옵션
| 옵션 | 유형 | 기본값 | 비고 |
|---|---|---|---|
basePath | string | /doconut | ?convert= 엔드포인트의 기본 경로; 실제로 UseDoconut()가 마운트된 ASP.NET 브랜치와 일치해야 합니다(보통 MiddlewarePath를 통해 조정됩니다) |
resPath | string | /doconut-res | 다른 Doconut 위젯과의 구성 일관성을 위해 허용됩니다; 변환 위젯은 현재 이를 사용해 URL을 생성하지 않습니다 |
maxUploadMb | number | 25 | 클라이언트 측 사전 검사만 수행 — 업로드 전에 파일이 너무 큰 경우 거부합니다. 서버는 자체 제한을 독립적으로 적용하며 초과 시 413 로 응답합니다 |
licenseUrl | string | null | null | 설정하면 결과 화면의 워터마크 알림을 이 URL에 대한 링크로 변환합니다 |
labels | object | {} | 위젯의 영어 기본 문자열(드롭 텍스트, 버튼, 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() 은 위젯 인스턴스 자체를 반환합니다 — 이를 보관하여 위젯을 프로그래밍 방식으로 제어하세요:
const conv = Doconut.convert('#doconut-convert', { basePath: '/doconut' });
const file = document.querySelector('#picker').files[0]; // 사용자 자신의 File <input type="file" id="picker">
conv.reset(); // idle/drop 화면으로 돌아갑니다; onReady를 다시 호출하지 않습니다
conv.loadFile(file); // File 객체로 흐름을 시작합니다; 현재 idle 상태가 아니면 no-op
conv.destroy(); // 리스너를 제거하고, mount를 비웁니다; 이후 instance는 사용할 수 없습니다레이블
모든 문자열은 영어 기본값을 가지고 있습니다; labels 은 일부를 재정의하고 나머지는 영어 그대로 유지합니다. 런타임에 변경되는 조각은 {placeholders} 를 사용하며, 예를 들어 uploading: 'Uploading {name}…' 와 pages: '{n} pages' 가 있습니다.
| 키 | 영어 기본값 |
|---|---|
dropPrompt | Drag & drop a document here |
dropHint | PDF, Word, Excel, PowerPoint, images and more |
chooseFile | Choose file |
uploading | Uploading {name}… |
page / pages | 1 page / {n} pages |
noTargets | No conversion targets are available for this file. |
convertTo / convert | Convert to / Convert |
converting | Converting to {target}… |
readyToDownload | Ready to download |
download / convertAnother | Download / Convert another |
watermarkNotice | Output is watermarked — get a license to remove it. |
retry | Retry |
genericError | Something went wrong. Please try again. |
sizeLimit | That file is larger than the {mb} MB upload limit. Please choose a smaller file. |
serverError | The server could not process this request. Please try again. |
networkError | Could 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 사용자 정의 속성에서 색상, 반경 및 글꼴을 읽어 내부를 건드리지 않고도 테마를 적용할 수 있습니다:
#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 (multipart, one file) | 소스 문서를 업로드하고 미리 보기를 위해 엽니다 | 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는 multipart 본문의 첫 번째 파일을 사용합니다.
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는 동일한 값입니다. 뷰어 결과를 닫아도 아직 유효한 다운로드 저장소는 삭제되지 않으며, 브라우저 위젯을 재설정해도 두 창 중 어느 것도 연장되지 않습니다.
실패 모드, 라우트별 그룹화:
| 라우트 | 상태 | 조건 | 본문 |
|---|---|---|---|
| any | 404 | 위젯이 활성화되지 않았습니다(AddConverterWidget()가 호출되지 않음) — 세 라우트가 처리되기 전에 확인됩니다 | status only |
| any | 405 | 잘못된 HTTP 메서드(open/run는 POST가 필요하고, download는 GET가 필요합니다) | status only |
open | 400 | 멀티파트 업로드가 아님 | Expected a multipart file upload. |
open | 400 | 파일이 없거나 비어 있습니다 | No file uploaded. |
open | 400 | 변환할 수 없는 소스 확장자 | This file type cannot be converted. |
open | 403 | 파일 유형에 라이선스가 제공하지 않는 기능이 필요합니다 (Dicom가 없는 DICOM 파일) | Converting this file type requires the Dicom capability license. |
open | 413 | 업로드 파일이 MaxUploadMb를 초과함, Content-Length와 비교하고 업로드를 읽는 동안 확인됩니다 | File is too large. |
run | 400 | 잘못된 토큰(GUID가 아님) | Invalid token. |
run | 400 | ConversionTarget로 파싱되지 않는 target | Unknown target format. |
run | 400 | target가 소스의 allowedTargets에 없습니다 | That target format is not available for this file. |
run | 404 | 저장된 업로드가 만료되었거나 토큰이 열리지 않음 | Upload expired — please re-open the file. |
open, run | 500 | 내부 처리 실패 | 정제된 메시지 — 다른 모든 Doconut 오류 경로와 동일하게 정제되며, 내부 세부 정보를 절대 노출하지 않습니다 |
download | 400 | 잘못된 토큰(GUID가 아님) | status only |
download | 404 | 알 수 없거나 만료된 다운로드 토큰 | status only |
fetch를 사용한 전체 라운드 트립:
// 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의 출처 아래에서 역프록시하십시오.
프로덕션에서
- 플러그인을 설치 코어 패키지 옆에, 동일한 버전으로:
dotnet add package Doconut.NET8.Converter. - 라이선스 파일을 추가합니다.
Doconut.Viewer.Converter.lic를Doconut.Viewer.lic와 같은 폴더에 넣습니다. - 서버 제한을 설정합니다.
MaxUploadMb은AddConverterWidget에서 서버가 적용하는 한계이며, 위젯의maxUploadMb은 클라이언트 측 검사일 뿐입니다. 두 값을 동일하게 유지하십시오. - UI를 동일한 출처에서 제공 하세요, Doconut 엔드포인트와 동일하게, 혹은 역프록시를 사용하세요 (참조: 직접 프런트엔드 구축).
- 변환 결과를 해제합니다. 스트림
ConvertAsync가 반환하는 것은 풀에 저장됩니다; 이를 해제하면 버퍼가 풀로 반환됩니다.
웹 팜
위젯은 각 업로드와 그 결과를 open 를 제공한 노드의 메모리에 보관합니다. 스티키 세션이 없는 로드 밸런서 뒤에서는, 이후의 run, download 또는 프리뷰 요청이 다른 노드에 도달해 업로드를 찾지 못할 수 있습니다. 공유된 암호화 위젯 스토어를 한 번만 등록하십시오, AddDoconut() 이후에:
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
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);
}의존성 주입으로 해결됩니다; 생성자는 internal 입니다. sourceExtension 은 앞에 점을 포함합니다. HtmlToWordAsync 은 outputFormat 가 ConversionTarget.Doc 일 때 .doc 파일을 쓰고, 다른 값에 대해서는 .docx 파일을 씁니다.
ConversionTarget
45개의 출력 형식은 Target formats 에 나열되어 있습니다.
ConverterWidgetOptions
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. from run) | 30분 창이 경과했거나, 웹 팜 노드에 업로드가 없음 | 파일을 다시 열고; 팜에서는 AddDoconutDistributedWidgets 를 등록하십시오. |
| UI가 다른 출처에 있을 때 위젯이 실패합니다 | 엔드포인트에 CORS 지원이 없음 | UI를 동일한 출처에서 제공하거나, Doconut 경로를 역프록시하십시오. |
| 테마가 적용되지 않음 | 변수가 상위 요소나 마운트 내부 요소에 설정되어 있음; 위젯 자체의 .dcw 규칙이 마운트에 설정함 | 마운트 자체를 대상으로 하세요: #doconut-convert.dcw 또는 #doconut-convert |
이 페이지가 도움이 되었나요?