컨버터 플러그인

문서를 45개의 대상 형식으로 변환

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

SurfaceUse it when
DocumentConverter (C#)서버에서 변환하며, 브라우저가 관여하지 않습니다
Drop-in widget (doconutConverter.js)페이지에 바로 사용할 수 있는 업로드, 변환 및 다운로드 화면을 원합니다
HTTP endpoints on DocImage.axd (?convert=open|run|download)문서화된 서버 계약에 따라 자체 변환 UI를 구축합니다

패키지 설치

powershell
Install-Package Doconut.NETFramework.Converter

이 문서에서 설명하는 릴리스에 플러그인을 고정하려면:

powershell
Install-Package Doconut.NETFramework.Converter -Version 26.10.0

Converter 패키지를 Doconut.NETFramework와 동일한 버전으로 유지하십시오.

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

플러그인 등록

모든 플러그인은 동일한 방식으로 등록됩니다: AddPlugin<TPlugin>()를 DoconutHost.Initialize에, Application_Start에서 호출합니다.

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

이것이 C# 파사드가 필요로 하는 전부입니다. 위젯과 그 HTTP 엔드포인트는 별도의 선택 사항이며, AddConverterWidget() (see 드롭인 위젯).

플러그인은 Converter 기능을 부여하는 라이선스가 필요합니다. 라이선스가 없으면 DoconutHost.Initialize가 Application_Start에서 예외를 발생시킵니다:

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.

System.Web에서는 모든 요청이 빈 500로 응답하며, 그 이유는 Windows 이벤트 로그(소스 ASP.NET)에만 기록됩니다. 라이선스가 없거나, 레거시 TRIAL 파일이 있거나, Converter가 없는 라이선스이거나, 버전 기간 외에 사용된 유료 라이선스인 경우 예외가 발생합니다. 임시 Demo/NFR 라이선스도 허용됩니다. 보세요 라이선스 설정.

라이선스 및 워터마크

License stateStartupConversion output
Paid viewer license granting Converter, within its version windowStartsClean — watermarked: false
Active Temporary (Demo/NFR) licenseStartsConverts, with the evaluation watermark — watermarked: true
Expired Temporary (Demo/NFR) licenseStartsConverts, with the evaluation watermark — watermarked: true
No license, a legacy TRIAL file, a license without Converter, or a paid license outside its version windowApplication_Start throws; every request answers an empty 500—

DocumentConverter 파사드와 위젯의 ?convert=run 핸들러는 동일한 규칙을 적용합니다. 구매 전에 평가 라이선스로 통합을 구축하고 엔드 투 엔드로 테스트할 수 있으며, 출력 바이트만 변경됩니다.

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

C#에서 사용

각 변환은 위치가 0인 탐색 가능한 MemoryStream를 반환합니다. DocumentConverter는 상태가 없으며, 필요할 때마다 DoconutHost.Services에서 해결하고 자유롭게 재사용할 수 있습니다.

csharp
// DoconutHost.Services에서 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<string>가 아니라 Task<Stream>를 반환합니다 — HTML 문서(이미지가 Base64로 삽입됨)는 다른 결과와 마찬가지로 스트림으로 도착합니다.

호출자는 변환이 반환하는 MemoryStream를 소유하며, 복사하거나 반환한 후에 이를 해제해야 합니다(MVC의 File(stream, …)가 이를 대신 해제합니다). DocumentConverter를 직접 생성하거나 해제하지 마십시오 — 생성자는 내부입니다.

MVC 5 컨트롤러에서

동작을 비동기로 만들고 변환을 await 하세요:

csharp
[HttpPost]
public async Task<ActionResult> ToPdf(HttpPostedFileBase file)
{
    var converter = Doconut.DoconutHost.Services.GetRequiredService<DocumentConverter>();
    Stream pdf = await converter.ConvertAsync(
        file.InputStream, Path.GetExtension(file.FileName), ConversionTarget.Pdf,
        password: null, ct: Response.ClientDisconnectedToken);
    return File(pdf, "application/pdf", Path.GetFileNameWithoutExtension(file.FileName) + ".pdf");
}

Web Forms: 변환을 절대 차단하지 마세요

Web Forms 페이지는 단일 스레드 요청 컨텍스트에서 실행됩니다. ConvertAsync는 완료될 때 해당 컨텍스트에서 재개되므로, 동기적으로 기다리는 페이지는 — .Result, .Wait(), .GetAwaiter().GetResult() — 변환이 완료되기 위해 필요한 바로 그 스레드를 점유합니다. 요청이 절대 반환되지 않습니다. 브라우저는 계속 회전하고, IIS는 아무 로그도 남기지 않으며, 사이트의 나머지 부분은 정상 작동하므로 이는 교착 상태라기보다 느린 변환처럼 보입니다.

페이지를 Async="true" 하고 변환을 페이지 비동기 작업으로 실행하세요:

aspx
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>
csharp
// Web Forms: @Page 지시어는 Async="true"가 필요하며, 변환은 페이지 비동기 작업으로 실행됩니다.
// 대신 .Result, .Wait(), .GetAwaiter().GetResult()와 같이 차단하면 요청이 교착 상태에 빠집니다:
// 요청이 절대 반환되지 않으며, 로그도 남지 않습니다.
protected void Page_Load(object sender, EventArgs e)
{
    if (!IsPostBack) return;

    RegisterAsyncTask(new PageAsyncTask(async ct =>
    {
        var converter = Doconut.DoconutHost.Services.GetRequiredService<DocumentConverter>();

        using (var pdf = await converter.ConvertAsync(
                   Server.MapPath("~/App_Data/contract.docx"), ConversionTarget.Pdf, ct: ct))
        using (var ms = new MemoryStream())
        {
            if (pdf.CanSeek) pdf.Position = 0;
            await pdf.CopyToAsync(ms);

            Response.ContentType = "application/pdf";
            Response.AddHeader("Content-Disposition", "attachment; filename=contract.pdf");
            Response.BinaryWrite(ms.ToArray());
            // Context를 사용하고, HttpContext.Current는 사용하지 마세요: await 후에는 후자가 null이 될 수 있습니다.
            Context.ApplicationInstance.CompleteRequest();
        }
    }));
}

@Page 지시문에 Async="true"가 없으면, RegisterAsyncTask은 조용히 무시됩니다. await 후에 페이지의 Context를 사용하세요; 그곳에서 HttpContext.Current은 null 될 수 있습니다.

대상 포맷

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, PSD, 웹 문서, DICOM)마다 허용되는 대상이 별도로 정의됩니다. DICOM 소스(.dcm, .ima)를 변환하려면 Dicom 기능을 부여하는 라이선스가 필요합니다; 해당 대상은 Pdf, Png, Jpeg, Bmp, Tiff 및 Gif입니다. 이 enum을 UI의 대상 목록으로 하드코딩하지 마세요: ?convert=open는 업로드된 파일에 대한 allowedTargets를 반환하며, 이는 선택기를 구동하는 데 사용되어야 합니다.

