クイックスタート

MVC 5 または Web Forms で最初のドキュメントをレンダリングする

このウォークスルーは、.NET Framework 4.7.2 上の ASP.NET アプリケーションを、インストール済みパッケージからブラウザでレンダリングされたドキュメントへと導きます:Global.asax、オープンエンドポイント、ビューアのアセット、ウィジェット、そしてそれらを接続するトークンです。Web.config の登録が インストール に従って行われていることを前提としています — DocImage.axd ハンドラとリソースモジュールがなければ、以下のいずれもサーバーに到達できません。

Global.asax で Doconut を構成する

MVC 5 アプリケーション用の完全な Application_Start:

csharp
// Global.asax.cs - ワーカープロセスごとに一度だけ構成し、シャットダウン時に解放します。
protected void Application_Start()
{
    Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
        options.UnsafeMode  = false; // ページは、ドキュメントを開いたセッションにのみ提供されます。
    });

    // MVC のみ: 2 つの Doconut エンドポイントをルーティングから除外してください。
    RouteTable.Routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
    RouteTable.Routes.IgnoreRoute("doconut-res/{*pathInfo}");
}

protected void Application_End()
{
    Doconut.DoconutHost.Shutdown();
}
  • Encoding.RegisterProvider は、一部のドキュメント形式が使用するレガシーコードページをプロセスで利用可能にします。最初のドキュメントを開く前に一度だけ呼び出してください。
  • UnsafeMode = false はデフォルトで、誤って変更されないよう明示的に記述されています:DocImage.axd は、ドキュメントを開いた ASP.NET セッションのみにページを提供します。
  • IgnoreRoute の2つの呼び出し は、ハンドラとモジュールが提供する DocImage.axd と /doconut-res/* から MVC ルーティングを遠ざけます。Web Forms アプリケーションには MVC ルートがなく、この行は不要です。
  • DoconutHost.Shutdown は、アプリケーションプールがリサイクルされる際に Doconut のバックグラウンド作業を停止し、サービスを解放します。Initialize が実行されていなくても安全に呼び出すことができます。

ドキュメントを開く

ドキュメントを開くと不透明なトークンが返されます。ウィジェットは各ページリクエストにそのトークンを送ります。

MVC 5 では、コントローラアクションが Viewer サービスを DoconutHost.Services から解決します — MVC 5 にはコンストラクタインジェクションがありません:

csharp
// POST /Document/Open
[HttpPost]
public async Task<ActionResult> Open()
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

    // トークンは不透明です - ビューアに渡し、決してログに記録したり永続化したりしないでください。
    string token = await viewer.OpenDocumentAsync(Server.MapPath("~/files/Sample.pdf"));
    return Json(new { token });
}

ドキュメントは セッション状態を持つリクエスト内で 開く必要があります。なぜなら、開くことが現在の ASP.NET セッションにページへのアクセス権を付与するからです。MVC コントローラと Web Forms ページはデフォルトでセッション状態を持ちます。カスタム IHttpHandler は、System.Web.SessionState.IRequiresSessionState を実装しない限りセッション状態を持ちません。ハンドラからそれなしでドキュメントを開くと、ビューアはすべてのページで「You Are Not Authorized To View This Page.」と表示します。

Web Forms では、ページ自体がコードビハインドでドキュメントを開くことができます。OpenDocument は OpenDocumentAsync の同期版で、非同期ページを使用しないコードビハインド向けです:

csharp
// Default.aspx.cs
protected string Token;

protected void Page_Load(object sender, EventArgs e)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    Token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
}

トークンはベアラークレデンシャルのように扱ってください:決してログに記録したり永続化したりせず、ウィジェットにのみ渡します。ドキュメントセッションが期限切れになると機能しなくなるので、再度ドキュメントを開いて新しいトークンを取得してください。

ビューア資産の参照

Viewer.ReferenceCss と Viewer.ReferenceScripts は埋め込み資産用の <link> と <script> タグを依存順に出力し、/doconut-res/ を指します。ウィジェットは jQuery プラグインなので、jQuery が最初に来ます。

MVC 5. ビューには @inject がないため、コントローラでタグを生成し、ViewBag に渡します:

csharp
public ActionResult Index()
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
    {
        IncludeBootstrapCss = true,
        IncludeViewerCss    = true
    });
    ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
    {
        IncludeJQuery        = true,
        IncludeBootstrap     = true,
        IncludeViewerScripts = true
    });
    return View();
}
html
@Html.Raw(ViewBag.ViewerCss)
...
@Html.Raw(ViewBag.ViewerScripts)

その処理はコントローラに残してください。MVC 5 はビューを最初に提供する際にコンパイルし、追加のコンパイラパッケージがなければそのコンパイラは C# 5 しか理解できません — ?. もなく、$"..." もなく、nameof もありません。これらを使用するビューは Visual Studio で正常にコンパイルされ、ブラウザでは空の 500 が返されます。

Web Forms. 同じ文字列をコードビハインドから公開し、<%= %> で書き出します:

html
<head>
    <%= ViewerCss %>
</head>
<body>
    ...
    <%= ViewerScripts %>
</body>

IncludeViewerCss と IncludeViewerScripts は必須のコアです。Search と Annotation のリボンを追加するには、IncludeSearchCss、IncludeAnnotationCss、IncludeSearchScripts、IncludeSearchBar、IncludeAnnotationScripts、IncludeAnnotationBar も設定します。ライセンスでその機能が許可されていない場合、両方の方法ともリボンのファイルを省略しますが、ビューア自体は起動します。

ページへのビューア追加

レンダリング領域は二重に入れ子になった div です:

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

外側の div に実際の高さを設定してください — ビューアはコンテナを埋め、開始時にそのサイズを測定します。ビューアは独自のツールバーを描画しません:GotoPage、Next、Zoom、FitType などは、ページが自分のボタンに接続するメソッドで、ビューアの横に配置されます:

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.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>
</nav>

ビューアの初期化とドキュメント表示

ビューアのスクリプトを読み込んだ後、ウィジェットを作成し、トークンを渡します:

javascript
var objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/',                   // '/' はサイトルートの DocImage.axd を意味します
    ResPath:    'doconut-res/images',  // 先頭に '/' がありません
    onViewerReady: function () {
        // ページが表示されています; ここでロードインジケーターを非表示にします
    },
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

fetch('/Document/Open', { method: 'POST' })
    .then(function (resp) { return resp.json(); })
    .then(function (data) { objViewer.View(data.token); });

Web Forms では、ページが自らドキュメントを開く場合、最後の3行は objViewer.View('<%= Token %>'); に置き換わります。

ここでの4つの詳細はエラーメッセージなしで失敗します:

  • BasePath: '/' はサイトルートの DocImage.axd を指します。仮想ディレクトリ内のアプリケーションの場合、スラッシュなしで名前を使用します('myapp' は /myapp/DocImage.axd を要求)。先頭のスラッシュ('/myapp')は //myapp/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 が発生して失敗します。

オプション名は camelCase(showThumbs、autoLoad、pageZoom)と PascalCase(FitType、BasePath、ResPath)が混在しています。スペルミスしたオプションは無視され、ウィジェットはデフォルトを使用します。

ワンライン代替

自分のツールバーを持たず、ドキュメントを表示するだけのページの場合、Viewer.RenderViewer は初期化スクリプト全体を書き込みます — docViewer(...) は BasePath: '/' と ResPath: 'doconut-res/images' を使用し、次に .View(token) を行います。このパッケージにのみ存在します:

csharp
// Default.aspx.cs
protected string ViewerInit;

protected void Page_Load(object sender, EventArgs e)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    string token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
    ViewerInit = viewer.RenderViewer("div_ctlDoc", token);
}
html
<div id="div_ctlDoc" style="height: 100vh"></div>
<%= ViewerScripts %>
<%= ViewerInit %>

ズーム、フィット、サムネイルパネルを変更するには、ViewerConfig を3番目の引数として渡します。生成されたスクリプトはビューアへの参照を保持しないため、ページが独自のツールバーを必要とする場合は、上記の手書き初期化を使用してください。

ドキュメントを閉じる

ユーザーがビューアを離れるか代替を開くときは objViewer.Close(true) を呼び出します:ウィジェットをクリアし、DocImage.axd にクローズリクエストを送信します。引数なしで objViewer.Close() を呼び出すとウィジェットだけがクリアされます。サーバー側では viewer.CloseDocument(token) がドキュメントセッションを即座に削除し、レンダリングリソースを解放し、セッションのページへのアクセス権を取り消します。スライディング有効期限も最終的に同様の処理を行いますが、大きなドキュメントを明示的に閉じることでメモリが早く解放されます。

実行方法

~/files/Sample.pdf に PDF を配置し、IIS Express でサイトを起動します(Visual Studio の F5)。ウィジェットをホストするページを開きます。最初のページが左側にサムネイル付きで表示されます。表示されない場合は、トラブルシューティング を参照してください。

ライセンスなしで得られるもの

ライセンスがなくてもエラーは発生しません。ビューアは通常通りレンダリングしますが、すべてのページに評価用の透かしが付加されます。Doconut がライセンスを探す場所については、ライセンス設定 を参照してください。

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