ビューア

メインのドキュメントビューアクラス

Viewer (namespace Doconut) は、Razor ページ、MVC コントローラー、Blazor コンポーネント、または最小限の API からドキュメントを開くための公開エントリーポイントです。sealed であり、AddDoconut() によって transient サービスとして登録され、コンストラクタインジェクションで解決されます — 直接インスタンス化しないでください。

以前の .NET Standard ライブラリは、メモリキャッシュ、HTTP コンテキストアクセッサ、および 1 つ以上のライセンスパスを受け取る公開コンストラクタを提供していました。そのコンストラクタは廃止され、サービスグラフがこれらの依存関係を供給します。

Viewer はリクエストごとの状態を保持せず、意図的に IDisposable を実装 しません。ドキュメントセッションはセッションキャッシュ内で独立して存在するため、サービスを破棄しても開かれたドキュメントが削除されることはありません(Core Concepts → How the Viewer Works を参照)。

OpenDocumentAsync

ドキュメントを開き、クライアントウィジェットが以降のすべてのリクエストで使用するセッショントークンを返します。すべてのオープンは非同期で行われ、同期的な OpenDocument は存在しません。

OverloadUse when
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)自動フォーマット検出とフォーマットのデフォルト設定でディスクから開く
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default)フォーマットごとのレンダリングオプションが必要な場合(PdfConfig、WordConfig、…)
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default)ドキュメントがディスク上のファイルではありません(アップロード、データベース、ブロブ)。fileInfo は正しい拡張子を持たなければならず、フォーマット検出の基準となります。
csharp
// シンプルなオープン
string token = await viewer.OpenDocumentAsync(path);

// フォーマットごとの設定とオプション付き
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// アップロードから
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

対処すべき例外:

  • LicenseException — 見つかったライセンスが拒否された場合(メッセージに拒否理由が含まれます)、またはフォーマットがもはや付与されていないプラグイン機能を必要とする場合。拒否メッセージなしのカレンダー期限切れは、例外をスローする代わりに透かし付きレンダリングにフォールバックします。
  • FormatNotSupportedException — Document format '<extension>' is not supported.
  • InvalidDataException — ファイル内容が破損しているか、拡張子と一致しません。

CloseDocument

text
void CloseDocument(string token)

キャッシュからセッションを削除し(ドキュメントエンジンを即座に破棄)、セキュリティマーカーを削除し、アクセス権を取り消します。オプションですが、スライディング有効期限も同様のクリーンアップを行います — ただし大きなドキュメントには推奨されます。

GetPageCount

text
int GetPageCount(string token)

開かれたセッションの総ページ数です。トークンが不明または期限切れの場合は InvalidOperationException(Document session not found. Please re-open document.)がスローされ、空のトークンの場合は ArgumentException がスローされます。

GetPageDimensions

text
(int Width, int Height) GetPageDimensions(string token, int page = 1)

ドキュメントのデフォルトのレンダリングページサイズ(100% ズーム)で、コード内で構築されたアノテーションの座標空間です。互換性のために page が受け入れられますが、結果はドキュメントのデフォルトになります。トークンが不明または期限切れの場合は InvalidOperationException(Document session not found. Please re-open document.)がスローされ、空のトークンの場合は ArgumentException がスローされます。

ワークシート名取得

text
IReadOnlyList<string> GetWorksheetNames(string token)

開いているスプレッドシートのワークシート名を、ブックの順序で返します。開いているドキュメントがスプレッドシートでない場合は空のリストが返されます。

表示されているワークシートのみが一覧に含まれます。非表示や空のワークシートは除外され、ExcelConfig.SheetNames がレンダリングを制限している場合は、そのワークシートだけが表示されます。ワークシートは必ずしも1ページとは限らず、非常に大きい場合は複数ページに跨ってレンダリングされます。トークンが不明または期限切れの場合は InvalidOperationException (Document session not found. Please re-open document.) がスローされ、空のトークンの場合は ArgumentException がスローされます。

26.9.0で追加。

機能フラグ

メンバー意味
bool IsSearchEnabled現在のライセンスは Search を付与します
bool IsAnnotationEnabled現在のライセンスは Annotation を付与します

これらは Razor ビューで使用し、サーバーが実際に提供できる場合にのみライセンスされたリボンをレンダリングします — 詳細はクイックスタートをご覧ください。

DocOptions(ドキュメントオプション)

オープンごとに設定できる、フォーマットに依存しないオプションです(名前空間 Doconut):

型プロパティデフォルト説明
stringPassword""保護されたドキュメントのパスワード(フォーマット設定に自動的にコピーされます)。
intImageResolution0廃止予定。 互換性のためだけに保持されます — 代わりにフォーマット設定で ImageResolution を設定してください。
stringWatermark""レンダリングされたページに描画されるカスタム透かしテキスト。書式文字列: "^Text~Color~FontSize~FontName~Opacity~Angle"、例: "^Sample Copy~Red~24~Verdana~80~-45"。
intTimeOut60セッションのスライディング有効期限(分)。
boolIsSecuredtrue現在は適用されていません — 予約項目です。トークンバインディングは全体で DoconutOptions.UnsafeMode により制御されます(Core Concepts → Sessions & Security を参照)。

このクラスは、通常の単一ホスト閲覧フローの外側に意図的に配置された、特化したプロパティも公開しています:

