Word 文書や実行時に VSTO のアドインの Excel ブックを拡張します。Extend Word documents and Excel workbooks in VSTO add-ins at runtime

VSTO アドインを利用すれば、Word 文書と Excel ブックを次のようにカスタマイズできます。You can use a VSTO Add-in to customize Word documents and Excel workbooks in the following ways:

  • 開いている文書またはブックに管理されているコントロールを追加します。Add managed controls to any open document or worksheet.

  • Excel ワークシートの既存のリスト オブジェクトを、イベントを公開し、Windows フォーム データ バインディング モデルでデータにバインディングできる拡張 ListObject に変換します。Convert an existing list object on an Excel worksheet to an extended ListObject that exposes events and can be bound to data by using the Windows Forms data binding model.

  • 特定の文書、ブック、ワークシートに対して Word と Excel が公開するアプリケーションレベル イベントにアクセスします。Access application-level events that are exposed by Word and Excel for specific documents, workbooks, and worksheets.

    この機能を使用するには、ドキュメントまたはブックを拡張する実行時にオブジェクトを生成します。To use this functionality, you generate an object at runtime that extends the document or workbook.

    適用対象: この記事の情報は、次のアプリケーション用の VSTO アドイン プロジェクトに適用されます。Excel および Word です。Applies to: The information in this article applies to VSTO Add-in projects for the following applications: Excel and Word. 詳細については、「Office アプリケーションおよびプロジェクトの種類で使用できる機能」を参照してください。For more information, see Features available by Office application and project type.

VSTO アドインで拡張されたオブジェクトを生成します。Generate extended objects in VSTO Add-ins

拡張オブジェクト は Word または Excel オブジェクト モデルにネイティブで存在するオブジェクト ( ネイティブ Office オブジェクト) に機能を追加する Visual Studio Tools for Office Runtime が提供する種類のインスタンスです。Extended objects are instances of types provided by the Visual Studio Tools for Office runtime that add functionality to objects that exist natively in the Word or Excel object models (called native Office objects). Word または Excel オブジェクトの拡張オブジェクトを生成するにはGetVstoObject メソッドを使用します。To generate an extended object for a Word or Excel object, use the GetVstoObject method. 最初に呼び出したとき、GetVstoObjectメソッドを指定した Word または Excel のオブジェクトを指定したオブジェクトを拡張する新しいオブジェクトが返されます。The first time you call the GetVstoObject method for a specified Word or Excel object, it returns a new object that extends the specified object. このメソッドを呼び出し、同じ Word または Excel を指定するたびに、同じ拡張オブジェクトが返されます。Each time you call the method and specify the same Word or Excel object, it returns the same extended object.

拡張オブジェクトの種類にはネイティブ Office オブジェクトの種類と同じ名前が与えられますが、この種類は Microsoft.Office.Tools.Excel または Microsoft.Office.Tools.Word 名前空間で定義されます。The type of the extended object has the same name as the type of the native Office object, but the type is defined in the Microsoft.Office.Tools.Excel or Microsoft.Office.Tools.Word namespace. たとえば、GetVstoObject メソッドを呼び出し、Document オブジェクトを拡張した場合、このメソッドは Document オブジェクトを返します。For example, if you call the GetVstoObject method to extend a Document object, the method returns a Document object.

GetVstoObject メソッドは主に VSTO アドイン プロジェクトで使用するためのものです。The GetVstoObject methods are intended to be used primarily in VSTO Add-in projects. ドキュメントレベル プロジェクトでこれらのメソッドを使用することもできますが、動作が異なり、用途が少なくなります。You can also use these methods in document-level projects, but they behave differently, and have fewer uses.

特定のネイティブ Office オブジェクトに対して拡張オブジェクトが既に生成されているかどうかを確認するには、HasVstoObject メソッドを使用します。To determine whether an extended object has already been generated for a particular native Office object, use the HasVstoObject method. 詳細については、次を参照してください。 Office オブジェクトが拡張されているかどうかを判断します。For more information, see Determine whether an Office object has been extended.

ホスト項目を生成します。Generate host items

使用する場合、GetVstoObjectドキュメント レベルのオブジェクトを拡張 (つまり、 WorkbookWorksheet、またはDocument)、返されたオブジェクトが呼び出されます、ホスト項目When you use the GetVstoObject to extend a document-level object (that is, a Workbook, Worksheet, or Document), the returned object is called a host item. ホスト項目は、他の拡張されたオブジェクトやコントロールなど、他のオブジェクトを含めることができる種類です。A host item is a type that can contain other objects, including other extended objects and controls. Word または Excel プライマリ相互運用機能アセンブリの対応する種類と似ていますが、機能が多くなっています。It resembles the corresponding type in the Word or Excel primary interop assembly, but it has additional features. ホスト項目の詳細については、次を参照してください。ホスト項目とホスト コントロールの概要します。For more information about host items, see Host items and host controls overview.

ホスト項目を生成したら、それを利用して管理されているコントロールを文書、ブック、ワークシートに追加できます。After you generate a host item, you can use it to add managed controls to the document, workbook, or worksheet. 詳細については、次を参照してください。マネージ文書やワークシートにコントロールを追加します。For more information, see Add managed controls to documents and worksheets.