드롭인 위젯

엔드포인트 활성화

위젯의 ?convert=open|run|download 엔드포인트는 DocImage.axd에 의해 제공되며 기본적으로 비활성화되어 있습니다. 플러그인 등록 옆에서 이를 활성화하세요:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;
    });
});
// System.Web은 Doconut이 보기 전에 전체 업로드를 읽어들입니다: maxRequestLength (KB)와
// Web.config에서 위젯의 MaxUploadMb보다 큰 maxAllowedContentLength (bytes)를 설정하세요.

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

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.

위젯이 정상적으로 동작하지 않을 때 확인해야 할 두 가지:

  • basePath: '/DocImage.axd'. 위젯의 기본값인 /doconut는 ASP.NET Core 엔드포인트입니다. 이 패키지에서는 엔드포인트가 Web.config의 DocImage.axd 핸들러입니다.
  • 스크립트와 엔드포인트는 독립적입니다. 리소스 모듈은 위젯이 활성화되었는지 여부와 관계없이 doconutConverter.js를 제공합니다. AddConverterWidget()가 없으면 위젯은 로드되고 드롭 영역을 그리며 완전히 정상적으로 보이지만, 첫 번째 동작은 404를 반환합니다.

업로드 제한

ASP.NET은 DocImage.axd가 실행되기 전에 전체 요청 본문을 읽습니다. MaxUploadMb를 초과하지만 호스트 제한 이하인 업로드는 위젯 자체의 JSON 413(File is too large.)를 반환합니다. 호스트 제한을 초과하는 업로드는 IIS에 의해 먼저 거부되며, 위젯이 읽을 수 없는 오류 페이지가 표시됩니다. 위젯의 상한선 위에 Web.config에 두 개의 호스트 제한을 모두 유지하십시오:

xml
<system.web>
  <httpRuntime maxRequestLength="30720" />           <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
  <security>
    <requestFiltering>
      <requestLimits maxAllowedContentLength="31457280" />  <!-- BYTES: 30 MB -->
    </requestFiltering>
  </security>
</system.webServer>

삽입하기

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

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

옵션

옵션유형기본값비고
basePathstring/doconut엔드포인트 URL. 이 패키지에 '/DocImage.axd'을 설정하십시오
resPathstring/doconut-res다른 Doconut 위젯과의 일관성을 위해 허용됩니다; 변환기 위젯은 이를 사용해 URL을 생성하지 않습니다
maxUploadMbnumber25클라이언트 측 사전 확인만 수행합니다; 서버가 자체 상한선을 적용합니다
licenseUrlstring | nullnull결과 화면의 워터마크 알림을 링크로 전환합니다
labelsobject{}위젯의 영어 문자열 중 일부를 재정의합니다

콜백

콜백발생 시점페이로드
onReady()위젯이 드롭 화면을 렌더링했습니다—
onSourceLoaded({ token, pages, sourceExt, allowedTargets })?convert=open succeeds소스 토큰, 페이지 수, 소스 확장자(점 없이), 허용된 대상
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target })?convert=run succeeds실행 응답과 요청된 target
onDownload({ downloadName, downloadToken })사용자가 다운로드를 클릭함브라우저 자체 다운로드와 동시에 발생
onError({ phase, message })오픈 또는 실행 요청이 실패함phase은 'open' 또는 'run'이며; message은 정제된 서버 오류입니다

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

명령형 핸들

Doconut.convert()은 위젯 인스턴스를 반환합니다:

javascript
const conv = Doconut.convert('#doconut-convert', { basePath: '/DocImage.axd' });
const file = document.querySelector('#picker').files[0]; // 직접 선택한 File <input type="file" id="picker">
conv.reset();         // 드롭 화면으로 돌아갑니다; onReady를 다시 호출하지 않습니다
conv.loadFile(file);  // File로 흐름을 시작합니다; 위젯이 드롭 화면에 있을 때만 동작합니다
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 글꼴입니다.

자체 프런트엔드 구축

위젯은 DocImage.axd에 있는 이 HTTP 계약의 클라이언트입니다. 라우트는 AddConverterWidget()이 호출될 때까지 404을 반환합니다. 오류는 JSON 본문 { "error": "..." }을 포함하지만, 표에 "상태만"이라고 표시된 경우는 제외합니다. 알 수 없는 ?convert= 값은 400을 반환합니다.

경로목적성공 응답
POST /DocImage.axd?convert=open (multipart, one file)소스 문서를 업로드하고 열기200 — { token, pages, sourceExt, allowedTargets }
POST /DocImage.axd?token=<token>&convert=run&target=<ext>업로드된 소스를 target(으)로 변환200 — { downloadToken, resultToken, resultPages, downloadName, watermarked }
GET /DocImage.axd?convert=download&token=<downloadToken>변환된 파일을 스트리밍200 — 파일, Content-Disposition: attachment, Cache-Control: no-store

