アプリケーション レベルのアドインにおける実行時の Word 文書や Excel ブックの拡張

  • [アーティクル]

更新 : 2008 年 7 月

対象

このトピックの情報は、指定された Visual Studio Tools for Office プロジェクトおよび Microsoft Office のバージョンにのみ適用されます。

プロジェクトの種類

  • アプリケーション レベルのプロジェクト

Microsoft Office のバージョン

  • Excel 2007

  • Word 2007

詳細については、「アプリケーションおよびプロジェクトの種類別の使用可能な機能」を参照してください。

Visual Studio 2008 Service Pack 1 (SP1) より、アプリケーション レベルのアドインを使用して、以下のような文書およびブックのカスタマイズができるようになりました。

  • 開いている文書またはワークシートにマネージ コントロールを追加する。

  • 特定の文書またはブックで認識されるスマート タグを作成する。

  • Windows フォームのデータ バインディング モデルを使用して、Excel ワークシート上の既存のリスト オブジェクトを、イベントを公開し、データにバインド可能な Visual Studio Tools for Office リスト オブジェクトに変換する。

  • Word および Excel によって、特定の文書、ブック、ワークシートに対して公開されている、アプリケーション レベルのイベントにアクセスする。

この機能を使用するには、実行時に文書またはブックを拡張する Visual Studio Tools for Office オブジェクトを作成します。

アドインにおける拡張オブジェクトの生成

拡張オブジェクトは、Word または Excel のオブジェクト モデルにネイティブに存在するオブジェクト (ネイティブ Office オブジェクトと呼びます) に対して機能を追加する Visual Studio Tools for Office オブジェクトです。アドイン内で拡張オブジェクトを生成するには、Excel および Word のプライマリ相互運用機能アセンブリで、以下のいずれかの型のインスタンスの GetVstoObject メソッドを使用します。

ネイティブ Office オブジェクトの GetVstoObject メソッドを初めて呼び出すと、オブジェクトを拡張する新しい Visual Studio Tools for Office オブジェクトが返されます。同じネイティブ Office オブジェクトに対してメソッドを呼び出すたびに、同じ拡張オブジェクトを返します。

拡張オブジェクトの型の名前は、ネイティブ Office オブジェクトの型と同じですが、型は Microsoft.Office.Tools.Excel 名前空間または Microsoft.Office.Tools.Word 名前空間で定義されています。たとえば、Microsoft.Office.Interop.Word.Document オブジェクトの GetVstoObject メソッドは、Microsoft.Office.Tools.Word.Document を返します。

あるネイティブ Office オブジェクトに対して既に Visual Studio Tools for Office オブジェクトが生成されているかどうかを判定するには、Office オブジェクトの HasVstoObject メソッドを使用します。詳細については、「Office オブジェクトが拡張されているかどうかを判断する」を参照してください。

GetVstoObject メソッドは、主にアプリケーション レベルのプロジェクトで使用するためのものです。これらのメソッドをドキュメント レベルのプロジェクトで使用することもできますが、動作が異なり、ほとんど使用されません。詳細については、「ドキュメント レベルのカスタマイズにおけるネイティブな Office オブジェクトからの拡張オブジェクトの取得」を参照してください。

Cc442981.alert_note(ja-jp,VS.90).gifメモ :

GetVstoObject メソッドと HasVstoObject メソッドを、ThisAddIn.cs または ThisAddIn.vb 以外のコード ファイルで使用する場合や、SP1 をインストールする前に作成したプロジェクトで使用する場合は、プロジェクトを変更する必要があります。詳細については、「GetVstoObject メソッドと HasVstoObject メソッドを使用するようにプロジェクトを構成する」を参照してください。

ホスト項目の生成

ドキュメント レベルのオブジェクト、つまり Microsoft.Office.Interop.Excel.Workbook、Microsoft.Office.Interop.Excel.Worksheet、または Microsoft.Office.Interop.Word.Document の GetVstoObject メソッドを使用する場合、返されたオブジェクトはホスト項目と呼ばれます。ホスト項目は、他の拡張オブジェクトやコントロールなど、他のオブジェクトを格納できる型です。Word や Excel のプライマリ相互運用機能アセンブリの対応する型に似ていますが、追加の機能を備えています。ホスト項目の詳細については、「ホスト項目とホスト コントロールの概要」を参照してください。

