ホスト項目とホスト コントロールの概要Host items and host controls overview

ホスト項目とホスト コントロールは、Visual Studio の Office 開発ツールを使用して作成される Office ソリューションのプログラミング モデルを提供する助けとなる型です。Host items and host controls are types that help provide the programming model for Office solutions that are created by using the Office development tools in Visual Studio. ホスト項目とホスト コントロールは、Microsoft Office Word および Microsoft Office Excel の COM ベースのオブジェクト モデルとの対話を、Windows フォーム コントロールなどのマネージド オブジェクトとの対話と似たものにします。Host items and host controls make interacting with the object models of Microsoft Office Word and Microsoft Office Excel, which are based on COM, more like interacting with managed objects such as Windows Forms controls.

適用対象: このトピックの情報は、ドキュメントに適用されます-レベルのプロジェクトおよび VSTO 追加-Excel および Word プロジェクトでします。Applies to: The information in this topic applies to document-level projects and VSTO Add-in projects for Excel and Word. 詳細については、「Office アプリケーションおよびプロジェクトの種類で使用できる機能」を参照してください。For more information, see Features available by Office application and project type.

ホスト項目Host items

ホスト項目は、Office プロジェクトでオブジェクト モデルの階層構造の最上位にある型です。Host items are types that are at the top of object model hierarchies in Office projects. Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime は、Word ソリューションおよび Excel ソリューションに対して次のホスト項目を定義します:The Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime defines the following host items for Word and Excel solutions:

  • Document

  • Workbook

  • Worksheet

  • ChartSheet

    これらの型はそれぞれが、Word または Excel のオブジェクト モデルにネイティブに存在する ネイティブ Office オブジェクトと呼ばれるオブジェクトを拡張します。Each of these types extends an object that exists natively in the Word or Excel object model, called a native Office object. たとえば、 Document ホスト項目は、Word のプライマリ相互運用機能アセンブリに定義されている Document オブジェクトを拡張します。For example, the Document host item extends the Document object, which is defined in the primary interop assembly for Word.

    ホスト項目は、一般に、対応する Office オブジェクトと同じ基本機能を備えていますが、さらに次の機能を備えています:Host items generally have the same base functionality as the corresponding Office objects, but are enhanced with the following features:

  • ホスト コントロールや Windows フォーム コントロールなどのマネージド コントロールをホストする機能。The ability to host managed controls, including host controls and Windows Forms controls.

  • 豊富なイベント モデル。Richer event models. ネイティブの Word または Excel オブジェクト モデルの一部の文書、ブック、ワークシート イベントはアプリケーション レベルでのみ発生します。Some document, workbook, and worksheet events in the native Word and Excel object models are raised only at the application level. ホスト項目は文書レベルでこれらのイベントを提供します。そのため、特定の文書のイベントを簡単に処理できます。Host items provide these events at the document level, so that it is easier to handle the events for a specific document.

ドキュメント レベルのプロジェクトでのホスト項目を理解します。Understand host items in document-level projects

ドキュメント レベルのプロジェクトでは、ホスト項目はコードのエントリ ポイントを提供し、ソリューションの開発に役立つデザイナーを備えています。In document-level projects, host items provide an entry point for your code, and they have designers that help you develop your solution.

DocumentWorksheet のホスト項目は、Windows フォーム デザイナーに似た、文書やワークシートを視覚的に表現する関連デザイナーを備えています。The Document and Worksheet host items have associated designers that are the visual representation of the document or worksheet, like a Windows Forms designer. このデザイナーを使用して、Word や Excel で文書やワークシートのコンテンツを変更したり、デザイン サーフェイスにコントロールをドラッグしたりすることができます。You can use this designer to modify the content of the document or worksheet directly in Word or Excel, and to drag controls onto the design surface. 詳細については、次を参照してください。 Document ホスト項目Worksheet ホスト項目します。For more information, see Document host item and Worksheet host item.

Workbook ホスト項目は、ユーザー インターフェイスのあるコントロールのコンテナーとしては動作しませんThe Workbook host item does not act as a container for controls that have a user interface. 代わりに、このホスト項目のデザイナーはコンポーネント トレイとして機能し、ユーザーはこのデザイナーを使用して DataSetなどのコンポーネントをデザイン サーフェイスにドラッグできます。Instead, the designer for this host item functions as a component tray, which enables you to drag a component, such as a DataSet, onto its design surface. 詳細については、次を参照してください。 Workbook ホスト項目します。For more information, see Workbook host item.

ドキュメント レベルのプロジェクトでは、ホスト項目をプログラムで作成することはできません。Host items cannot be created programmatically in document-level projects. その代わり、デザイン時に Visual Studio によってプロジェクトに自動的に生成される ThisDocumentThisWorkbook、または Sheetn クラスを使用します。Instead, use the ThisDocument, ThisWorkbook, or Sheetn classes that Visual Studio automatically generates in your project at design time. 生成されるこれらのクラスは、ホスト項目から派生するもので、コードのエントリ ポイントを提供します。These generated classes derive from the host items, and they provide an entry point for your code. 詳細については、次を参照してください。ホスト項目とホスト コントロールのプログラム上の制限事項します。For more information, see Programmatic limitations of host items and host controls.