Word 文書のホスト項目を生成するにはTo generate a host item for a Word document

  • 次のコード例はアクティブな文書のホスト項目を生成する方法を示しています。The following code example demonstrates how to generate a host item for the active document.

    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 If
    
    if (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);
    }
    

Excel ブックのホスト項目を生成するにはTo generate a host item for an Excel workbook

  • 次のコード例はアクティブなブックのホスト項目を生成する方法を示しています。The following code example demonstrates how to generate a host item for the active workbook.

    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 If
    
    Microsoft.Office.Interop.Excel.Workbook nativeWorkbook = 
        Globals.ThisAddIn.Application.ActiveWorkbook;
    if (nativeWorkbook != null)
    {
        Microsoft.Office.Tools.Excel.Workbook vstoWorkbook = 
            Globals.Factory.GetVstoObject(nativeWorkbook);
    }
    

Excel ワークシートのホスト項目を生成するにはTo generate a host item for an Excel worksheet

  • 次のコード例はプロジェクトのアクティブなワークシートのホスト項目を生成する方法を示しています。The following code example demonstrates how to generate a host item for the active worksheet in a project.

    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 If
    
    Microsoft.Office.Interop.Excel.Worksheet nativeWorksheet =
        Globals.ThisAddIn.Application.ActiveSheet;
    if (nativeWorksheet != null)
    {
        Microsoft.Office.Tools.Excel.Worksheet vstoSheet = 
            Globals.Factory.GetVstoObject(nativeWorksheet);
    }
    

ListObject ホスト コントロールを生成します。Generate ListObject host controls

GetVstoObject メソッドを利用して ListObject を拡張すると、このメソッドは ListObject を返します。When you use the GetVstoObject method to extend a ListObject, the method returns a ListObject. ListObjectが元の機能をすべてListObjectします。The ListObject has all of the features of the original ListObject. 追加の機能を持つまた、Windows フォーム データ バインディング モデルを使用してデータにバインドできます。It also has additional functionality and can be bound to data by using the Windows Forms data binding model. 詳細については、次を参照してください。 ListObject コントロールします。For more information, see ListObject control.

ListObject のホスト コントロールを生成するにはTo generate a host control for a ListObject

  • 次のコード例はプロジェクトのアクティブなワークシートの最初の ListObject に対して ListObject を生成する方法を示しています。The following code example demonstrates how to generate a ListObject for the first ListObject in the active worksheet in a project.

    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 If
    
    Microsoft.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);
    }
    

文書やワークシートにマネージ コントロールを追加します。Add managed controls to documents and worksheets

Document または Worksheetを生成したら、これらの拡張オブジェクトが表す文書またはワークシートにコントロールを追加できます。After you generate a Document or Worksheet, you can add controls to the document or worksheet that these extended objects represent. コントロールを追加するには、使用、Controlsのプロパティ、DocumentまたはWorksheetします。To add controls, use the Controls property of the Document or Worksheet. 詳細については、次を参照してください。実行時に Office ドキュメントにコントロールを追加します。For more information, see Add controls to Office documents at runtime.

Windows フォーム コントロールまたは ホスト コントロールを追加できます。You can add Windows Forms controls or host controls. ホスト コントロールは Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime により提供されるコントロールであり、Word または Excel プライマリ相互運用機能アセンブリのそれに対応するコントロールをラップします。A host control is a control provided by the Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime that wraps a corresponding control in the Word or Excel primary interop assembly. ホスト コントロールは、すべての基になるネイティブ Office オブジェクトの動作を公開します。A host control exposes all of the behavior of the underlying native Office object. イベントを発生させ、Windows フォーム データ バインディング モデルを使用してデータにバインドできます。It also raises events and can be bound to data by using the Windows Forms data binding model. 詳細については、次を参照してください。ホスト項目とホスト コントロールの概要します。For more information, see Host items and host controls overview.

Note

VSTO アドインを利用し、 XmlMappedRange コントロールをワークシートに、 XMLNode または XMLNodes コントロールを文書に追加することはできません。You cannot add a XmlMappedRange control to a worksheet, or a XMLNode or XMLNodes control to a document, by using a VSTO Add-in. これらのホスト コントロールをプログラミングで追加することはできません。These host controls cannot be added programmatically. 詳細については、次を参照してください。ホスト項目とホスト コントロールのプログラム上の制限事項します。For more information, see Programmatic limitations of host items and host controls.

永続化し、コントロールを削除Persist and remove controls

管理されているコントロールを文書またはワークシートに追加するとき、文書を保存し、閉じても、コントロールは保持されません。When you add managed controls to a document or worksheet, the controls are not persisted when the document is saved and then closed. 基礎となるネイティブ Office オブジェクトだけが残るようにすべてのホスト コントロールが削除されます。All host controls are removed so that only the underlying native Office objects are left behind. たとえば、 ListObjectListObjectになります。For example, a ListObject becomes a ListObject. すべての Windows フォーム コントロールも削除されますが、ActiveX ラッパーは文書に残ります。All Windows Forms controls are also removed, but ActiveX wrappers for the controls are left behind in the document. コントロールを消去するか、文書を次回開いたときにコントロールを再作成するには、VSTO アドインにコードを追加する必要があります。You must include code in your VSTO Add-in to clean up the controls, or to recreate the controls the next time the document is opened. 詳細については、次を参照してください。 Office ドキュメントでのダイナミック コントロールを永続化します。For more information, see Persist dynamic controls in Office documents.