ホスト項目を生成した後、それを使用して、文書、ブック、またはワークシートにスマート タグやマネージ コントロールを追加できます。詳細については、「文書とブックへのスマート タグの追加」および「文書とワークシートへのマネージ コントロールの追加」を参照してください。

Word 文書のホスト項目を生成するには

  • Microsoft.Office.Interop.Word.Document の GetVstoObject メソッドを使用します。アクティブな文書のホスト項目を生成するコード例を次に示します。

    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 = _
        NativeDocument.GetVstoObject()
End If

    if (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 ブックのホスト項目を生成するには

  • Microsoft.Office.Interop.Excel.Workbook の GetVstoObject メソッドを使用します。アクティブなブックのホスト項目を生成するコード例を次に示します。

    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 If

    Microsoft.Office.Interop.Excel.Workbook nativeWorkbook =
    Globals.ThisAddIn.Application.ActiveWorkbook;

if (nativeWorkbook != null)
{
    Microsoft.Office.Tools.Excel.Workbook vstoWorkbook =
        nativeWorkbook.GetVstoObject();
}

Excel ワークシートのホスト項目を生成するには

  • Microsoft.Office.Interop.Excel.Worksheet の GetVstoObject メソッドを使用します。アクティブなワークシートからホスト項目を生成するコード例を次に示します。

    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 If

    Microsoft.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 ホスト コントロールの生成

Microsoft.Office.Interop.Excel.ListObject の GetVstoObject メソッドを使用すると、このメソッドは Microsoft.Office.Tools.Excel.ListObject を返します。生成された Microsoft.Office.Tools.Excel.ListObject は、元の Microsoft.Office.Interop.Excel.ListObject の機能をすべて備えていますが、Windows フォームのデータ バインディング モデルを使用してデータにバインドできるなど、追加の機能も備えています。詳細については、「ListObject コントロール」を参照してください。

ListObject のホスト コントロールを生成するには

  • Microsoft.Office.Interop.Excel.ListObject の GetVstoObject メソッドを使用します。アクティブなワークシートの最初の Microsoft.Office.Interop.Excel.ListObject に対する Microsoft.Office.Tools.Excel.ListObject を生成するコード例を次に示します。

    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 If

    Microsoft.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 フォーム コントロールまたはホスト コントロールを追加できます。ホスト コントロールは、Word や Excel のプライマリ相互運用機能アセンブリの対応するコントロールをラップする Visual Studio Tools for Office コントロールです。ホスト コントロールでは、下位のネイティブ Office オブジェクトのすべての動作が利用できますが、イベントを発生させ、Windows フォームのデータ バインディング モデルを使用してデータにバインドすることもできます。詳細については、「ホスト項目とホスト コントロールの概要」を参照してください。

Cc442981.alert_note(ja-jp,VS.90).gifメモ :

アドインを使用して、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 文書のアプリケーション レベルのイベントを処理する方法を次のコード例に示します。この例の CreateDocument1 メソッドは、新しい文書を作成し、この文書が保存されるのを防ぐイベント ハンドラ 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 が保存されたときだけ呼び出されるため、保存された文書を確認するという追加の処理を行わずに、保存動作を取り消すことができます。

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 = 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 オブジェクトに対して既に Visual Studio Tools for Office オブジェクトが生成されているかどうかを判定するには、Office オブジェクトの HasVstoObject メソッドを使用します。このメソッドは、拡張オブジェクトが既に生成されている場合は true を返し、そうでない場合は false を返します。

これは、指定した Office オブジェクトに拡張オブジェクトがあるときだけコードを実行する場合に役立ちます。たとえば、DocumentBeforeSave イベントを処理して、文書が保存される前にマネージ コントロールを文書から削除する Word アドインがある場合、HasVstoObject メソッドを使用して、文書が拡張されているかどうかを判断できます。文書が拡張されていない場合は、マネージ コントロールが含まれていないため、イベント ハンドラは文書上のコントロールをクリーンアップせずに戻るだけで済みます。

GetVstoObject メソッドと HasVstoObject メソッドを使用するようにプロジェクトを構成する

Visual Studio 2008 SP1 をインストールした後で、アプリケーション レベルのプロジェクトを作成すると、プロジェクトは GetVstoObject メソッドと HasVstoObject メソッドを ThisAddIn.cs または ThisAddIn.vb のどちらかのコード ファイルで使用するように自動的に構成されます。

これらのメソッドを ThisAddIn.cs または ThisAddIn.vb 以外のコード ファイルで使用するには、コード ファイルを以下のように変更する必要があります。

拡張オブジェクトを作成するように Excel プロジェクトのコード ファイルを変更するには

  • 次の using ステートメント (C# の場合) または Imports ステートメント (Visual Basic の場合) を、GetVstoObject メソッドと HasVstoObject メソッドを使用するコード ファイルの先頭に追加します。

    Imports Microsoft.Office.Tools.Excel.Extensions

    using Microsoft.Office.Tools.Excel.Extensions;

拡張オブジェクトを作成するように Word プロジェクトのコード ファイルを変更するには

  • 次の using ステートメント (C# の場合) または Imports ステートメント (Visual Basic の場合) を、GetVstoObject メソッドと HasVstoObject メソッドを使用するコード ファイルの先頭に追加します。

    Imports Microsoft.Office.Tools.Excel.Extensions

    using Microsoft.Office.Tools.Excel.Extensions;

SP1 をインストールする前に作成したアプリケーション レベルのプロジェクトでこれらのメソッドを使用するには、以下のようにプロジェクトを変更する必要があります。

拡張オブジェクトを作成するように既存の Excel アドインを変更するには

  1. Microsoft.Office.Tools.Excel.v9.0.dll アセンブリへの参照を追加します。

  2. 次の using ステートメント (C# の場合) または Imports ステートメント (Visual Basic の場合) を、GetVstoObject メソッドと HasVstoObject メソッドを使用するコード ファイルの先頭に追加します。

    Imports Microsoft.Office.Tools.Excel.Extensions

    using Microsoft.Office.Tools.Excel.Extensions;

拡張オブジェクトを作成するように既存の Word アドインを変更するには

  1. Microsoft.Office.Tools.Word.v9.0.dll アセンブリへの参照を追加します。

  2. 次の using ステートメント (C# の場合) または Imports ステートメント (Visual Basic の場合) を、GetVstoObject メソッドと HasVstoObject メソッドを使用するコード ファイルの先頭に追加します。

    Imports Microsoft.Office.Tools.Word.Extensions

    using Microsoft.Office.Tools.Word.Extensions;

これらの変更が必要なのは、GetVstoObject メソッドと HasVstoObject メソッドが拡張メソッドとして実装されているためです。GetVstoObject メソッドと HasVstoObject メソッドは、Excel または Word のプライマリ相互運用機能アセンブリ内の型で定義されているかのように使用できますが、実際には Visual Studio Tools for Office ランタイムの Microsoft.Office.Tools.Excel.Extensions 名前空間および Microsoft.Office.Tools.Word.Extensions 名前空間内の型で定義されています。拡張メソッドの詳細については、「拡張メソッド (C# プログラミング ガイド)」および「拡張メソッド (Visual Basic)」を参照してください。

参照

処理手順

Excel アドインのダイナミック コントロールのサンプル

Word アドインのダイナミック コントロールのサンプル

概念

アプリケーション レベルのアドインのプログラミング

実行時の Office ドキュメントへのコントロールの追加

ホスト項目とホスト コントロールの概要

スマート タグの概要

ドキュメント レベルのカスタマイズにおけるネイティブな Office オブジェクトからの拡張オブジェクトの取得

履歴の変更

日付

履歴

理由

2008 年 7 月

トピックを追加

SP1 機能変更