クイックスタート
数分で最初のドキュメントをレンダリング
このウォークスルーは、空の Program.cs からブラウザーでレンダリングされたドキュメントへと ASP.NET Core アプリを導きます:サーバー登録、完全な Viewer パッケージ(Viewer ツールバー、Viewer マウント、オプションの検索/注釈リボン)、アセット参照、クライアント初期化、ドキュメントのオープン、そして実行。
サーバー設定
AddDoconut() はサービスを登録します;UseDoconutResources() と UseDoconut() はミドルウェアを接続します。リソース呼び出しは最初に行う必要があります。UseDoconut() は届いたすべてのリクエストに応答するので、app.Map を使用して独自のブランチにマウントしてください。セッション呼び出しも必要です — Doconut のデフォルトドキュメントセキュリティは、すべてのページリクエストを ASP.NET セッション状態と照合して検証します。セッション状態にはキャッシュが必要です:AddDistributedMemoryCache() がそれを提供します。MVC または Razor Pages アプリはすでに登録されていますが、最小 API アプリは登録しておらず、Unable to resolve service for type 'IDistributedCache' が発生して起動時に停止します。すでに インストール 中に Doconut を登録しましたか?次のセクションへ進んでください。
builder.Services.AddDoconut(options =>
{
options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // session state にはキャッシュが必要です (MVC/Razor Pages はすでに追加されています)
builder.Services.AddSession(); // Doconut ドキュメントセキュリティは ASP.NET セッションステートに依存しています
app.UseSession(); // UseDoconut() の前に UseSession() を呼び出してください
app.UseDoconutResources(); // UseDoconut() の前に登録する必要があります
app.Map("/doconut", branch => branch.UseDoconut());本番環境スタイルのパスレイアウトの場合、ドキュメントミドルウェアを明示的なブランチにマッピングし、4 つのパス設定を揃えてください:
builder.Services.AddDoconut(options =>
{
options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
options.MiddlewarePath = "/doconut";
options.ResourcesPath = "/doconut-res";
options.UnsafeMode = false;
});
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();
app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());MiddlewarePath は調整用の値であり、単体で ASP.NET Core のブランチをマッピングするものではありません。この例ではホストが /doconut をマッピングするため、クライアントは BasePath: 'doconut' を使用します。ResourcesPath は /doconut-res に埋め込みバンドルを提供し、ウィジェットの画像リソースパスはそのため ResPath: 'doconut-res/images' になります。両方とも 先頭スラッシュなし で記述してください:ビューアが自動でスラッシュを付加するため、'/doconut' は //doconut/DocImage.axd になり、ブラウザはそれを doconut というホストへのリクエストと解釈し、ビューアは "The viewer handler could not be reached" というエラーで失敗します。
ページにビューアを追加
Viewer はページに必須のコアです。そのレンダリングサーフェスは 2 つの入れ子になった div を使用します:
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>ツールバー、モジュールマウント、そして Viewer サーフェスを 1 つのページ構成として扱います。 検索と 注釈は埋め込みリボンをオプションのマウントに注入しますが、これらのモジュールは決して 単独では使用されません:常に同じページの Viewer にアタッチされます。この順序で使用してください:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Viewer のナビゲーション、ズーム、検索、アノテーションボタン -->
</nav>
<div id="searchBarMount"></div>
<div id="annBarMount"></div>
<div id="divDocViewer">
<div id="div_ctlDoc"></div>
</div>ビューアアセットを参照
Razor ビューでは、注入された Viewer サービスが依存順序でビューアの <link> と <script> タグを出力します — ウィジェットは jQuery プラグインであるため、viewer スクリプトの前に jQuery をロードする必要があります:
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
IncludeBootstrapCss = true,
IncludeViewerCss = true
}))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeBootstrap = true,
IncludeViewerScripts = true
}))完全な Viewer パッケージを取得するには、Viewer とモジュールのリソースを一緒にリクエストします:
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
IncludeBootstrapCss = true,
IncludeViewerCss = true,
IncludeSearchCss = true,
IncludeAnnotationCss = true
}))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeBootstrap = true,
IncludeViewerScripts = true,
IncludeSearchScripts = true,
IncludeSearchBar = true,
IncludeAnnotationScripts = true,
IncludeAnnotationBar = true
}))IncludeViewerCss と IncludeViewerScripts は必須のコアフラグです。決して公開しないでください
それら、Viewer マウント、そして docViewer がない検索または注釈リボンの例
インスタンス。ReferenceCss と ReferenceScripts は、現在のライセンスがその機能を許可していない場合、オプションモジュールのリソースを省略します
現在のライセンスがその機能を許可していない場合でも、コア Viewer は起動し続けます。
ビューアの初期化
クライアント側ウィジェットは jQuery プラグインです。これは実際の初期化オプションの最小セットです(疑似コードではありません)。
let searchBar = null;
let annBar = null;
const objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
pageZoom: 100,
FitType: 'width',
BasePath: 'doconut', // 先頭に '/' がありません
ResPath: 'doconut-res/images', // 先頭に '/' がありません
onViewerReady: function () {
// ページが表示されています; ここでローディングスピナーを非表示にしても安全です
},
// 埋め込みリボンが存在する場合、アノテーションのライフサイクルイベントを転送します。
onAnnLoaded: () => annBar?.handleAnnLoaded(),
onAnnSaved: () => annBar?.handleAnnSaved(),
onAnnSaveError: () => annBar?.handleAnnSaveError(),
onAnnClosed: () => annBar?.handleAnnClosed(),
onError: function (message) {
console.error('Doconut viewer error:', message);
}
});オプションのケースは実際に混在しています — showThumbs、autoLoad、pageZoom は camelCase ですが、FitType、BasePath、ResPath は PascalCase です。一貫した規則はなく、ケースが間違っているとオプションは黙って無視されます(ウィジェットは例外を投げる代わりにデフォルトにフォールバックします)。
さらに4つの詳細はエラーメッセージなしで失敗します:
BasePathに先頭スラッシュがありません。'doconut'は/doconut/DocImage.axdをリクエストし、'/doconut'は//doconut/DocImage.axdを生成します。ブラウザはこれを別のホストへのリクエストとして読み取ります。ResPath: 'doconut-res/images'— アイコンはリソースルートの1つ下のフォルダーにあります。'doconut-res'を使用すると、すべてのアイコンが404を返します:ツールバーのグリフもロードスピナーもありませんが、ドキュメント自体はまだレンダリングされます。先頭スラッシュはBasePathと同様に壊します。- コールバックはオプションです。
onViewerReady、onErrorおよびその他はdocViewer(...)に渡されるオブジェクトに入れます。ビューア名のグローバル関数(例:ctlDoc_ViewerReady)は決して呼び出されません。 - ビューアを保持し、
Viewを別途呼び出します。docViewer(...)はZoom、Next、FitTypeを含むオブジェクトを返します;View(...)は別のものを返します。var objViewer = $('#div_ctlDoc').docViewer({...}).View(token)はドキュメントをレンダリングし、最初のツールバンクリックでobjViewer.Zoom is not a functionに失敗します。
完全な Viewer パッケージの組み立て
完全なビューアページは以下のパーツを一緒にインストールします:
| パッケージの構成要素 | 要件 | 接続方法 |
|---|---|---|
Viewer リソース、マウント、そして objViewer | 必須 | コアドキュメントレンダラ |
| Viewer ツールバー | 完全なページに必須 | ホストマークアップ;ボタンは同じ objViewer を呼び出します |
| 検索リボン | オプション、ライセンスモジュール | doconutSearchBar(...).attach(objViewer) |
| 注釈リボン | オプション、ライセンスモジュール | doconutAnnotationBar(...).attach(objViewer) |
メインの Viewer ツールバーはホストマークアップですが、Viewer と共にインストールされ、単独のコントロールとして文書化してはなりません。これにより、レイアウト、ラベル、アイコン、認可ルールはアプリケーション側で管理でき、すべてのボタンが同じ Viewer インスタンスを操作します:
<nav id="toolbar" aria-label="Document viewer controls">
<button type="button" onclick="objViewer.GotoPage(1)">First</button>
<button type="button" onclick="objViewer.Next(false)">Previous</button>
<button type="button" onclick="objViewer.Next(true)">Next</button>
<button type="button" onclick="objViewer.GotoPage(objViewer.TotalPages())">Last</button>
<button type="button" onclick="objViewer.Zoom(false)">Zoom out</button>
<button type="button" onclick="objViewer.Zoom(true)">Zoom in</button>
<button type="button" onclick="objViewer.FitType('width')">Fit width</button>
<button type="button" onclick="objViewer.FitType('height')">Fit height</button>
<button type="button" id="openSearch">Search</button>
<button type="button" id="openAnnotations">Annotations</button>
</nav>回転、サムネイル、印刷、全画面、レイアウト、ボタン状態ヘルパーは、同じ objViewer を呼び出す独自のツールバースクリプトに含めます。Viewer.ReferenceScripts(...) の後にロードし、<nav id="toolbar"> マークアップと一緒に保持してください。
以下の初期化順序を守ってください:
- Viewer とライセンスモジュール用の CSS を出力します。
- Viewer ツールバー、検索/注釈マウント、そして Viewer マウントを一緒にレンダリングします。
- Viewer とライセンスモジュール用のスクリプトを出力します。
- ホストアプリケーション独自のツールバーヘルパースクリプトをロードします。
docViewerを初期化し、結果として得られるobjViewerを保持します。- 各ライセンスされた検索または注釈リボンを初期化します。
- すべてのリボンで
attach(objViewer)を呼び出します。 - ドキュメントを開き、Viewer とモジュールのリクエスト用にそのトークンを保持します。
分散デプロイメントでは、追加の access リクエスト値と非同期レンダリングのリトライ設定はトランスポートに属し、Viewer、ツールバー、またはリボンの組み立て方法は変わりません。
サーバー側のガードは重要です:オプション機能が利用できない場合、そのスクリプトは出力されず、jQuery プラグイン関数も存在しません。
<script>
let token = '';
const refitViewer = () =>
requestAnimationFrame(() => objViewer.Refit());
@if (Viewer.IsSearchEnabled)
{
<text>
searchBar = $('#searchBarMount').doconutSearchBar({
docId: 'ctlDoc',
getRequestParams: () => ({ token }),
onLayout: refitViewer
});
searchBar.attach(objViewer);
</text>
}
@if (Viewer.IsAnnotationEnabled)
{
<text>
annBar = $('#annBarMount').doconutAnnotationBar({
docId: 'ctlDoc',
getRequestParams: () => ({ token }),
onLayout: refitViewer
});
annBar.attach(objViewer);
</text>
}
document.getElementById('openSearch').addEventListener('click', () => {
if (!searchBar) return;
searchBar.isOpen() ? searchBar.close() : searchBar.open();
});
document.getElementById('openAnnotations').addEventListener('click', () => {
if (!annBar) return;
annBar.isOpen() ? annBar.close() : annBar.open();
});
</script>埋め込みコンポーネントはそれぞれ独自のリボン DOM を生成します。検索は Find、Options、Results グループを含みます。注釈は作成ツール、スタイルコントロール、保存アクション、そしてオプションのエクスポート/画像アクションを含みます。これらのバーは open()、close()、reset()、isOpen() を公開します;作成後は必ず attach(objViewer) を一度呼び出してください。
上記の例では、起動を最小限に抑えるためにオプションのホストコールバックと注釈のエクスポート/画像エンドポイントを省略しています。完全な機能別設定については 検索 と 注釈 を参照してください。また、ホスト所有の Viewer ツールバーをスタイル変更または置き換えるには カスタムテーマ をご覧ください。
ドキュメントを開く
サーバー側は単一のエンドポイントです: 注入された Viewer サービスがドキュメントを開き、セッショントークンを返します。
app.MapPost("/api/open", async (Viewer viewer) =>
{
// トークンは不透明です — ウィジェットに渡し、決してログに記録したり永続化したりしないでください。
string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
return Results.Ok(new { token });
});クライアントはそのトークンを取得し、objViewer.View(token) を使用してウィジェットに渡します:
fetch('/api/open', { method: 'POST' })
.then(resp => resp.json())
.then(data => {
token = data.token;
objViewer.View(token);
});ドキュメントを閉じる
ユーザーがビューアを離れるか代替ドキュメントを開くときに objViewer.Close(true) を呼び出します: ウィジェットをクリアし、サーバーにクローズリクエストを送信します。引数なしで objViewer.Close() を呼び出すとウィジェットのみがクリアされます。サーバー主導のワークフローでは、viewer.CloseDocument(token) はキャッシュされたセッションを即座に削除し、レンダリングエンジンを破棄し、セキュリティマーカーを削除し、トークンを無効化します。スライディング有効期限は最終的に同じクリーンアップを行いますが、大きなドキュメントの場合は明示的なクローズが推奨されます。
完了したリクエストフローは次のとおりです:
AddDoconut + middleware
-> render CSS/scripts and mount div
-> initialize docViewer
-> OpenDocumentAsync
-> return opaque token
-> objViewer.View(token)
-> page/search/annotation requests
-> Close / CloseDocumentトークンはベアラークレデンシャルのように扱ってください: ログに記録せず、永続化せず、ウィジェットにのみ渡します。トークンはサーバー上のライブドキュメントセッションを識別し、そのセッションが期限切れになると機能しなくなります — 新しいトークンを取得するにはドキュメントを再度開いてください。
実行方法
wwwroot/files/Sample.pdf に PDF を配置し、dotnet run を実行し、ウィジェットをホストするページを開きます。最初のページがビューアに表示され、左側にサムネイルパネルが表示されます。表示されない場合は、トラブルシューティングをご覧ください。
ライセンスなしで得られるもの
ライセンスがない場合でも例外は発生しません。ビューアは通常通りレンダリングされますが、すべてのページに評価用の透かしが付加されます。Doconut がライセンスを取得する方法と取得後の変化については、ライセンス設定をご覧ください。
このページは役に立ちましたか?