クイックスタート

数分で最初のドキュメントをレンダリング

このハンドブックでは、空の Program.cs からブラウザーでレンダリングされたドキュメントまで、ASP.NET Core アプリを段階的に構築します:サーバー登録、完全な Viewer パッケージ(Viewer ツールバー、Viewer マウント、オプションの検索/注釈リボン)、アセット参照、クライアント初期化、ドキュメントのオープン、そして実行。

ホストアプリケーションは、netstandard2.1 をサポートするランタイム(.NET Core 3.0 以降)を対象とする必要があります。

サーバー設定

AddDoconut() はサービスを登録します;UseDoconutResources() と UseDoconut() はミドルウェアを接続します。リソース呼び出しは最初に行う必要があります。UseDoconut() は到達したすべてのリクエストに応答するので、app.Map を使用して独自のブランチにマウントしてください。セッション呼び出しも必要です — Doconut のデフォルトドキュメントセキュリティは、すべてのページリクエストを ASP.NET セッション状態と照合して検証します。セッション状態にはキャッシュが必要です:AddDistributedMemoryCache() が提供します。MVC または Razor Pages アプリはすでに登録していますが、最小 API アプリは登録しておらず、Unable to resolve service for type 'IDistributedCache' が原因で起動時に停止します。すでに インストール 中に Doconut を登録しましたか?次のセクションへ進んでください。

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // セッション状態にはキャッシュが必要です(MVC/Razor Pages はすでに追加されています)
builder.Services.AddSession(); // Doconut のドキュメントセキュリティは ASP.NET のセッション状態に依存しています

app.UseSession();          // UseDoconut() の前に UseSession() を呼び出してください
app.UseDoconutResources(); // UseDoconut() の前に登録する必要があります
app.Map("/doconut", branch => branch.UseDoconut());

この設定は、歴史的な DocImage.axd リクエスト形状を保持し、 一致するブランチにドキュメントミドルウェアをマウントします。これは、既存の .NET Standard アプリケーションを引き継ぐ際にコピーすべき構成です、なぜならクライアントが常に同じ URL を呼び出し続けるからです:

csharp
builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // Doconut のセッションチェックを有効にしたままにしてください
    options.ShowDoconutInfo = false;
});
builder.Services.AddDistributedMemoryCache(); // セッション状態にはキャッシュが必要です(MVC/Razor Pages はすでに追加されています)
builder.Services.AddSession(options =>
{
    options.IdleTimeout        = TimeSpan.FromSeconds(3600);
    options.Cookie.HttpOnly    = true;
    options.Cookie.IsEssential = true;
});

// 一部のドキュメント形式でのマルチバイトエンコーディングに必要です。
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

app.UseStaticFiles();
app.UseRouting();
app.UseSession();
app.UseDoconutResources();   // ドキュメントブランチの前に
app.MapWhen(
    context => context.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

UseDoconut() はこのリリースでオプションを受け取りません — すべては AddDoconut() に移動しました。 MiddlewarePath は調整値です;それは ASP.NET Core のブランチをマッピングしません、それ自体。上記の DocImage.axd ブランチでは、クライアントは BasePath: '/' を使用します;と app.Map("/doconut", ...) は最小設定から、BasePath: 'doconut' を使用します。 ResourcesPath は埋め込みバンドルを /doconut-res で提供し、ウィジェットの画像リソースパスはそれゆえ ResPath: 'doconut-res/images' です。

ページに Viewer を追加

Viewer はページに必須のコアです。そのレンダリングサーフェスは 2 つの入れ子になった div を使用します:

html
<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

ツールバー、モジュールマウント、そして Viewer サーフェスを 1 つのページ構成として扱います。検索と
Annotation は埋め込みリボンをオプションのマウントに注入しますが、これらのモジュールは決して
単独ではありません:常に同じページ上の Viewer にアタッチされます。

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- ビューアのナビゲーション、ズーム、検索、アノテーションボタン -->
</nav>

<div id="searchBarMount"></div>
<div id="annBarMount"></div>

<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

ビューア資産の参照

Razorビューでは、注入された Viewer サービスがビューアの <link> と <script> タグを依存順に出力します — ウィジェットはjQueryプラグインなので、jQueryはビューアスクリプトより先に読み込む必要があります。

html
@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
@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 インスタンスなしで、SearchまたはAnnotation Ribbonの例を公開しないでください。ReferenceCss と ReferenceScripts は、現在のライセンスがその機能を許可していない場合にオプションモジュールのリソースを省略します;コアViewerは依然として起動します。

これらの呼び出しは手作業でコピーしたスクリプトファイルに取って代わります。アプリケーションがまだ独自の docViewer.js、documentLinks.js、または docViewer.UI.js をロードしている場合、ページが出力されたリソースから正しく動作するようになったらそれらのタグを削除してください — 詳細は移行ガイドをご覧ください。

ビューアの初期化

クライアント側ウィジェットはjQueryプラグインです。これは実際の初期化オプションの最小セットです(疑似コードではありません)。

javascript
let searchBar = null;
let annBar = null;

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/',                   // DocImage.axd ブランチ; 'doconut' を app.Map("/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);
    }
});