VSTO アドイン プロジェクトのホスト項目を理解します。Understand host items in VSTO Add-in projects

VSTO アドインを作成するときにありませんアクセス、ホスト項目に既定では。When you create a VSTO Add-in, you do not have access to any host items by default. ただし、生成DocumentWorkbook、およびWorksheetWord と実行時に Excel VSTO アドイン内の項目をホストします。However, you can generate Document, Workbook, and Worksheet host items in Word and Excel VSTO Add-ins at runtime.

ホスト項目を生成すると、文書にコントロールを追加するなどのタスクを実行できます。After you generate a host item, you can perform tasks such as adding controls to documents. 詳細については、次を参照してください。拡張 Word 文書や Excel ブックを実行時に VSTO アドインでします。For more information, see Extend Word documents and Excel workbooks in VSTO Add-ins at runtime.

ホスト コントロールHost controls

ホスト コントロールは、Word や Excel のオブジェクト モデルで、Microsoft.Office.Interop.Word.ContentControlRange オブジェクトなどのさまざまなユーザー インターフェイス (UI) オブジェクトを拡張します。Host controls extend various user interface (UI) objects in the Word and Excel object models, such as Microsoft.Office.Interop.Word.ContentControl and Range objects.

Excel プロジェクトで使用できるホスト コントロールを次に示します:The following host controls are available for Excel projects:

  • グラフ コントロールChart control

  • ListObject コントロールListObject control

  • NamedRange コントロールNamedRange control

  • XmlMappedRange コントロールXmlMappedRange control

    Word プロジェクトで使用できるホスト コントロールを次に示します:The following host controls are available for Word projects:

  • Bookmark コントロールBookmark control

  • コンテンツ コントロールContent controls

  • XMLNode コントロールXMLNode control

  • XMLNodes コントロールXMLNodes control

    Office ドキュメントに追加されたホスト コントロールは、ネイティブな Office オブジェクトのように動作しますが、ホスト コントロールには、イベントやデータ バインディング機能を含む追加の機能があります。Host controls that are added to Office documents behave like the native Office objects; however, host controls have additional functionality, including events and data-binding capabilities. たとえば、Excel 内のネイティブな Range オブジェクトのイベントをキャプチャするには、最初にワークシートの変更イベントを処理する必要があります。For example, when you want to capture the events of a native Range object in Excel, you must first handle the change event of the worksheet. 次に、変更が Range内で発生したかどうかを判断する必要があります。Then you must determine whether the change occurred within the Range. 一方、 NamedRange ホスト コントロールには、直接処理できる Change イベントがあります。In contrast, the NamedRange host control has a Change event that you can handle directly.

    ホスト項目とホスト コントロール間のリレーションシップは、Windows フォームおよび Windows フォーム コントロールの間のリレーションシップに似ています。The relationship between a host item and host controls is similar to the relationship between a Windows Form and Windows Forms controls. Windows フォームにテキスト ボックス コントロールを配置するのと同じように、 NamedRange ホスト項目に Worksheet コントロールを配置します。Just as you would place a text box control on a Windows Form, you place a NamedRange control on a Worksheet host item. 次の図は、ホスト項目とホスト コントロールの関係を示しています。The following illustration shows the relationship between host items and host controls.

    ホスト項目とホスト コントロールの間のリレーションシップRelationship between host items and host controls

    また、Windows フォーム コントロールを Word および Excel の文書領域に直接追加することによって、Office ソリューションで Windows フォーム コントロールを使用できます。You can also use Windows Forms controls in your Office solutions by adding them directly to the Word and Excel document surface. 詳細については、次を参照してください。 Windows フォーム コントロールの Office ドキュメントの概要します。For more information, see Windows Forms controls on Office documents overview.

Note

Word サブ文書へのホスト コントロールおよび Windows フォーム コントロールの追加はサポートされていません。Adding host controls or Windows Forms controls to a Word subdocument is not supported.

ホスト コントロールをドキュメントに追加します。Add host controls to your documents

ドキュメント レベルのプロジェクトでは、次の方法を使用して、デザイン時に Word 文書や Excel ワークシートにホスト コントロールを追加できます。In document-level projects, you can add host controls to your Word documents or Excel worksheets at design time in the following ways:

ホスト コントロールの名前Name host controls

ツールボックス から文書にホスト コントロールをドラッグすると、コントロールには自動的にコントロールの型と末尾の増分番号で構成される名前が付けられます。When you drag a host control from the Toolbox to your document, the control is automatically named using the control type with an incremental number at the end. たとえば、ブックマークには bookmark1bookmark2などの名前が付けられます。For example, bookmarks are named bookmark1, bookmark2, and so on. Word または Excel のネイティブ機能を使用してコントロールを追加する場合は、コントロールの作成時に特定の名前を指定できます。If you use the native functionality of Word or Excel to add the control, you can give it a specific name at the time that you create it. [プロパティ] ウィンドウで、 [名前] プロパティの値を変更してコントロールの名前を変更することもできます。You can also rename your controls by changing the value of the Name property in the Properties window.

