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

• Microsoft.Office.Interop.Excel..::.ListObject。

• Microsoft.Office.Interop.Excel..::.Workbook。

• Microsoft.Office.Interop.Excel..::.Worksheet。

• Microsoft.Office.Interop.Word..::.Document。

ネイティブ 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 オブジェクトからの拡張オブジェクトの取得」を参照してください。

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

ホスト項目の生成

ListObject ホスト コントロールの生成

Microsoft.Office.Tools.Word..::.Document または Microsoft.Office.Tools.Excel..::.Workbook を生成した後、これらのオブジェクトが表す文書またはブックのコンテキストで認識されるスマート タグを作成できます。これを行うには、Microsoft.Office.Tools.Word..::.Document または Microsoft.Office.Tools.Excel..::.Workbook の VstoSmartTags プロパティを使用します。詳細については、次のトピックを参照してください。

• 方法 : Word 文書にスマート タグを追加する

• 方法 : Excel ブックにスマート タグを追加する

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 フォームのデータ バインディング モデルを使用してデータにバインドすることもできます。詳細については、「ホスト項目とホスト コントロールの概要」を参照してください。

メモ :
アドインを使用して、XmlMappedRange コントロールをワークシートに追加したり、XMLNode コントロールや XMLNodes コントロールを文書に追加することはできません。これらのホスト コントロールをプログラムで追加することはできません。詳細については、「ホスト項目およびホスト コントロールのプログラム上の制限事項」を参照してください。

コントロールの永続化と削除

ネイティブな Word および Excel オブジェクト モデルにおける一部の文書、ブック、ワークシートのイベントは、アプリケーション レベルでのみ発生します。たとえば、Word で文書を開くと DocumentBeforeSave イベントが発生しますが、このイベントは Microsoft.Office.Interop.Word..::.Document クラスではなく、Microsoft.Office.Interop.Word..::.Application クラスで定義されています。

アドインでネイティブ Office オブジェクトだけを使用する場合、これらのアプリケーション レベルのイベントを処理し、イベントが発生した文書がカスタマイズした文書かどうかを判断するための追加のコードを記述する必要があります。ホスト項目では、個別のドキュメントのイベントが扱いやすくなるように、これらのイベントがドキュメント レベルで発生します。ホスト項目を生成し、そのホスト項目のイベントを処理できます。

ネイティブな Word オブジェクトの使用例

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;
    }
}

ホスト項目の使用例

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

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

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

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

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

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

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

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

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

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

処理手順

概念