アプリケーション レベルのアドインにおける実行時の Word 文書や Excel ブックの拡張
アプリケーション レベルのアドインを使用して、以下のような Word 文書および Excel ブックのカスタマイズができます。
開いている文書またはワークシートにマネージ コントロールを追加する。
特定の文書またはブックで認識されるスマート タグを作成する。
注意
スマート タグは、Excel 2010 および Word 2010 では使用されていません。 詳細については、「スマート タグの概要」を参照してください。
Windows フォームのデータ バインド モデルを使用して、Excel ワークシート上の既存のリスト オブジェクトを、イベントを公開し、データにバインドできる、拡張された ListObject に変換する。
Word および Excel によって、特定の文書、ブック、ワークシートに対して公開されている、アプリケーション レベルのイベントにアクセスする。
この機能を使用するには、実行時に文書またはブックを拡張するオブジェクトを作成します。
対象: このトピックの情報は、Excel 2007 と Excel 2010、および Word 2007 と Word 2010 のアプリケーション レベルのプロジェクトに適用されます。詳細については、「Office アプリケーションおよびプロジェクト タイプ別の使用可能な機能」を参照してください。
アドインにおける拡張オブジェクトの生成
拡張オブジェクトは、Word または Excel のオブジェクト モデルにネイティブに存在するオブジェクト (ネイティブ Office オブジェクトと呼びます) に対して機能を追加する、Visual Studio Tools for Office ランタイムによって提供される型のインスタンスです。 Word オブジェクトまたは Excel オブジェクト用に拡張オブジェクトを生成するには、GetVstoObject メソッドを使用します。 指定した Word オブジェクトまたは Excel オブジェクトに対して初めて GetVstoObject メソッドを呼び出すと、指定したオブジェクトを拡張する新しいオブジェクトが返されます。このメソッドを呼び出し、同じ Word オブジェクトまたは Excel オブジェクトを指定するたびに、同じ拡張オブジェクトが返されます。
拡張オブジェクトの型の名前は、ネイティブ Office オブジェクトの型と同じですが、型は Microsoft.Office.Tools.Excel 名前空間または Microsoft.Office.Tools.Word 名前空間で定義されています。 たとえば、GetVstoObject メソッドを呼び出して Microsoft.Office.Interop.Word.Document オブジェクトを拡張する場合、このメソッドは Microsoft.Office.Tools.Word.Document オブジェクトを返します。
GetVstoObject メソッドにアクセスする方法は、プロジェクトで対象とする .NET Framework のバージョンによって異なります。
.NET Framework 3.5 を対象とするプロジェクトの場合は、Excel および Word のプライマリ相互運用機能アセンブリで次に示す型のインスタンスに対して GetVstoObject メソッドを使用します。
.NET Framework 4 を対象とするプロジェクトの場合は、Globals.Factory.GetVstoObject メソッドを使用し、拡張するネイティブの Word オブジェクトまたは Excel オブジェクト (Microsoft.Office.Interop.Word.Document、Microsoft.Office.Interop.Excel.Worksheet など) を渡します。
GetVstoObject メソッドは、主にアプリケーション レベルのプロジェクトで使用するためのものです。 これらのメソッドをドキュメント レベルのプロジェクトで使用することもできますが、動作が異なり、ほとんど使用されません。 詳細については、「ドキュメント レベルのカスタマイズにおけるネイティブな Office オブジェクトからの拡張オブジェクトの取得」を参照してください。
あるネイティブ Office オブジェクトに対して既に拡張オブジェクトが生成されているかどうかを判断するには、HasVstoObject メソッドを使用します。 詳細については、「Office オブジェクトが拡張されているかどうかを判断する」を参照してください。
注意
GetVstoObject メソッドと HasVstoObject メソッドを、.NET Framework 3.5 を対象とする ThisAddIn.cs または ThisAddIn.vb 以外のコード ファイルで使用する場合は、プロジェクトを変更する必要があります。 詳細については、「GetVstoObject メソッドと HasVstoObject メソッドを使用するようにプロジェクトを構成する」を参照してください。
ホスト項目の生成
GetVstoObject を使用してドキュメント レベルのオブジェクト (Microsoft.Office.Interop.Excel.Workbook、Microsoft.Office.Interop.Excel.Worksheet、または Microsoft.Office.Interop.Word.Document) を拡張する場合、返されたオブジェクトはホスト項目と呼ばれます。 ホスト項目は、他の拡張オブジェクトやコントロールなど、他のオブジェクトを格納できる型です。 Word や Excel のプライマリ相互運用機能アセンブリの対応する型に似ていますが、追加の機能を備えています。 ホスト項目の詳細については、「ホスト項目とホスト コントロールの概要」を参照してください。
ホスト項目を生成した後、それを使用して、文書、ブック、またはワークシートにスマート タグやマネージ コントロールを追加できます。 詳細については、「文書とブックへのスマート タグの追加」および「文書とワークシートへのマネージ コントロールの追加」を参照してください。
Word 文書のホスト項目を生成するには
次のコード例は、.NET Framework 4 を対象とするプロジェクトでアクティブな文書用のホスト項目を生成する方法を示しています。
If Globals.ThisAddIn.Application.Documents.Count > 0 Then Dim NativeDocument As Microsoft.Office.Interop.Word.Document = _ Globals.ThisAddIn.Application.ActiveDocument Dim VstoDocument As Microsoft.Office.Tools.Word.Document = _ Globals.Factory.GetVstoObject(NativeDocument) End Ifif (Globals.ThisAddIn.Application.Documents.Count > 0) { Microsoft.Office.Interop.Word.Document nativeDocument = Globals.ThisAddIn.Application.ActiveDocument; Microsoft.Office.Tools.Word.Document vstoDocument = Globals.Factory.GetVstoObject(nativeDocument); }次のコード例は、同じ作業を .NET Framework 3.5 を対象とするプロジェクトで行う方法を示しています。
If Globals.ThisAddIn.Application.Documents.Count > 0 Then Dim NativeDocument As Microsoft.Office.Interop.Word.Document = Globals.ThisAddIn.Application.ActiveDocument If NativeDocument IsNot Nothing Then Dim vstoDocument As Microsoft.Office.Tools.Word.Document = NativeDocument.GetVstoObject() End If End Ifif (Globals.ThisAddIn.Application.Documents.Count > 0) { Microsoft.Office.Interop.Word.Document nativeDocument = Globals.ThisAddIn.Application.ActiveDocument; Microsoft.Office.Tools.Word.Document vstoDocument = nativeDocument.GetVstoObject(); }
Excel ブックのホスト項目を生成するには
次のコード例は、.NET Framework 4 を対象とするプロジェクトでアクティブなブック用のホスト項目を生成する方法を示しています。
Dim NativeWorkbook As Microsoft.Office.Interop.Excel.Workbook = Globals.ThisAddIn.Application.ActiveWorkbook If NativeWorkbook IsNot Nothing Then Dim vstoWorkbook As Microsoft.Office.Tools.Excel.Workbook = Globals.Factory.GetVstoObject(NativeWorkbook) End IfMicrosoft.Office.Interop.Excel.Workbook nativeWorkbook = Globals.ThisAddIn.Application.ActiveWorkbook; if (nativeWorkbook != null) { Microsoft.Office.Tools.Excel.Workbook vstoWorkbook = Globals.Factory.GetVstoObject(nativeWorkbook); }次のコード例は、同じ作業を .NET Framework 3.5 を対象とするプロジェクトで行う方法を示しています。
Dim NativeWorkbook As Microsoft.Office.Interop.Excel.Workbook = _ Globals.ThisAddIn.Application.ActiveWorkbook If NativeWorkbook IsNot Nothing Then Dim VstoWorkbook As Microsoft.Office.Tools.Excel.Workbook = _ NativeWorkbook.GetVstoObject() End IfMicrosoft.Office.Interop.Excel.Workbook nativeWorkbook = Globals.ThisAddIn.Application.ActiveWorkbook; if (nativeWorkbook != null) { Microsoft.Office.Tools.Excel.Workbook vstoWorkbook = nativeWorkbook.GetVstoObject(); }
Excel ワークシートのホスト項目を生成するには
次のコード例は、.NET Framework 4 を対象とするプロジェクトでアクティブなワークシート用のホスト項目を生成する方法を示しています。
Dim NativeWorksheet As Microsoft.Office.Interop.Excel.Worksheet = Globals.ThisAddIn.Application.ActiveSheet If NativeWorksheet IsNot Nothing Then Dim vstoSheet As Microsoft.Office.Tools.Excel.Worksheet = Globals.Factory.GetVstoObject(NativeWorksheet) End IfMicrosoft.Office.Interop.Excel.Worksheet nativeWorksheet = Globals.ThisAddIn.Application.ActiveSheet; if (nativeWorksheet != null) { Microsoft.Office.Tools.Excel.Worksheet vstoSheet = Globals.Factory.GetVstoObject(nativeWorksheet); }次のコード例は、同じ作業を .NET Framework 3.5 を対象とするプロジェクトで行う方法を示しています。
Dim NativeSheet As Microsoft.Office.Interop.Excel.Worksheet = _ TryCast(Globals.ThisAddIn.Application.ActiveSheet, _ Microsoft.Office.Interop.Excel.Worksheet) If NativeSheet IsNot Nothing Then Dim VstoSheet As Microsoft.Office.Tools.Excel.Worksheet = _ NativeSheet.GetVstoObject() End IfMicrosoft.Office.Interop.Excel.Worksheet nativeSheet = Globals.ThisAddIn.Application.ActiveSheet as Microsoft.Office.Interop.Excel.Worksheet; if (nativeSheet != null) { Microsoft.Office.Tools.Excel.Worksheet vstoSheet = nativeSheet.GetVstoObject(); }
ListObject ホスト コントロールの生成
GetVstoObject メソッドを使用して Microsoft.Office.Interop.Excel.ListObject を拡張する場合、このメソッドは Microsoft.Office.Tools.Excel.ListObject を返します。 Microsoft.Office.Tools.Excel.ListObject には、元の Microsoft.Office.Interop.Excel.ListObject のすべての機能が備わっているだけでなく、Windows フォームのデータ バインド モデルを使用してデータにバインドできるなど、追加の機能も備わっています。 詳細については、「ListObject コントロール」を参照してください。
ListObject のホスト コントロールを生成するには
次のコード例は、.NET Framework 4 を対象とするプロジェクト内のアクティブなワークシートにある最初の Microsoft.Office.Interop.Excel.ListObject 用に Microsoft.Office.Tools.Excel.ListObject を生成する方法を示しています。
Dim sheet As Microsoft.Office.Interop.Excel.Worksheet = Globals.ThisAddIn.Application.ActiveSheet If sheet.ListObjects.Count > 0 Then Dim listObject As Excel.ListObject = sheet.ListObjects(1) Dim vstoListObject As Microsoft.Office.Tools.Excel.ListObject = Globals.Factory.GetVstoObject(listObject) End IfMicrosoft.Office.Interop.Excel.Worksheet sheet = Globals.ThisAddIn.Application.ActiveSheet; if (sheet.ListObjects.Count > 0) { Excel.ListObject listObject = sheet.ListObjects[1]; Microsoft.Office.Tools.Excel.ListObject vstoListObject = Globals.Factory.GetVstoObject(listObject); }次のコード例は、同じ作業を .NET Framework 3.5 を対象とするプロジェクトで行う方法を示しています。
Dim sheet As Excel.Worksheet = Globals.ThisAddIn.Application.ActiveSheet If sheet.ListObjects.Count > 0 Then Dim listObject As Excel.ListObject = sheet.ListObjects(1) Dim vstoListObject As Microsoft.Office.Tools.Excel.ListObject = _ listObject.GetVstoObject() End IfMicrosoft.Office.Interop.Excel.Worksheet sheet = Globals.ThisAddIn.Application.ActiveSheet as Microsoft.Office.Interop.Excel.Worksheet; if (sheet.ListObjects.Count > 0) { Excel.ListObject listObject = sheet.ListObjects[1]; Microsoft.Office.Tools.Excel.ListObject vstoListObject = listObject.GetVstoObject(); }
文書とブックへのスマート タグの追加
Microsoft.Office.Tools.Word.Document または Microsoft.Office.Tools.Excel.Workbook を生成した後、これらのオブジェクトが表す文書またはブックのコンテキストで認識されるスマート タグを作成できます。 これを行うには、Microsoft.Office.Tools.Word.Document または Microsoft.Office.Tools.Excel.Workbook の VstoSmartTags プロパティを使用します。 詳細については、次のトピックを参照してください。
文書とワークシートへのマネージ コントロールの追加
Microsoft.Office.Tools.Word.Document または Microsoft.Office.Tools.Excel.Worksheet を生成した後、これらの拡張オブジェクトが表す文書またはワークシートにコントロールを追加できます。 これを行うには、Microsoft.Office.Tools.Word.Document または Microsoft.Office.Tools.Excel.Worksheet の Controls プロパティを使用します。 詳細については、「実行時の Office ドキュメントへのコントロールの追加」を参照してください。
Windows フォーム コントロールまたはホスト コントロールを追加できます。 ホスト コントロールは、Visual Studio Tools for Office Runtime に用意されているコントロールであり、Word や Excel のプライマリ相互運用機能アセンブリの対応するコントロールをラップします。 ホスト コントロールでは、下位のネイティブ Office オブジェクトのすべての動作が利用できますが、イベントを発生させ、Windows フォームのデータ バインド モデルを使用してデータにバインドすることもできます。 詳細については、「ホスト項目とホスト コントロールの概要」を参照してください。
注意
アドインを使用して、XmlMappedRange コントロールをワークシートに追加したり、XMLNode コントロールや XMLNodes コントロールを文書に追加することはできません。 これらのホスト コントロールをプログラムで追加することはできません。 詳細については、「ホスト項目およびホスト コントロールのプログラム上の制限事項」を参照してください。
コントロールの永続化と削除
マネージ コントロールを文書またはワークシートに追加する場合、文書を保存して閉じるとコントロールは永続化されません。 すべてのホスト コントロールは削除されるため、下位のネイティブ Office オブジェクトだけが残ります (たとえば、Microsoft.Office.Tools.Excel.ListObject は Microsoft.Office.Interop.Excel.ListObject になります)。 Windows フォーム コントロールもすべて削除されますが、コントロールの ActiveX ラッパーはドキュメント内に残ります。 コントロールをクリーン アップする場合や、次にドキュメントを開いたときにコントロールを再度作成するには、アドインにコードを追加する必要があります。 詳細については、「Office ドキュメントでのダイナミック コントロールの永続化」を参照してください。
文書とブックに対するアプリケーション レベル イベントへのアクセス
ネイティブな Word および Excel オブジェクト モデルにおける一部の文書、ブック、ワークシートのイベントは、アプリケーション レベルでのみ発生します。 たとえば、Word で文書を開くと DocumentBeforeSave イベントが発生しますが、このイベントは Microsoft.Office.Interop.Word.Document クラスではなく、Microsoft.Office.Interop.Word.Application クラスで定義されています。
アドインでネイティブ Office オブジェクトだけを使用する場合、これらのアプリケーション レベルのイベントを処理し、イベントが発生した文書がカスタマイズした文書かどうかを判断するための追加のコードを記述する必要があります。 ホスト項目では、個別のドキュメントのイベントが扱いやすくなるように、これらのイベントがドキュメント レベルで発生します。 ホスト項目を生成し、そのホスト項目のイベントを処理できます。
ネイティブな Word オブジェクトの使用例
Word 文書のアプリケーション レベルのイベントを処理する方法を次のコード例に示します。 CreateDocument メソッドは、新しい文書を作成し、この文書が保存されるのを防ぐイベント ハンドラー DocumentBeforeSave を定義します。 これは、Microsoft.Office.Interop.Word.Application オブジェクトに対して発生するアプリケーション レベルのイベントであるため、イベント ハンドラーは Doc パラメーターを document1 オブジェクトと比較して、document1 が保存される文書を表しているかどうかを判断する必要があります。
Private document1 As Word.Document = Nothing
Private Sub CreateDocument1()
document1 = Me.Application.Documents.Add()
End Sub
Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) _
Handles Application.DocumentBeforeSave
If Type.ReferenceEquals(Doc, document1) Then
Cancel = True
End If
End Sub
private Word.Document document1 = null;
private void CreateDocument1()
{
document1 = this.Application.Documents.Add(ref missing,
ref missing, ref missing, ref missing);
this.Application.DocumentBeforeSave +=
new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
Application_DocumentBeforeSave);
}
private void Application_DocumentBeforeSave(Word.Document Doc,
ref bool SaveAsUI, ref bool Cancel)
{
if (Type.ReferenceEquals(Doc, document1))
{
Cancel = true;
}
}
ホスト項目の使用例
次のコード例では、ホスト項目 Microsoft.Office.Tools.Word.Document の BeforeSave イベントを処理することで、このプロセスが簡略化されます。 この例の CreateDocument2 メソッドは、document2 オブジェクトを拡張する Microsoft.Office.Tools.Word.Document を生成し、文書が保存されるのを防ぐイベント ハンドラー BeforeSave を定義します。 このイベント ハンドラーは、document2 が保存されたときだけ呼び出されるため、保存された文書を確認するという追加の処理を行わずに、保存動作を取り消すことができます。
次のコード例は、同じ作業を .NET Framework 4 を対象とするプロジェクトで行う方法を示しています。
Private document2 As Word.Document = Nothing
Private WithEvents vstoDocument As Microsoft.Office.Tools.Word.Document = Nothing
Private Sub CreateDocument2()
document2 = Me.Application.Documents.Add()
vstoDocument = Globals.Factory.GetVstoObject(document2)
End Sub
Private Sub vstoDocument_BeforeSave(ByVal sender As Object, _
ByVal e As SaveEventArgs) Handles vstoDocument.BeforeSave
e.Cancel = True
End Sub
private Word.Document document2 = null;
private Microsoft.Office.Tools.Word.Document vstoDocument = null;
private void CreateDocument2()
{
document2 = this.Application.Documents.Add(ref missing,
ref missing, ref missing, ref missing);
vstoDocument = Globals.Factory.GetVstoObject(document2);
vstoDocument.BeforeSave += new SaveEventHandler(vstoDocument_BeforeSave);
}
private void vstoDocument_BeforeSave(object sender, SaveEventArgs e)
{
e.Cancel = true;
}
次のコード例は、同じ作業を .NET Framework 3.5 を対象とするプロジェクトで行う方法を示しています。
Private document2 As Microsoft.Office.Interop.Word.Document = Nothing
Private WithEvents vstoDocument As Microsoft.Office.Tools.Word.Document = Nothing
Private Sub CreateDocument2()
document2 = Me.Application.Documents.Add()
vstoDocument = document2.GetVstoObject()
End Sub
Private Sub vstoDocument_BeforeSave(ByVal sender As Object,
ByVal e As SaveEventArgs) Handles vstoDocument.BeforeSave
e.Cancel = True
End Sub
private Word.Document document2 = null;
private Microsoft.Office.Tools.Word.Document vstoDocument = null;
private void CreateDocument2()
{
document2 = this.Application.Documents.Add(ref missing,
ref missing, ref missing, ref missing);
vstoDocument = document2.GetVstoObject();
vstoDocument.BeforeSave += new SaveEventHandler(vstoDocument_BeforeSave);
}
private void vstoDocument_BeforeSave(object sender, SaveEventArgs e)
{
e.Cancel = true;
}
Office オブジェクトが拡張されているかどうかを判断する
あるネイティブ Office オブジェクトに対して既に拡張オブジェクトが生成されているかどうかを判断するには、HasVstoObject メソッドを使用します。 このメソッドは、拡張オブジェクトが既に生成されている場合は true を返し、そうでない場合は false を返します。
.NET Framework 3.5 を対象とするプロジェクトの場合は、Excel および Word のプライマリ相互運用機能アセンブリで次に示す型のインスタンスに対して HasVstoObject メソッドを使用できます。
.NET Framework 4 を対象とするプロジェクトでは、Globals.Factory.HasVstoMethod メソッドを使用します。 拡張オブジェクトをテストするネイティブな Word オブジェクトまたは Excel オブジェクト (Microsoft.Office.Interop.Word.Document、Microsoft.Office.Interop.Excel.Worksheet など) を渡します。
HasVstoObject メソッドは、指定した Office オブジェクトが拡張オブジェクトを持つときにのみコードを実行する場合に役立ちます。 たとえば、DocumentBeforeSave イベントを処理して、文書が保存される前にマネージ コントロールを文書から削除する Word アドインがある場合、HasVstoObject メソッドを使用して、文書が拡張されているかどうかを判断できます。 文書が拡張されていない場合は、マネージ コントロールが含まれていないため、イベント ハンドラーは文書上のコントロールをクリーンアップせずに戻るだけで済みます。
GetVstoObject メソッドと HasVstoObject メソッドを使用するように .NET Framework 3.5 プロジェクトを構成する
.NET Framework 3.5 を対象とするアプリケーション レベルのプロジェクトを作成すると、プロジェクトは GetVstoObject メソッドと HasVstoObject メソッドを ThisAddIn.cs または ThisAddIn.vb のどちらかのコード ファイルで使用するように自動的に構成されます。 これらのメソッドを ThisAddIn.cs または ThisAddIn.vb 以外のコード ファイルで使用するには、コード ファイルを以下のように変更する必要があります。
拡張オブジェクトを作成するように Excel プロジェクトのコード ファイルを変更するには
次の using ステートメント (C# の場合) または Imports ステートメント (Visual Basic の場合) を、GetVstoObject メソッドと HasVstoObject メソッドを使用するコード ファイルの先頭に追加します。
Imports Microsoft.Office.Tools.Excel.Extensionsusing Microsoft.Office.Tools.Excel.Extensions;
拡張オブジェクトを作成するように Word プロジェクトのコード ファイルを変更するには
次の using ステートメント (C# の場合) または Imports ステートメント (Visual Basic の場合) を、GetVstoObject メソッドと HasVstoObject メソッドを使用するコード ファイルの先頭に追加します。
Imports Microsoft.Office.Tools.Word.Extensionsusing Microsoft.Office.Tools.Word.Extensions;
これらの変更が必要なのは、GetVstoObject メソッドと HasVstoObject メソッドが拡張メソッドとして実装されているためです。 GetVstoObject メソッドと HasVstoObject メソッドは、Excel または Word のプライマリ相互運用機能アセンブリ内の型で定義されているかのように使用できますが、実際には Visual Studio Tools for Office Runtime の Microsoft.Office.Tools.Excel.Extensions 名前空間および Microsoft.Office.Tools.Word.Extensions 名前空間内の型で定義されています。 拡張メソッドの詳細については、「拡張メソッド (C# プログラミング ガイド)」および「拡張メソッド (Visual Basic)」を参照してください。
参照
概念
ドキュメント レベルのカスタマイズにおけるネイティブな Office オブジェクトからの拡張オブジェクトの取得