GroupDocs.Annotation を使用した .NET でのプレビュー作成方法

プレビュー作成 体験を提供することは、現代のドキュメント中心アプリケーションの基盤です。GroupDocs.Annotation for .NET を使用すると、PDF のサムネイル画像をレンダリングし、セキュアなドキュメントプレビュー ストリームを生成し、モバイルデバイスでもユーザーインターフェイスを快適に保つことができます。このガイドでは、プレビュー生成が重要な理由を明らかにし、一般的な実装シナリオを検討し、独自のソリューションに高品質なプレビューを追加するためのロードマップを提供します。

クイック回答

AnnotationApi クラスは、ドキュメントをロードしプレビュー画像を作成する GroupDocs.Annotation のコアコンポーネントです。GetPages メソッドは、レンダリングされたページ画像をバイト配列として返します。HideAnnotations フラグは、レンダリング画像からすべてのアノテーションレイヤーを除去します。

  • PDF サムネイルを最速でレンダリングする方法は？ AnnotationApi で PDF をロードし、DPI = 150 に設定して GetPages を呼び出します – 2 MB のファイルで最初のページが 200 ms 未満で PNG として返されます。
  • プレビューで全てのアノテーションを非表示にできますか？ はい – レンダリング前に HideAnnotations フラグを使用してクリーンなビューを生成します。
  • プレビュー生成はスレッドセーフですか？ API はステートレスであり、複数のプレビュータスクを並行して安全に実行できます。
  • 本番環境で使用するためにライセンスが必要ですか？ 無制限のプレビュー生成には有効な GroupDocs.Annotation ライセンスが必要です。
  • サポートされている .NET バージョンはどれですか？ .NET Framework 4.6+、.NET Core 3.1+、.NET 5/6/7。

ドキュメントプレビューとは何ですか？

ドキュメントプレビューは、ファイルの軽量な視覚表現（通常は画像または画像の連続）で、ユーザーが全文書をダウンロードせずに内容をざっと確認できるようにします。UX を向上させ、帯域幅を削減し、レンダリングするものだけを公開することでセキュリティ層を追加します。

なぜセキュアなドキュメントプレビューを使用するのか？

セキュアなドキュメントプレビューは、機密メタデータ、隠しレイヤー、または制限されたアノテーションがサーバーから漏れ出さないことを保証します。GroupDocs.Annotation はプレビューストリームを暗号化し、明示的に許可しないマークアップをすべて除去するため、エンドユーザーが見る内容を完全に制御できます。定量的な主張: ライブラリは 30+ file formats をサポートし、デフォルト DPI 150 を使用した標準的な 8 コアサーバー上で 500‑page PDFs in under 2 seconds を生成できます。

PDF サムネイルはどのようにレンダリングしますか？

AnnotationApi で PDF をロードし、テキストを鮮明にするために DPI を 150‑300 に指定し、最初のページを PNG で要求します。この 2 段階のアプローチはバイト配列を返し、ブラウザへ直接ストリームしたりディスクにキャッシュしたりできます。より高い DPI（例: 300）を使用するとテキストが多い文書の可読性が向上し、低い DPI（例: 72）ではサムネイルグリッドのファイルサイズが削減されます。

前提条件

  • .NET Framework 4.6+ または .NET Core 3.1+ がインストールされていること。
  • 有効な GroupDocs.Annotation ライセンス（評価用に一時ライセンスが使用可能）。
  • プレビュー対象となる PDF、Word、Excel、またはその他のサポートされているファイルへのアクセス。

プレビュー作成のステップバイステップ

プレビューを作成するには、GroupDocs.Annotation パッケージをインストールし、ライセンスで API を初期化し、プレビューオプションを設定し、画像を生成し、必要に応じて結果をキャッシュする必要があります。以下のセクションでは、コード例とともに各ステップを解説し、アノテーションの非表示、DPI の設定、大きなファイルの効率的な処理方法を示します。

ステップ 1: NuGet パッケージをインストール

プロジェクトの Package Manager Console を開き、以下を実行します:

Install-Package GroupDocs.Annotation

ステップ 2: API を初期化

AnnotationApi インスタンスを作成し、ライセンスファイルのパスとオプションの構成（例: キャッシュフォルダー、メモリ制限）を渡します。

