実行時に VSTO アドインの Word 文書と Excel ブックを拡張するExtend Word documents and Excel workbooks in VSTO add-ins at run time

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 run time 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. 指定された Word またGetVstoObjectは 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使用してドキュメントレベルのオブジェクト ( Worksheet Workbookつまり、、、または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 run time.

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オブジェクトに対して発生するアプリケーションレベルのイベントです。イベントハンドラーは、パラメーター document1Docオブジェクトと比較して、が保存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. たとえば、イベントを処理しDocumentBeforeSaveて、保存前にドキュメントからマネージコントロールを削除する Word VSTO アドインがある場合は、 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