sourceExt은 open 응답에서 선행 점("docx")이 없으며, 이는 ConvertAsync의 sourceExtension 매개변수와 반대입니다. allowedTargets은 소문자 대상 이름("pdf", "html", …)을 나열합니다; 이 중 하나를 target로 전달하면 대소문자를 구분하지 않고 매칭됩니다. open은 multipart 본문의 첫 번째 파일을 사용합니다.

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

미리보기 이미지는 표준 뷰어 이미지 경로인 /DocImage.axd?token={token}&page=1&thumb=1&width={px}를 사용하며, open에서 가져온 token 또는 run에서 가져온 resultToken를 사용합니다. 위젯은 width=240을 요청합니다.

업로드된 소스는 마지막으로 읽은 후 30분 동안 보관됩니다; 그 이후에는 run이 404을 반환하고 파일을 다시 열어야 합니다. 변환이 완료되면 downloadToken은 자체 30분 창을 가집니다. resultToken은 결과를 미리 보기 위한 일반 뷰어 토큰이며, 결과를 미리 볼 수 있을 때는 downloadToken과 동일한 값입니다.

경로상태시점본문
모두404위젯이 활성화되지 않았습니다(AddConverterWidget()가 호출되지 않음)상태만
모두405잘못된 동사(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.
open413업로드가 MaxUploadMb를 초과합니다 (IIS 제한은 초과하지 않음)File is too large.
run400잘못된 형식의 토큰 (GUID가 아님)Invalid token.
run400target이(가) ConversionTarget로 파싱되지 않음Unknown target format.
run400allowedTargets에 없는 대상That target format is not available for this file.
run404업로드가 만료되었거나 열리지 않음Upload expired — please re-open the file.
open, run500처리 실패정제된 메시지
download400 / 404잘못된 형식이거나 알 수 없거나 만료된 다운로드 토큰상태만

fetch을(를) 사용한 전체 라운드 트립:

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

  // 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);
}

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

프로덕션 환경에서

  1. 플러그인 설치를 핵심 패키지 옆에, 동일한 버전으로: Install-Package Doconut.NETFramework.Converter.
  2. 라이선스 파일을 추가합니다. Doconut.Viewer.Converter.lic 를 Doconut.Viewer.lic 와 같은 폴더에 넣습니다.
  3. 업로드 제한을 설정합니다. MaxUploadMb in AddConverterWidget 은 Doconut이 적용하는 한도이며, maxRequestLength 와 maxAllowedContentLength 를 Web.config 에서 이를 초과하도록 유지하고 (업로드 제한 참고), 위젯의 maxUploadMb 도 동일하게 설정합니다.
  4. Web Forms에서 변환을 절대 차단하지 마세요 ( Web Forms에서 참고).
  5. 변환 결과를 해제합니다. 스트림 ConvertAsync 가 반환하는 것은 풀에 저장되며, 이를 해제하면 버퍼가 풀로 반환됩니다.

웹 팜

위젯은 open 를 제공한 서버의 메모리에 각 업로드와 그 결과를 보관합니다. 스티키 세션이 없는 로드 밸런서 뒤에서는 이후의 run, download 또는 미리보기 요청이 다른 서버에 도달해 업로드를 찾지 못할 수 있습니다. DoconutHost.Initialize 의 두 번째 인수를 통해 공유된 암호화 위젯 스토어를 등록하세요:

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

Doconut.DoconutHost.Initialize(
    options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
        options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
        options.AddConverterWidget();
    },
    services => 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);
}

DoconutHost.Services 로부터 해결됩니다; 생성자는 internal 입니다. sourceExtension 은 앞에 점을 포함합니다. outputFormat 이 ConversionTarget.Doc 일 때 HtmlToWordAsync 은 .doc 파일을 쓰고, 다른 값에 대해서는 .docx 파일을 씁니다.

ConversionTarget

45개의 출력 형식이 대상 형식 에 나열되어 있습니다.

ConverterWidgetOptions

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

DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null) 를 통해 설정하며, 이는 DoconutOptions 를 반환하므로 메서드 체이닝이 가능합니다.

문제 해결

증상원인해결책
플러그인을 추가한 후 모든 요청이 빈 500 로 응답합니다; Windows 이벤트 로그(소스 ASP.NET)에 The Converter plugin is registered via AddPlugin but no active license grants Converter. 가 표시됩니다.라이선스가 없거나, TRIAL 파일이 있거나, Converter 가 없는 라이선스, 혹은 버전 기간 외의 유료 라이선스Converter 를 부여하는 라이선스를 설치하거나, AddPlugin<ConverterPlugin>() 를 제거하십시오.
모든 요청이 빈 500 로 응답하고; 이벤트 로그에 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 가 등록되지 않았습니다.DoconutHost.Initialize 에 AddPlugin<ConverterPlugin>() 를 추가하십시오.
Web Forms 변환이 절대 반환되지 않습니다.페이지가 ConvertAsync 에서 차단됩니다.Async="true" 와 RegisterAsyncTask 를 사용하십시오.
스트림 변환에서 형식이 지원되지 않는다고 표시됩니다.sourceExtension 에 앞점이 없습니다."xlsx" 대신 ".xlsx" 를 전달하십시오.
ConvertAsync 가 Converting '.dcm' requires the Dicom capability license. 를 발생시킵니다.DICOM 소스이며, 라이선스가 Dicom 를 부여하지 않습니다.Dicom 를 부여하는 라이선스를 사용하십시오.
출력에 워터마크가 표시됩니다.라이선스가 임시(Demo/NFR)입니다.Converter 를 부여하는 유료 라이선스를 사용하십시오.
위젯은 로드되지만 요청이 404 로 반환됩니다.AddConverterWidget() 가 호출되지 않았거나, basePath 가 '/DocImage.axd' 가 아닙니다.AddConverterWidget() 를 호출하고; basePath: '/DocImage.axd' 를 설정하십시오.
대용량 업로드 시 위젯 메시지 대신 IIS 오류 페이지가 표시됩니다.maxRequestLength / maxAllowedContentLength 가 MaxUploadMb 이하입니다.Web.config 제한을 MaxUploadMb 이상으로 올리십시오.
open 가 403 Converting this file type requires the Dicom capability license. 로 응답합니다.DICOM 업로드이며, 라이선스가 Dicom 를 부여하지 않습니다.Dicom 를 부여하는 라이선스를 사용하십시오.
run 가 400 That target format is not available for this file. 로 응답합니다.대상이 소스의 allowedTargets 중 하나가 아닙니다.convert=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.

프레임워크 참고 사항

ASP.NET Core 패키지와 비교할 때, 이 패키지는 호스팅만 다르며; API, 엔드포인트 계약, 위젯 스크립트 및 라이선스 규칙은 동일합니다.

  • 등록은 Application_Start 에 있으며, DoconutHost.Initialize 를 통해, builder.Services.AddDoconut 대신 사용합니다. AddDoconutDistributedWidgets 와 같은 서비스는 두 번째 인수에 전달됩니다.
  • 엔드포인트는 DocImage.axd 로 제공되고 스크립트는 DoconutResourceModule 로 제공되며, 두 모두 Web.config 에 등록됩니다, UseDoconut() 와 UseDoconutResources() 대신. 위젯은 basePath: '/DocImage.axd' 가 필요합니다.
  • 시작 실패는 모든 요청에서 빈 500 로 나타나며, 이유는 Windows 이벤트 로그에 기록됩니다.
  • 업로드는 Doconut 이 보기 전에 ASP.NET 에 의해 전체가 읽히므로, IIS 제한은 MaxUploadMb 이상이어야 합니다.
  • Web Forms 페이지는 변환 중에 차단되지 않아야 합니다; Web Forms에서 를 참조하십시오.
  • Windows 전용이며, .NET Framework 패키지의 나머지와 동일합니다.

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