var config = new AnnotationConfig
{
    LicensePath = "GroupDocs.Annotation.lic",
    CacheFolder = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Cache")
};
var annotationApi = new AnnotationApi(config);

ステップ 3: アノテーションなしでプレビューを生成

HideAnnotations フラグを true に設定し、目的の DPI を選択し、必要なページを要求します。

var previewOptions = new PreviewOptions
{
    HideAnnotations = true,
    Dpi = 150,
    OutputFormat = PreviewOutputFormat.Png,
    PageNumbers = new[] { 1 }   // first page only for thumbnail
};

byte[] previewBytes = annotationApi.GetPreview("sample.pdf", previewOptions);
File.WriteAllBytes("sample_thumb.png", previewBytes);

GetPreview 呼び出しはバイト配列を返し、HTTP 応答に直接送信したり、CDN に保存したり、UI コンポーネントに埋め込んだりできます。

ステップ 4: プレビューをキャッシュして再利用

同じプレビューを繰り返し生成しないように、ソースファイルとプレビュー設定のハッシュをキャッシュキーとして画像を保存します。ソースドキュメントが変更された場合は、タイムスタンプを比較してキャッシュを無効化します。

string cacheKey = $"{Path.GetFileNameWithoutExtension(filePath)}_{previewOptions.Dpi}_{previewOptions.HideAnnotations}";

ステップ 5: 大きなドキュメントを効率的に処理

100 MB を超えるファイルの場合、using ブロックを使用して AnnotationApi が内部ストリームを速やかに破棄するようにします。マルチページプレビューが必要な場合はページをバッチ処理し、次に進む前に各バッチを解放します。

一般的な実装シナリオ

  • Document management systems – クイックな視覚ナビゲーションのためにサムネイル画像のグリッドを表示します。
  • Collaboration platforms – レビューア向けにプレビューのみのビューをレンダリングし、必要に応じてアノテーションレイヤーを切り替えられるようにします。
  • Web portals – ファイルリンクにホバー時プレビューを表示し、フルダウンロードの必要性を減らします。
  • Mobile apps – 帯域使用量をページあたり 50 KB 未満に抑えるため、低解像度 PNG（72 DPI）を生成します。

プレビュー生成のトラブルシューティング

  • Memory spikes with large PDFs – 各プレビューバッチの後に AnnotationApi の Dispose() を呼び出し、同時プレビュータスクの数を制限してください。
  • Blurry text in thumbnails – DPI を 300 に上げるか、出力形式を PNG に切り替えてください。JPEG 圧縮は細い文字をぼやけさせる可能性があります。
  • Missing images in Excel previews – プレビューオプションで LoadCharts = true を設定し、ワークブックのチャートオブジェクトが完全にロードされていることを確認してください。
  • Slow response times – プレビュー生成をバックグラウンドワーカー（例: Task.Run）に移動し、実際のプレビューが準備できるまでプレースホルダー画像を提供します。

よくある質問

Q: パスワード保護されたドキュメントのプレビューを生成できますか？
A: はい。AnnotationApi インスタンス作成時に LoadOptions でパスワードを指定すれば、復号に成功した後にプレビューが生成されます。

Q: DOCX や XLSX などの非 PDF フォーマットのプレビュー描画をサポートしていますか？
A: もちろんです。GroupDocs.Annotation は 30 以上の異なるフォーマット（DOCX、XLSX、PPTX、各種画像形式など）のプレビューを描画できます。

Q: プレビューが隠しメタデータを露出しないようにするには？
A: PreviewOptions の HideMetadata オプションを使用します。API は画像をレンダリングする前にすべてのドキュメントプロパティを除去します。

Q: プレビューエンドポイントを公開しても安全ですか？
A: プレビューストリームはサーバー側で生成され、HTTPS 経由で配信できます。トークンベースの認証と組み合わせて、認可されたユーザーのみがアクセスできるように制限してください。

Q: 推奨されるキャッシュ有効期限ポリシーは何ですか？
A: ソースドキュメントのバージョン期間中キャッシュします。ドキュメントの最終更新タイムスタンプが変わったら、キャッシュされた画像を無効化し、再生成してください。

追加リソース

最終更新日: 2026-08-09
テスト環境: GroupDocs.Annotation 23.10 for .NET
作者: GroupDocs

関連チュートリアル