データ オブジェクトをドキュメント レベルのカスタマイズでキャッシュして、データにオフラインでアクセスしたり、Microsoft Office Word や Microsoft Office Excel を開いたりしないようにすることができます。 オブジェクトをキャッシュするには、オブジェクトに特定の要件を満たすデータ型が必要です。 .NET Framework の多くの一般的なデータ型は、 String、 DataSet、 DataTableなど、これらの要件を満たしています。
適用対象: このトピックの情報は、Excel および Word のドキュメント レベルのプロジェクトに適用されます。 詳細については、「 Office アプリケーションとプロジェクトの種類で使用できる機能」を参照してください。
データ キャッシュにオブジェクトを追加するには、次の 2 つの方法があります。
ソリューションのビルド時にデータ キャッシュにオブジェクトを追加するには、 CachedAttribute 属性をオブジェクト宣言に適用します。 詳細については、「 方法: オフラインまたはサーバーで使用するためにデータをキャッシュする」を参照してください。
実行時にプログラムでオブジェクトをデータ キャッシュに追加するには、ホスト項目の
StartCachingメソッド (ThisDocumentやThisWorkbookクラスなど) を使用します。 詳細については、「 方法: プログラムによって Office ドキュメントにデータ ソースをキャッシュする」を参照してください。データ キャッシュにオブジェクトを追加した後は、Word または Excel を起動せずに、キャッシュされたデータにアクセスして変更できます。 詳細については、 サーバー上のドキュメント内のデータへのアクセスを参照してください。
キャッシュされるデータ オブジェクトの要件
ソリューションにデータ オブジェクトをキャッシュするには、オブジェクトが次の要件を満たしている必要があります。
ThisDocumentやThisWorkbookクラスなど、ホスト項目の読み取り/書き込みパブリック フィールドまたはプロパティである。インデクサーまたはその他のパラメーター化されたプロパティではありません。
さらに、データ オブジェクトは、 XmlSerializer クラスによってシリアル化可能である必要があります。つまり、オブジェクトの型には次の特性が必要です。
パブリック型にする。
パラメーターを持たないパブリック コンストラクターを用意します。
追加のセキュリティ特権を必要とするコードは実行しません。
読み取り/書き込みパブリック プロパティのみを公開します (他のプロパティは無視されます)。
多次元配列を公開しません (入れ子になった配列を受け入れます)。
プロパティとフィールドからインターフェイスを返しません。
コレクションの場合、 IDictionary を実装しません。
データ オブジェクトをキャッシュすると、Visual Studio Tools for Office ランタイムは、ドキュメント内の カスタム XML パーツ に格納されている XML 文字列にオブジェクトをシリアル化します。 詳細については、「 カスタム XML パーツの概要」を参照してください。
キャッシュされたデータ サイズの制限
ドキュメント内のデータ キャッシュに追加できるデータの合計量と、データ キャッシュ内の個々のオブジェクトのサイズには、いくつかの制限があります。 これらの制限を超えると、データがデータ キャッシュに保存されるときに、アプリケーションが予期せず閉じる可能性があります。
これらの制限を回避するには、次のガイドラインに従ってください。
10 MB を超えるオブジェクトをデータ キャッシュに追加しないでください。
1 つのドキュメントのデータ キャッシュに合計 100 MB を超えるデータを追加しないでください。
これらはおおよその値です。 正確な制限は、使用可能な RAM や実行中のプロセスの数など、いくつかの要因によって異なります。
キャッシュされたオブジェクトの動作を制御する
キャッシュされたオブジェクトの動作をより詳細に制御するには、キャッシュされたオブジェクトの型に ICachedType インターフェイスを実装します。 たとえば、オブジェクトが変更されたときにユーザーに通知する方法を制御する場合は、このインターフェイスを実装できます。
ICachedTypeを実装する方法を示すコード例については、ControlCollectionの「Excel 動的コントロールのサンプル」および「Word 動的コントロールのサンプル」の クラスを参照してください。
パスワードで保護されたドキュメントでキャッシュされたデータへの変更を保持する
パスワードで保護されているドキュメント内のデータ オブジェクトをキャッシュする場合、キャッシュされたデータに対する変更は保存されません。 2 つのメソッドをオーバーライドすることで、キャッシュされたデータに対する変更を保存できます。 これらのメソッドをオーバーライドして、ドキュメントの保存時に保護を一時的に削除し、保存操作の完了後に保護を再適用します。
詳細については、「 方法: パスワードで保護されたドキュメントにデータをキャッシュする」を参照してください。
null 値をデータ キャッシュに追加するときにデータが失われるのを防ぐ
データ キャッシュにオブジェクトを追加する場合、ドキュメントを保存して閉じる前に、キャッシュされたすべてのオブジェクトを null 以外の値に初期化する必要があります。 ドキュメントを保存して閉じるときにキャッシュされたオブジェクトに null 値がある場合、Visual Studio Tools for Office ランタイムは、キャッシュされたすべてのオブジェクトをデータ キャッシュから自動的に削除します。
デザイン時に 属性を使用して CachedAttribute 値を持つオブジェクトをデータ キャッシュに追加する場合は、ServerDocument クラスを使用して、ドキュメントを開く前にキャッシュされたデータ オブジェクトを初期化できます。 これは、エンド ユーザーがドキュメントを開く前に、Word または Excel がインストールされていないサーバーでキャッシュされたデータを初期化する場合に便利です。 詳細については、 サーバー上のドキュメント内のデータへのアクセスを参照してください。