型プロパティデフォルト説明
boolIsWebFarmfalse廃止予定 — 効果なし。 ドキュメントを DistributedDocumentPublisher.PublishAsync(または IDistributedPublishQueue.EnqueueAsync)で公開し、代わりに FileShareConfig.RootPath を設定してください。大文字小文字に注意してください — 以前のライブラリではこれを IsWebfarm と綴っていました。
stringWebFarmPath""廃止予定 — 効果なし。 Distributed Deployments で説明されているように FileShareConfig.RootPath を使用してください。以前は WebfarmPath と綴っていました。
boolEditModefalse別途配布される編集ワークフロー用に予約されています。標準ビューアーには false を残してください。

カスタム透かし

DocOptions.Watermark は6つのチルダ区切りフィールドを使用します。オプションの先頭 ^ は全角レイアウトを要求します:

text
^Text~Color~FontSize~FontName~Opacity~Angle
csharp
string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });
フィールド例意味
先頭 ^^オプションの全角レイアウト。これがない場合は通常の透かし配置が使用されます。
テキストConfidential各ページに描画されるテキスト。空であってはなりません。
色Red描画レイヤーが理解できる名前付きカラー。
フォントサイズ24フォントサイズ。数値が無効な場合はレンダラのデフォルトにフォールバックします。
フォント名Verdana要求されたフォントファミリ。デプロイ環境にインストールされていることを確認してください。
不透明度800から255のバイト値。正しく解析できる必要があります。
角度-45度単位の回転角度。数値が無効な場合はデフォルトにフォールバックします。

パーサーはオプションの ^ の後に正確に6つのフィールドがあることを期待します。無効な定義は、サイレントに消える代わりに SDK の可視 Invalid Watermark フォールバックに置き換えられます。

ライセンスの決定

ライセンス状態カスタム値が提供されたかレンダリング結果
有効な有料ビューアライセンスいいえクリーンページ
有効な有料ビューアライセンスはいカスタム透かし
アクティブな一時/デモベースビューアいいえクリーンベースビューアページ
アクティブな一時/デモベースビューアはいクリーンベースビューアパスが適用されるときのカスタム透かし
欠損、拒否、期限切れ、バージョン不一致、または無効ドメインのライセンスいずれか強制/評価透かし; カスタム値はそれを上書きできません
評価ルール下のプラグインレンダリングいずれか評価透かし

同じ判断は提供されるページ画像およびアノテーションのエクスポートにも適用されます。アニメーションGIFの出力はフレームごとに透かしが付与されます。したがって、カスタム透かしは評価透かしを置き換えたり抑制したりする手段ではなく、ライセンスされたアプリケーション機能です。

アノテーション API

サーバー側のアノテーションのロードとエクスポートです。完全な手順はガイド → アノテーションにあります; 概要は以下の通りです:

メンバー目的
AnnotationManager GetAnnotationManager(string token)オープンセッションのページ寸法にバインドされたマネージャー
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)明示的なページ寸法を持つマネージャー
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)セッションに依存しないマネージャー
void LoadAnnotationData(string token, AnnotationManager manager)C#で作成されたアノテーションをセッションにロードする
void LoadAnnotationData(string token, string annotationData)AnnotationManager.GetAnnotationData() が返すエンコードされたページ/Base64エンベロープからアノテーションをロードする
void LoadAnnotationXML(string token, XmlDocument annotationXml)XMLからアノテーションをロードする
XmlDocument GetAnnotationXML(string token)セッションのアノテーションをXMLとしてエクスポートする
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)アノテーションが焼き込まれたPDF
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default)ページごとに1つのPNG、アノテーションが焼き込まれ、directoryPath に書き込む(存在しない場合は作成); 書き込まれた画像数を返す
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)アノテーションが焼き込まれたページ別PNGのZIP

これらはすべてセッショントークンを受け取ります。以前のライブラリのセッションフリーな GetAnnotationManager(pageWidth, pageHeight) 形状はセッション外でアノテーションを構築するために残っていますが、ロードするには依然としてトークンが必要です。

DICOM メタデータ

text
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

このメソッドは API の整合性のために存在しますが、このパッケージは技術的な DICOM タグを提供できません。メタデータリーダーは .NET 8 ビルドのみが同梱されています。DICOM セッションおよび非 DICOM セッションの両方で null を返します;DICOM セッションの場合、プラットフォームの制限を説明する一度だけの警告も出力します。ページ、フレーム、アニメーションのレンダリングは引き続きサポートされています。

リソースヘルパー — ReferenceCss / ReferenceScripts

UseDoconutResources() が提供する埋め込みリソースの <link>/<script> タグを正しい依存順序で出力します。検索やアノテーションなどライセンスで制御される機能のバンドルは、ライセンスが有効な場合にのみ 出力され、クライアント UI をサーバーの動作と一致させます。

text
string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

CssConfig フラグ: IncludeBootstrapCss、IncludeViewerCss、IncludeSearchCss(検索制御)、IncludeAnnotationCss(アノテーション制御)。

ScriptConfig フラグ: IncludeJQuery(他すべてが必要とする)、IncludeBootstrap、IncludeViewerScripts(コア: docViewer.js + スプリッタ + リンク)、IncludeSearchScripts と IncludeSearchBar(検索制御)、IncludeAnnotationScripts と IncludeAnnotationBar(アノテーション制御)、EmitFeatureFlags(デフォルト true: インライン window.Doconut.features = { search, annotation, editor } スクリプトも書き込む; インラインスクリプトをブロックする Content-Security-Policy の下では false に設定)。

html
@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))

これらのヘルパーはブラウザリソースを配信するサポートされた方法です。docViewer.js、documentLinks.js、docViewer.UI.js を wwwroot にコピーしたアプリケーションは、タグからページがレンダリングされたらそれらのコピーを削除すべきです。

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