インストール

Doconut を .NET Framework 4.7.2 の Web アプリケーションに追加する

Doconut.NETFramework は .NET Framework 4.7.2 上のクラシック ASP.NET アプリケーションで Doconut ビューアをホストします — IIS または IIS Express、MVC 5 または Web Forms が対象です。セットアップは 3 つの部分からなります: NuGet パッケージ、Web.config の 2 つの登録、そして Global.asax の 1 回の呼び出しです。このページはそれらすべてをカバーします; クイックスタート でページにドキュメントを配置します。

必要条件

  • Web プロジェクトは .NET Framework 4.7.2 以上を対象とします。4.7 プロジェクトはこのパッケージを使用できないため、まずターゲットを変更してください。
  • サイトは integrated pipeline で実行されます(IIS および IIS Express のアプリケーションプールのデフォルトです)。
  • サーバーは Windows 上で動作します。このパッケージは Windows のみ対応です。

このページは Doconut.NETFramework 26.9.0 以降 を対象としています。バージョン 26.8.0 およびそれ以前は .NET Framework 4.7 を対象とし、異なる API を使用していました。そのラインは廃止されています。その境界を越えて既存アプリケーションを更新する方法は 移行 に記載されています。

パッケージのインストール

Package Manager Console から:

powershell
Install-Package Doconut.NETFramework

または、SDK スタイルのプロジェクトでは:

bash
dotnet add package Doconut.NETFramework

バージョン指定なしのコマンドは最新の安定版をインストールします。このドキュメントで説明しているリリースを固定したい場合は、バージョンを指定してください:

powershell
Install-Package Doconut.NETFramework -Version 26.10.0
bash
dotnet add package Doconut.NETFramework --version 26.10.0

レンダリングエンジンはパッケージに組み込まれており、参照・コピー・デプロイ用の別個のエンジン アセンブリは存在しません。オプション機能はそれぞれ別パッケージとして提供されます — 例として Doconut.NETFramework.Converter と Doconut.NETFramework.Dicom — それぞれにライセンスが必要です(プラグインシステム を参照)。

Web.config の設定