Note

ホスト コントロールの名前に予約語は使用できません。You cannot use reserved words to name host controls. たとえば、 NamedRange コントロールをワークシートに追加し、名前を Systemに変更すると、プロジェクトをビルドするときにエラーが発生します。For example, if you add a NamedRange control to a worksheet and change the name to System, errors occur when you build the project.

ホスト コントロールを削除します。Delete host controls

ドキュメント レベルのプロジェクトでコントロールを削除できますホスト デザイン時に、Excel ワークシートまたは Word 文書にコントロールを選択し、キーを押して、削除キー。In document-level projects, you can delete host controls at design time by selecting the control on the Excel worksheet or Word document and pressing the Delete key. ただし、 コントロールを削除するには、Excel の [名前の定義] NamedRange ダイアログ ボックスを使用する必要があります。However, you must use the Define Name dialog box in Excel to delete NamedRange controls.

デザイン時にホスト コントロールをドキュメントに追加する場合をする必要があるために削除できません、プログラムで実行時に、次回のコードでは、コントロールを使用しようとする、例外がスローされます。If you add a host control to a document at design time, you should not remove it programmatically at runtime because the next time you try to use the control in code, an exception is thrown. Deleteホスト コントロールのメソッドでは、実行時にドキュメントに追加されるホスト コントロールのみ削除します。The Delete method of a host control only removes host controls that are added to the document at runtime. デザイン時に作成されたホスト コントロールの Delete メソッドを呼び出すと、例外がスローされます。If you call the Delete method of a host control that was created at design time, an exception is thrown.

たとえば、 DeleteNamedRange メソッドは、プログラムによってワークシートに追加された場合のみ (動的に作成されたホスト コントロールと呼ばれます)、 NamedRange を正しく削除します。For example, the Delete method of a NamedRange only successfully deletes the NamedRange if it was programmatically added to the worksheet, which is known as creating host controls dynamically. 動的に作成されたホスト コントロールは、コントロール名を Remove プロパティまたは Controls プロパティの Controls メソッドに渡すことによっても削除できます。Dynamically created host controls can also be removed by passing the control name to the Remove method of the Controls or Controls property. 詳細については、次を参照してください。実行時に Office ドキュメントにコントロールを追加します。For more information, see Add controls to Office documents at runtime.

エンドユーザーは、実行時にドキュメントからホスト コントロールを削除する、予期しない方法で、ソリューションが失敗する可能性があります。If end users delete a host control from the document at runtime, the solution might fail in unexpected ways. Word および Excel のドキュメント保護機能を使用して、ホスト コントロールが削除されないように保護できます。You can use the document protection features in Word and Excel to protect the host controls from being deleted. 詳細については、次を参照してください。 Office 開発のサンプルとチュートリアルします。For more information, see Office development samples and walkthroughs.

Note

文書やワークシートの Shutdown イベント ハンドラーでは、コントロールをプログラムで削除しないでください。Do not programmatically remove controls during the Shutdown event handler of the document or worksheet. Shutdown イベントが発生すると、UI 要素は使用できなくなります。The UI elements are no longer available when the Shutdown event occurs. アプリケーションが終了する前にコントロールを削除する場合は、 BeforeCloseBeforeSaveなどの別のイベント ハンドラーにコードを追加してください。If you want to remove controls before the application closes, add your code to another event handler such as BeforeClose or BeforeSave.

ホスト コントロールのイベントに対してプログラムProgram against host control events

ホスト コントロールが Office オブジェクトを拡張する方法の 1 つに、イベントの追加が挙げられます。One way that host controls extend Office objects is by adding events. たとえば、Excel の Range オブジェクトと Word の Bookmark オブジェクトはイベントを持ちませんが、 Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime では、プログラミング可能なイベントを追加することによってこれらのオブジェクトを拡張します。For example, the Range object in Excel and Bookmark object in Word do not have events, but the Visual Studio Tools for Office RuntimeVisual Studio Tools for Office runtime extends these objects by adding programmable events. Windows フォームのコントロールのイベントにアクセスするのと同じ方法で、これらのイベントにアクセスし、コーディングすることができます。Visual Basic ではイベント ドロップダウン リストを使用し、C# ではイベント プロパティ ページを使用します。You can access and code against these events the same way you access events of controls on Windows Forms: through the event drop-down list in Visual Basic and the event property page in C#. 詳細については、「チュートリアル:NamedRange コントロールのイベントに対してプログラムします。For more information, see Walkthrough: Program against events of a NamedRange control.

Note

Excel の EnableEvents オブジェクトの Application プロパティを falseと呼ばれるオブジェクトを拡張します。You should not set the EnableEvents property of the Application object in Excel to false. このプロパティを false に設定すると、ホスト コントロールのイベントを含む、すべてのイベントが Excel で発生しなくなります。Setting this property to false prevents Excel from raising any events, including the events of host controls.

関連項目See also