コンバータープラグイン

ドキュメントを45の対象フォーマットに変換

Converter プラグインは Doconut をドキュメント変換サービスに変えます。DocumentConverter の公開ファサードの背後にあるエンジンと、オプトインで DocImage.axd が提供するドロップインウィジェットを提供するので、C# から、ウィジェットから、または自分で作成したフロントエンドからドキュメントを変換できます。

対象使用シーン
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() です(ドロップインウィジェット を参照)。

プラグインは 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 が欠けたライセンス、バージョンウィンドウ外で使用された有料ライセンスに対して例外がスローされます。一時的なデモ/NFR ライセンスは受け入れられます。ライセンス設定 を参照してください。

ライセンスと透かし

ライセンス状態起動時変換出力
バージョンウィンドウ内で Converter を付与する有料ビューアライセンス開始クリーン — watermarked: false
有効な一時(デモ/NFR)ライセンス開始変換し、評価用透かし — watermarked: true が付与されます
期限切れの一時(デモ/NFR)ライセンス開始変換し、評価用透かし — watermarked: true が付与されます
ライセンスなし、レガシー TRIAL ファイル、Converter が欠けたライセンス、またはバージョンウィンドウ外の有料ライセンスApplication_Start がスローされ、すべてのリクエストが空の 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: HTML を保持し、Word 文書に戻すための 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();
        }
    }));
}

Async="true" が @Page ディレクティブに含まれていない場合、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、web document、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 の maxAllowedContentLength (bytes) をウィジェットの MaxUploadMb より上位に設定してください。

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.

ウィジェットが期待通りに動作しない場合に確認すべき 2 つの点:

  • 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]; // 自分の <input type="file" id="picker"> からのファイル
conv.reset();         // ドロップ画面に戻ります; onReady を再度発火しません
conv.loadFile(file);  // File でフローを開始します; widget がドロップ画面にある場合を除き何もしません
conv.destroy();       // リスナーを削除し、mount を空にします; これ以降 instance は使用できません

ラベル

すべての文字列には英語のデフォルトがあります;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": "..." })を持ちますが、テーブルに「status only」と記載されている場合は除きます。未知の ?convert= 値は 400 を返します。

ルート目的成功レスポンス
POST /DocImage.axd?convert=open (マルチパート、1 ファイル)ソースドキュメントをアップロードして開く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 はマルチパートボディの最初のファイルを使用します。

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() が呼び出されていません)ステータスのみ
任意405HTTP メソッドが間違っています(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);
}

エンドポイントは same-origin です:このバージョンは 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 が返すものはプールされており、破棄するとバッファがプールに戻ります.

Web ファーム

ウィジェットは、open を提供したサーバー上のメモリに各アップロードとその結果を保持します。スティッキーセッションのないロードバランサーの背後では、後続の run、download、またはプレビューリクエストが別のサーバーに到達し、アップロードが見つからないことがあります。DoconutHost.Initialize の第2引数を通じて、共有された暗号化ウィジェットストアを登録します:

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 bytes、すべてのサーバーで同一
        // store.Ttl = TimeSpan.FromMinutes(30);   // アップロードが保持される期間(デフォルト)
    }));
  • 単一サーバーでは何も必要ありません:この呼び出しがなければインメモリストアが使用されます。
  • アップロードと結果は共有領域で保存時に暗号化されます(AES-256、encrypt-then-MAC)、各ファイルはトークンに紐付けられるため、あるトークンが別のトークンのファイルを読むことはできません。
  • 共有領域では、アップロードまたは結果は書き込まれた後 Ttl の間保持されます;読み取ってもその期間は延長されません。
  • FarmKey は少なくとも 32 バイトで、すべてのサーバーで同一である必要があります。シークレットストアからロードし、ハードコードしないでください。登録時に RootPath が欠如しているか FarmKey が 32 バイト未満の場合、ArgumentException がスローされます。
  • RootPath を、分散ビューアが使用するのと同じ共有場所に設定します。

API リファレンス

ファサードとウィジェットオプションは 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 には先頭のドットが含まれます。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 が返され、呼び出しをチェーンできます。

トラブルシューティング

症状原因対策
プラグインを追加した後、すべてのリクエストが空の 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 を付与するライセンスを使用してください
出力に透かしが入っていますライセンスが一時的です(デモ/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 を返します(run からの Upload expired — please re-open the file.)30 分ウィンドウが経過したか、ファーム内の別サーバーにアップロードがありませんファイルを再度開いてください;ファーム内では AddDoconutDistributedWidgets を登録してください
UI が別オリジンにあるとウィジェットが失敗しますエンドポイントが CORS をサポートしていませんUI を同一オリジンから提供するか、Doconut パスをリバースプロキシしてください
テーマが適用されません変数が祖先要素またはマウント内部の要素に設定されており、ウィジェット自身の .dcw ルールがマウント上に設定していますマウント自体を対象にしてください:#doconut-convert.dcw または #doconut-convert

フレームワークの注意点

ASP.NET Core パッケージと比較して、このパッケージはホスティングのみが異なります。API、エンドポイント契約、ウィジェットスクリプト、ライセンス規則は同じです。

  • 登録 は Application_Start にあり、DoconutHost.Initialize を通じて行われ、builder.Services.AddDoconut ではありません。AddDoconutDistributedWidgets のようなサービスは第2引数に入ります。
  • エンドポイント は DocImage.axd によって提供され、スクリプトは DoconutResourceModule によって提供され、どちらも Web.config に登録され、UseDoconut() と UseDoconutResources() ではありません。ウィジェットは basePath: '/DocImage.axd' が必要です。
  • 起動失敗 はすべてのリクエストで空の 500 として現れ、理由は Windows イベントログに記録されます。
  • アップロード は Doconut が見る前に ASP.NET によって全体が読み取られるため、IIS の制限は MaxUploadMb より上である必要があります。
  • Web Forms ページは変換でブロックしてはいけません;Web Forms で を参照してください。
  • Windows のみ、.NET Framework パッケージの残りと同様です。

このページは役に立ちましたか?