Doconut は 2 種類のリクエストを提供し、IIS は両方を Web.config を介してルーティングします:

  • DocImage.axd — ビューアのページ、サムネイル、検索、アノテーション エンドポイントで、Doconut.DocImageHandler が提供します。
  • /doconut-res/* — ビューア自身のスクリプト、スタイルシート、アイコンで、アセンブリに埋め込まれ、Doconut.DoconutResourceModule が提供します。

両方を追加し、依存する設定も加えます:

xml
<configuration>
  <system.web>
    <!-- MVC 5 のみ: Razor は実行時にビューをコンパイルし、netstandard ファサードが必要です。 -->
    <compilation targetFramework="4.7.2">
      <assemblies>
        <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
      </assemblies>
    </compilation>
    <!-- maxRequestLength は KILOBYTES 単位です: 200 MB。 -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- .cshtml と .aspx ファイルは UTF-8 で読み取り、サーバーの ANSI コードページではありません。 -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength は BYTES 単位です: 同じく 200 MB。 -->
        <requestLimits maxAllowedContentLength="209715200" />
      </requestFiltering>
    </security>
    <modules runAllManagedModulesForAllRequests="true">
      <add name="DoconutResourceModule" type="Doconut.DoconutResourceModule, Doconut" />
    </modules>
    <handlers>
      <add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd"
           type="Doconut.DocImageHandler, Doconut" />
    </handlers>
  </system.webServer>
</configuration>

各行は例外を発生させない失敗を防ぎます:

  • verb="GET,HEAD,POST" — HEAD を保持します。ビューアはアニメーション画像を検出するためにページ 1 に対して HEAD リクエストを送ります。動詞が無いと、ハンドラが実行される前に IIS が 404 で応答し、ドキュメントは表示されますがアニメーション検出は機能せず、ブラウザコンソールに 404 が大量に出ます。
  • runAllManagedModulesForAllRequests="true" — /doconut-res/*.js、.css、.png は静的ファイルのように見えるため、リソースモジュールが処理する前に IIS が静的ファイルハンドラに渡してしまいます。その結果、スクリプトやアイコンのないビューアになります。
  • <globalization fileEncoding="utf-8"> — バイトオーダーマークなしで UTF-8 として保存されたページ ファイルは、サーバーの ANSI コードページで読み取られるため、非 ASCII 文字は二重エンコードされてブラウザに届きます(エムダッシュは — と表示されます)。ファイル自体はディスク上で正しく、ページは依然として <meta charset="utf-8"> を宣言しています。
  • netstandard アセンブリ (MVC 5) — Razor はビューが最初に要求されたときにコンパイルし、独自の参照リストにこのファサードが含まれません。単純なメンバーアクセス以外の動的処理を行うビューは CS0012 で失敗し、空の 500 を返します。このエラーは Windows のイベントログ(ソース: ASP.NET)にのみ表示され、Web Forms アプリケーションではこの行は不要です。
  • アップロード制限 — ASP.NET はハンドラが実行される前にリクエスト本体全体を読み取るため、これらの上限を超えるアップロードは IIS によって独自のエラーページで拒否されます。maxRequestLength(キロバイト)と maxAllowedContentLength(バイト)を揃えて設定し、ユーザーが開くまたはアップロードする最大ファイルサイズを上回らないようにしてください。

さらに 2 つの設定が重要で、通常はすでに正しく設定されています:

  • セッション状態は有効のままです。 デフォルトでは、ページはドキュメントを開いた ASP.NET セッションのみに提供されるため、サイトは <sessionState mode="Off" /> を設定してはいけません。セッションとセキュリティ を参照してください。
  • バインディング リダイレクト。 NuGet が Web.config に書き込む <runtime> バインディングリダイレクトを保持してください。SDK スタイルのプロジェクトでは、生成された bin\<YourApp>.dll.config からコピーします。クラシック ASP.NET は Web.config からのみリダイレクトを読み取るためです。bin\ に存在しないバージョンを指すリダイレクトは、起動時に空の 500 でアプリケーション全体を停止させます。

Global.asax で Doconut を登録する

System.Web にはビルダーもミドルウェア パイプラインもありません。Doconut は DoconutHost.Initialize によって Application_Start でワーカープロセスごとに 1 回構成され、DoconutHost.Shutdown によって Application_End で解放されます:

csharp
// Global.asax.cs
protected void Application_Start()
{
    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    });
}

protected void Application_End()
{
    Doconut.DoconutHost.Shutdown();
}

DoconutHost.Initialize はハンドラ、リソースモジュール、および独自コードが使用するサービスを構築します。コードは DoconutHost.Services を通じてそれらにアクセスします(DoconutHost を参照)。最初の呼び出しだけが設定を行い、2 回目以降は無視されます。MVC アプリケーションでは、2 つの Doconut パスをルーティングから除外してください — クイックスタート では完全な Application_Start が示されています。

すべてのオプション

DoconutOptions は以下の設定可能なプロパティを受け入れます。すべて任意です。

PropertyDefaultDescription
UnsafeModefalsefalse の場合、DocImage.axd はドキュメントを開いた ASP.NET セッションのみにページを提供します。true の場合、トークンを含むすべてのリクエストが提供されます。false のままにしてください。
ShowDoconutInfofalsetrue の場合、token がない DocImage.axd リクエストは 404 の代わりにバージョンバナーで応答します。スモークチェックとして有用です;本番環境ではオフにしてください。
ResourcesPath"/doconut-res"リソースモジュールが埋め込みスクリプト、スタイル、アイコンを提供する場所です。ビューアの ResPath と任意の MVC IgnoreRoute と一緒に変更してください。
LicensePath""ライセンスファイルへのフルパスです。空の場合は次のソースへフォールスルーし、次に自動検出へ移ります。
LicenseContent""生のライセンス内容です — 環境変数、シークレットストア、またはデータベースから取得します。
LicenseStreamnullストリームとしてのライセンスで、起動時に一度だけ読み取られます。
MiddlewarePath"/doconut"このパッケージでは使用されません。ページエンドポイントは Web.config で宣言された DocImage.axd ハンドラで、設定が何であれ使用されます。依然として検証されます:/ で始まり、ResourcesPath と異なる必要があります。
ResetLicensefalseこのパッケージでは使用されません。ライセンスは DoconutHost.Initialize で一度だけ読み取られます;ライセンスファイルを置き換えた後はアプリケーションプールをリサイクルしてください。
MaxConcurrentEditorSessions200ライブエディタセッション(DocOptions.EditMode で開かれたドキュメント)の最大数です。これを超えると、最も使用されていないアイドルエディタセッションが閉じられます。通常のビューアセッションはカウントされません。0 または負の値は上限なしを意味します。
EditorSnapshotEveryOps50エディタ永続性が有効(AddDoconutEditorPersistence)な場合、N 回の変更ごとにライブドキュメントのスナップショットを取ります。0 または負の値はセッション中にスナップショットを取らないことを意味します。永続性が無効な場合は効果がありません。

複数のライセンスソースが設定されている場合、優先順位は LicenseStream > LicenseContent > LicensePath > 自動検出です — License Setup を参照してください。

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.ResourcesPath   = "/doconut-res"; // viewer’s JS/CSS/images が提供される場所
    options.UnsafeMode      = false;          // session セキュリティ をオンのままに保つ
    options.ShowDoconutInfo = false;
});
// このページエンドポイントはオプションではありません: それは Web.config に宣言された DocImage.axd ハンドラです。

次のステップ

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