文書やブックのアクセスのアプリケーション レベルのイベントAccess application-level events on documents and workbooks

ネイティブの Word または Excel オブジェクト モデルの一部の文書、ブック、ワークシート イベントはアプリケーション レベルでのみ発生します。Some document, workbook, and worksheet events in the native Word and Excel object models are raised only at the application level. たとえば、 DocumentBeforeSave イベントは文書を Word で開いたときに発生しますが、このイベントは Application クラスではなく、 Document クラスに定義されています。For example, the DocumentBeforeSave event is raised when a document is opened in Word, but this event is defined in the Application class, rather than the Document class.

VSTO アドインでネイティブ Office オブジェクトを使用するとき、これらのアプリケーションレベル イベントを処理し、イベントを発生された文書が自分でカスタマイズした文書であるかどうかを判断する追加コードを記述する必要があります。When you use only native Office objects in your VSTO Add-in, you must handle these application-level events and then write additional code to determine whether the document that raised the event is one that you have customized. ホスト項目は文書レベルでこれらのイベントを提供します。そのため、特定の文書のイベントを簡単に処理できます。Host items provide these events at the document level, so that it is easier to handle the events for a specific document. ホスト項目を生成し、そのホスト項目のイベントを処理できます。You can generate a host item and then handle the event for that host item.

ネイティブな Word オブジェクトを使用する例Example that uses native Word objects

次のコード例は Word 文書のアプリケーションレベル イベントの処理方法を示しています。The following code example demonstrates how to handle an application-level event for Word documents. CreateDocument メソッドは新しい文書を作成し、その文書が保存されないようにする DocumentBeforeSave イベント ハンドラーを定義します。The CreateDocument method creates a new document, and then defines a DocumentBeforeSave event handler that prevents this document from being saved. イベントは、アプリケーション レベルのイベントの発生する、Applicationオブジェクト、およびイベント ハンドラーを比較する必要があります、Docパラメーター、document1オブジェクトかどうかをdocument1保存されたドキュメントを表します。The event is an application-level event that is raised for the Application object, and the event handler must compare the Doc parameter with the document1 object to determine if document1 represents the saved document.

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

ホスト項目を使用する例Examples that use a host item

次のコード例では、 BeforeSave ホスト項目の Document イベントを処理することでこのプロセスを簡略化しています。The following code examples simplify this process by handling the BeforeSave event of a Document host item. CreateDocument2メソッドはこれらの例では、生成、Documentまで、document2オブジェクト、し、定義、BeforeSaveドキュメントが保存されるようにするイベント ハンドラー。The CreateDocument2 method in these examples generates a Document that extends the document2 object, and then it defines a BeforeSave event handler that prevents the document from being saved. イベント ハンドラーは場合にのみと呼ばれるdocument2は保存され、保存を取り消すことができます保存された文書を確認する追加の作業を実行しなくても動作します。The event handler is called only when document2 is saved, and can cancel the save action without doing any extra work to verify which document was saved.

次のコード例はこの作業を示しています。The following code example demonstrates this task.

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

Office オブジェクトが拡張されているかどうかを判断します。Determine whether an Office object has been extended

特定のネイティブ Office オブジェクトに対して拡張オブジェクトが既に生成されているかどうかを確認するには、HasVstoObject メソッドを使用します。To determine whether an extended object has already been generated for a particular native Office object, use the HasVstoObject method. このメソッドが戻るtrue拡張オブジェクトが既に生成されている場合。This method returns true if an extended object has already been generated.

Globals.Factory.HasVstoMethod メソッドを使用します。Use the Globals.Factory.HasVstoMethod method. 拡張オブジェクトに対してテストするネイティブの Word または Excel オブジェクト ( DocumentWorksheetなど) を渡します。Pass in the native Word or Excel object, such as a Document or Worksheet, that you want to test for an extended object.

HasVstoObject メソッドは、指定した Office オブジェクトに拡張オブジェクトがある場合にのみ、コードの実行で便利です。The HasVstoObject method is useful when you want to run code only when a specified Office object has an extended object. 処理する Word VSTO アドインがある場合など、DocumentBeforeSaveイベントが保存されるまで、マネージ コントロールをドキュメントから削除を使用して、HasVstoObject文書が拡張されているかどうかを判断するメソッド。For example, if you have a Word VSTO Add-in that handles the DocumentBeforeSave event to remove managed controls from a document before it's saved, use the HasVstoObject method to determine whether the document has been extended. 文書が拡張されていない場合は、コントロール、管理があることはできませんし、イベント ハンドラーがドキュメント上のコントロールをクリーンアップしようとしないで返すことができます。If the document has not been extended, it cannot have managed controls, and the event handler can return without trying to clean up controls on the document.

関連項目See also