トラブルシューティング
一般的なエラーを診断する
以下のメッセージはすべて Doconut が生成する文字列で、症状別に整理されています。エラーを見つけて、修正を適用してください。
ビューアが何も表示しない
ビューア領域が空で、ブラウザコンソールに /doconut-res/... に対する 404 が多数表示
UseDoconutResources() が欠落しているか、UseDoconut() の後に配置されています。パイプラインの最初に配置する必要があります。
ビューアが The viewer handler could not be reached (no response). を報告
リクエストは応答を受け取っていません。一般的な原因は、BasePath が / で始まっていることです:'/doconut' が //doconut/DocImage.axd に変わり、別のホストへのリクエストになります。先頭のスラッシュ(BasePath: 'doconut')を除いて記述してください。
ビューアが Please make sure your middleware is configured. を報告
ページエンドポイントは 404 と応答しました:UseDoconut() がクライアントの BasePath が指す場所にマウントされていません。app.Map("/doconut", branch => branch.UseDoconut()) を使用すると、クライアントは BasePath: 'doconut' を使用します。
HTTP 500 とともに:
Session middleware not configured. Call UseSession() before UseDoconut().Doconut のトークンセキュリティ(デフォルトで有効)は ASP.NET のセッション状態が必要です。builder.Services.AddSession() と app.UseSession() を Doconut ミドルウェアブランチの 前に 追加してください。セッション状態にはキャッシュも必要です:最小限の API アプリでは builder.Services.AddDistributedMemoryCache() を追加するか、Unable to resolve service for type 'IDistributedCache' が原因で起動時にアプリが停止します(MVC および Razor Pages アプリはすでに登録されています)。
ページ領域に表示されるエラー画像の内容:
You Are Not Authorized To View This Page.トークンが別のブラウザセッションで開かれました。典型的な原因は、セッションクッキーがページリクエストに届かないこと(クロスオリジン設定、SameSite ポリシー、クッキー保存機能のない API クライアント)や、アプリの再起動(新しいセッションキー)です。これは設計通りに機能しているセキュリティ層です — Core Concepts → Sessions & Security を参照してください。拒否はステータス 200 で提供される画像であるため、ステータスコードのみをチェックするモニタはそれをページとしてカウントします。
エラー画像の内容:
Document session not found. Please re-open document.トークンが期限切れ(スライディングウィンドウ、デフォルト 60 分 — DocOptions.TimeOut)またはセッションが閉じられました。新しいトークンを取得するためにドキュメントを再度開いてください。
サーバーは正常だがページが誤動作する — エラーが全く表示されない場合
これらはアプリケーションを引き継いだ後に最初に疑うべき障害モードです。3 つすべてがサーバーを正常に動作させ、ドキュメントを正しくレンダリングし、ブラウザコンソールに何も報告しません。
決して止まらないスピナー
ビューアのコールバックは、コンテナ ID にちなんだグローバル関数(ctlDoc_OnViewerReady() など)として宣言されています。以前のビューアはそれらの名前を検索しましたが、こちらは検索しません。スピナーを非表示にするハンドラは実行されず、関数をオプションとして渡す必要があります:
function ctlDoc_OnViewerBusy() { /* ビジーインジケータを表示 */ }
function ctlDoc_OnViewerReady() { /* 非表示にする */ }
function ctlDoc_Copy(text) { /* コピーしたテキストを使用する */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* 進捗を報告する */ }
const objViewer = $('#div_ctlDoc').docViewer({
// ... 既存のオプション ...
onViewerBusy: ctlDoc_OnViewerBusy,
onViewerReady: ctlDoc_OnViewerReady,
onCopy: ctlDoc_Copy,
onAutoLoadStatus: ctlDoc_AutoLoadStatus
});スピナーの背後のドキュメントは問題ありません。完全なオプション一覧は ビューア構成 にあります。
ビューアのアイコンや Chrome が欠落しているが、ページはそれ以外は正しい
ResPath が空であるか、アプリケーションルートを指しています — 以前のライブラリでは正しく、こちらでは間違っています。UseDoconutResources() がマウントするプレフィックス名を指定する必要があります:
ResPath: 'doconut-res/images' // または '<your ResourcesPath>/images'共有ストレージから提供する際の後続ページのタイルが壊れる
まだ書き込み中のページは 202 Accepted と応答します。retryOn409: true がないクライアントはそれを失敗した画像として扱います。分散デプロイ を参照してください。
ドキュメントのオープンに失敗する
LicenseException が拒否メッセージとともに — ライセンスファイルは見つかりましたが、無効な署名、改ざん、ブラックリスト登録、またはライセンスのバージョン/更新ウィンドウ外のビルドのために拒否されました。この状態は、透かしに劣化させるのではなく、オープンをブロックします(即座に失敗)。理由については License.RejectionMessage を参照してください。
LicenseException:
This document type requires the 'Dicom' plugin license.拡張子はプラグイン(ここでは DICOM)だけで処理されます。プラグインは登録されていますが、もはや機能を許可するライセンスがありません — 通常、アプリ起動後に期限切れとなった一時ライセンスです。機能を許可するライセンスをインストールし、IsCapabilityGranted(LicenseCapability.Dicom) を IDoconutLicenseService で確認してください。欠落または不十分な非一時的権利は通常、AddDoconut() の段階で早期に失敗します。
FormatNotSupportedException:
Document format '<extension>' is not supported.組み込み、プラグイン、またはカスタムのいずれのビューアもその拡張子をサポートしていません。サポートされているフォーマット一覧を確認してください;独自フォーマットの場合、DoconutOptions.RegisterViewer が追加できます。
InvalidDataException — ファイル内容が破損しているか、拡張子と一致しません(例:名前を変更したファイル)。オープンする前にアップロードを検証してください。
InvalidOperationException:
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().コンバータプラグインを登録せずに DocumentConverter を解決しました。
起動に失敗する
InvalidOperationException が AddPlugin を介して登録されたプラグインに言及 — 現在の非一時的ライセンスはそのプラグインの機能を許可していません。登録を削除するか、機能を許可するライセンスをインストールしてください。ライセンスが欠如している場合やレガシー TRIAL ファイルはプラグイン機能を付与しません。
ArgumentException from AddDoconut():
DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.即座に失敗するオプションの検証 — 問題のあるパスを修正してください。
ビルド / 依存関係エラー
パッケージはまったくインストールできません — Doconut.NETStandard は netstandard2.1 を対象としているため、NuGet は .NET Framework プロジェクトを拒否します。これは解決可能な復元エラーではなく、.NET Framework は netstandard2.1 を利用できません。代わりに Doconut.NETFramework パッケージを使用してください。
コンパイラエラー CS1705、またはドキュメントを開く際のランタイムエラー:
Could not load file or assembly 'System.Text.Json, Version=9.0.0.0'プロジェクトは System.Text.Json または System.Text.Encodings.Web を Doconut.NETStandard が宣言した 9.0.x の依存関係より下位に固定しています。ダウングレードを削除し、NuGet にパッケージグラフを復元させてください(System.Text.Json 9.0.0 と System.Text.Encodings.Web 9.0.0 はパッケージが宣言しています)。
パッケージをバンプした直後に多数のコンパイルエラーが発生 — これは予想通りです。26.8.0 は 26.7.0 とは異なる API 表面であり、互換性のある更新ではありません。エラーの多くは using 行がルート Doconut 名前空間へ移動したことによるものです。個別にパッチを当てるのではなく、Migrate to .NET Standard 2.1 を実施してください。
最初のプレゼンテーションファイルでの TypeInitializationException:
Could not load ... System.Drawing.Common, Version=6.0.0.0プレゼンテーションエンジンは System.Drawing.Common 6.0.0 を厳密に要求します(パッケージが宣言)。この依存関係を削除または上書きしないでください — これがないとすべての PPT/PPTX/PPS/POT/ODP のオープンが失敗します。
出力が正しくない
ページに透かしが付く — アプリは評価モードです:ライセンスファイルが見つからない、期限切れの一時ライセンス、または無効なドメインです。アクティブな一時ライセンス下では、プラグインの出力のみが透かし付けられます。有料ライセンスのサブスクリプション日以降にリリースされたビルドは透かしが付かず、オープン時に LicenseException がスローされます。IDoconutLicenseService を確認してください(License.IsLicenseFileFound、IsExpired、IsVersionValid、IsValidForDomain、License.RejectionMessage)— ライセンスページの IDoconutLicenseService 参照は既成のエンドポイントを示しています。
レガシードキュメントが文字化けして表示される — コードページエンコーディングがデフォルトでロードされていません。起動時に一度追加してください:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);フォントが間違っている、または置き換えられている — サーバーにドキュメントのフォントがありません。フォントをインストールするか、FontFolders を(WordConfig/PptConfig 上で)それらが格納されたフォルダーに指すよう設定してください。
画像の注釈はビューアに表示されるが、エクスポート時に「Image blocked」ボックスが出る — 画像のホストがプライベートまたはループバックアドレスであり、サーバーが取得を拒否しています。Annotations を参照してください。
評価時には機能し、製品環境では無効
典型的な本番稼働時の驚きとして、アクティブな Temporary ライセンスはすべての機能を付与しますが、購入したライセンスは購入した分だけしか提供しません。検索や注釈のバンドルは、機能が存在しない場合に消えることがあります。登録済みの Converter や DICOM プラグインが一時的でないライセンスが不足していると、AddDoconut() 中に失敗します。IsCapabilityGranted(...) を、デプロイ前に有効化するすべての機能と比較してください。
検索で何も見つからない(または少なすぎる)
- 直接 PDF の場合、
AllowSearchはオープン時に有効になっていませんでした。Word、Excel、PowerPoint は同じスイッチをネストされたPdfConfigを通じて提供します。 - コンテンツがスキャンされた画像のみの場合、通常の検索では一致するテキスト層がありません。テキストを含むソースまたはテキストを保持した PDF 投影を使用してください。
- HTML と MS Project (MPP) はデフォルト設定では検索できません —
DefaultRender = falseを設定して、PDF 投影を介してネイティブテキスト層でレンダリングさせます。Word、Excel、PowerPoint、TXT、Visio、メール、EPUB、MHT はカタログのデフォルト設定で検索できます。 objViewer.CanSearch()は初期化後にfalseです — 解決された形式には標準的な検索パスがありません。この判定は Search ライセンスとは別で、両方を確認してください。- ページは
objViewer.Search(...)の戻り値を読み取ります — カウントは第3引数のコールバックで返されます。
まだ解決できませんか?
最小限の Quick Start アプリで問題を切り分けてください。そこで再現する場合は、ドキュメント、Program.cs、ライセンス診断出力を添えてサポートに連絡してください。
このページは役に立ちましたか?