このページが機能するかどうかは、4つの詳細に左右されます:

  • コールバックはオプションです。 onViewerReady、onViewerBusy、onCopy、および onAutoLoadStatus はオプションオブジェクトに渡されます。以前のビューアはコンテナIDからグローバル関数名を導出し呼び出していましたが、こちらはそうではありません。グローバル関数としてのみ宣言されたハンドラは実行されず、何も報告されません。
  • ResPath はリソースプレフィックスを指します、アプリケーションのルートではありません。デフォルトの ResourcesPath を使用すると、その値は doconut-res/images です。ResourcesPath を変更した場合は、代わりに独自のプレフィックスを使用してください。アイコンはリソースルートの1つ下のフォルダにあります:'doconut-res' を使用すると、すべてのアイコンが404を返しますが、ドキュメント自体はまだ表示されます。
  • BasePath は先頭スラッシュがありません(サイトルート値 '/' 以外)。'doconut' は /doconut/DocImage.axd をリクエストし、'/doconut' は //doconut/DocImage.axd を生成します。これはブラウザが別のホストへのリクエストと解釈します。
  • ビューアを保持し、View を別途呼び出してください。 docViewer(...) は Zoom、Next、FitType を含むオブジェクトを返します;View(...) は別のものを返します。var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) はドキュメントをレンダリングし、最初のツールバーボタンをクリックした際に objViewer.Zoom is not a function で失敗します。

これらはすべて黙って失敗します — トラブルシューティング と 移行ガイド を参照してください。

オプションのケースは実際に混在しています — showThumbs、autoLoad、pageZoom はcamelCaseですが、FitType、BasePath、ResPath はPascalCaseです。一貫したルールはなく、ケースを間違えるとオプションは黙って無視されます(ウィジェットは例外を投げる代わりにデフォルトにフォールバックします)。

完全な Viewer パッケージを組み立てる

完全なビューアページは、以下の部品を一緒にインストールします。

パッケージの部品要件接続方法
Viewer リソース、マウント、および objViewer必須コア文書レンダラー
Viewer ツールバー完全なページに必須ホストマークアップ;ボタンは同じ objViewer を呼び出す
検索リボンオプション、ライセンスモジュールdoconutSearchBar(...).attach(objViewer)
注釈リボンオプション、ライセンスモジュールdoconutAnnotationBar(...).attach(objViewer)

メインの Viewer ツールバーはホストマークアップですが、Viewer と共にインストールされ、単独のコントロールとして文書化してはなりません。これにより、レイアウト、ラベル、アイコン、認可ルールがアプリケーション側で管理でき、すべてのボタンが同じ Viewer インスタンスを操作します。

html
<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>

この初期化順序を守ってください:

  1. Viewer とライセンスモジュール用の CSS を出力します。
  2. Viewer ツールバー、検索/注釈のマウント、および Viewer のマウントを一緒にレンダリングします。
  3. Viewer とライセンスモジュール用のスクリプトを出力します。
  4. ホストアプリケーションの独自ツールバーヘルパースクリプトを読み込みます。
  5. docViewer を初期化し、結果として得られる objViewer を保持します。
  6. 各ライセンス済みの検索または注釈リボンを初期化します。
  7. すべてのリボンで attach(objViewer) を呼び出します。
  8. 文書を開き、Viewer とモジュールのリクエスト用にそのトークンを保持します。

サーバー側のガードは重要です。オプション機能が利用できない場合、そのスクリプトは出力されず、jQuery プラグイン関数も存在しません。

html
<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 を生成します。検索リボンには「検索」「オプション」「結果」グループが含まれ、注釈リボンには作成ツール、スタイルコントロール、保存アクション、オプションのエクスポート/画像アクションが含まれます。これらのバーは open()、close()、reset()、isOpen() を公開し、作成後は必ず一度だけ attach(objViewer) を呼び出してください。

上記の例では、起動を最小限に抑えるためにオプションのホストコールバックや注釈のエクスポート/画像エンドポイントを省略しています。完全な機能別設定については 検索 と 注釈 を参照するか、ホスト所有の Viewer ツールバーをスタイル変更または置き換える場合は カスタムテーマ をご覧ください。

ドキュメントを開く

サーバー側は単一のエンドポイントで、注入された Viewer サービスがドキュメントを開き、セッショントークンを返します。このリリースではオープンは非同期です。

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    // トークンは不透明です — widgetに渡し、決してログに記録したり永続化したりしないでください。
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

クライアントはそのトークンを取得し、objViewer.View(token) を使用してウィジェットに渡します:

javascript
fetch('/api/open', { method: 'POST' })
    .then(resp => resp.json())
    .then(data => {
        token = data.token;
        objViewer.View(token);
    });

最初のオープンの前にウォームアップする必要はありません。アプリケーションを引き継ぐ場合は、InitCache() の呼び出しとそれをガードするフラグを削除してください — そのメソッドはもはや存在しません。

ドキュメントを閉じる

ユーザーがビューアを離れるか代替ドキュメントを開くときは objViewer.Close(true) を呼び出します:ウィジェットをクリアし、サーバーにクローズリクエストを送信します。引数なしの objViewer.Close() はウィジェットのみをクリアします。サーバー駆動のワークフローでは、viewer.CloseDocument(token) がキャッシュされたセッションを即座に削除し、レンダリングエンジンを破棄し、セキュリティマーカーを削除し、トークンを無効化します。スライディング有効期限も最終的に同様のクリーンアップを行いますが、大きなドキュメントの場合は明示的なクローズが推奨されます。

完了したリクエストフローは次のとおりです:

text
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 がライセンスを取得する方法と取得後の変更点については、ライセンス設定 を参照してください。

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