ホスト項目とホスト コントロールのプログラム上の制限事項

それぞれのホスト項目やホスト コントロールは、それに対応するネイティブな Microsoft Office Word オブジェクトや Microsoft Office Excel オブジェクトと同様に動作するように設計され、さらに追加の機能が備えられています。 ただし、ホスト項目やホスト コントロールと、ネイティブな Office オブジェクトの実行時の動作には、基本的な相違点がいくつかあります。

ホスト項目とホスト コントロールの概要については、「ホスト項目とホスト コントロールの概要」を参照してください。

対象: このトピックの情報は、Excel および Word のドキュメントレベルのプロジェクトおよび VSTO アドインのプロジェクトに適用されます。 詳細については、「Office アプリケーションおよびプロジェクトの種類別の使用可能な機能」を参照してください。

プログラムによってホスト項目を作成する

Word または Excel オブジェクト モデルを使用することで、文書、ブック、またはワークシートをプログラムで実行時に作成したり、開いたりする場合、その項目はホスト項目ではありません。 その新しいオブジェクトは、ネイティブな Office オブジェクトです。 たとえば、 Add メソッドを使用して実行時に新しい Word 文書を作成すると、その文書は、 Document ホスト項目ではなく、ネイティブな Document オブジェクトになります。 同様に、 Add メソッドを使用して実行時に新しいワークシートを作成すると、 Worksheet ホスト項目ではなく、ネイティブな Worksheet オブジェクトが作成されます。

ドキュメント レベルのプロジェクトでは、実行時にホスト項目を作成することはできません。 ドキュメント レベルのプロジェクトでは、デザイン時にのみ、ホスト項目を作成できます 詳細については、「Document ホスト項目」、「Workbook ホスト項目」、「Worksheet ホスト項目」を参照してください。

VSTO アドイン プロジェクトでは、実行時に DocumentWorkbook、または Worksheet のホスト項目を作成できます。 詳細については、「実行時に VSTO アドインの Word 文書と Excel ブックを拡張する」を参照してください。

プログラムによってホスト コントロールを作成する

実行時に、プログラムによって、 Document ホスト項目または Worksheet ホスト項目にホスト コントロールを追加できます。 詳細については、「実行時に Office 文書にコントロールを追加する」を参照してください。

ネイティブな DocumentWorksheetに、ホスト コントロールを追加することはできません。

Note

ホスト コントロールの XmlMappedRangeXMLNode、および XMLNodesは、プログラムによってワークシートや文書に追加することはできません。

ホスト項目、ホスト コントロール、ネイティブな Office オブジェクトの型の相違点について

それぞれのホスト項目やホスト コントロールには、基になるネイティブな Microsoft Office Word オブジェクトまたは Microsoft Office Excel オブジェクトがあります。 基になるオブジェクトには、ホスト項目またはホスト コントロールの InnerObject プロパティを使用してアクセスできます。 ただし、ネイティブな Office オブジェクトをそれに対応するホスト項目またはホスト コントロールにキャストする方法はありません。 ネイティブな Office オブジェクトをホスト項目またはホスト コントロールの型にキャストしようとすると、 InvalidCastException がスローされます。

ホスト項目とホスト コントロールの型、および基になるネイティブな Office オブジェクトの違いがコードに影響を及ぼす可能性について、いくつかのシナリオを挙げて説明します。

メソッドとプロパティにホスト コントロールを渡す

Word では、パラメーターとしてネイティブな Word オブジェクトを要求するメソッドまたはプロパティに、ホスト コントロールを渡すことはできません。 基になるネイティブな Word オブジェクトを返すには、ホスト コントロールの InnerObject プロパティを使用する必要があります。 たとえば、メソッドに Bookmark オブジェクトを渡す場合は、 InnerObject ホスト コントロールの Bookmark プロパティを渡します。

Excel では、メソッドまたはプロパティが基になる Excel オブジェクトを要求するときに、そのメソッドまたはプロパティにホスト コントロールを渡す場合は、ホスト コントロールの InnerObject のプロパティを使用する必要があります。

次に示す例では、 NamedRange コントロールを作成して、そのコントロールを AutoFill メソッドに渡しています。 このコードでは、名前付き範囲の InnerObject プロパティを使用して、 Range メソッドが要求する、基になる Office の AutoFill を返します。

this.Range["A1"].Value2 = "Monday";
this.Range["A2"].Value2 = "Tuesday";

Microsoft.Office.Tools.Excel.NamedRange dayRange = 
    this.Controls.AddNamedRange(this.Range["A1", "A7"], "dayRange");
this.Range["A1", "A2"].AutoFill(dayRange.InnerObject, Excel.XlAutoFillType.xlFillDays);

ネイティブな Office のメソッドとプロパティの戻り値の型

ホスト項目のほとんどのメソッドとプロパティは、そのホスト項目の基になっているネイティブな Office オブジェクトを返します。 たとえば、Excel の Parent ホスト コントロールの NamedRange プロパティは、 Worksheet ホスト項目ではなく Worksheet オブジェクトを返します。 同様に、Word の Parent ホスト コントロールの RichTextContentControl プロパティは、 Document ホスト項目ではなく Document オブジェクトを返します。

ホスト コントロールのコレクションにアクセスする

Visual Studio Tools for Office ランタイムには、ホスト コントロールの種類ごとの個別のコレクションは用意されていません。 その代わりに、ホスト項目の Controls プロパティを使用して、文書またはワークシートのすべてのマネージド コントロール (ホスト コントロールと Windows フォーム コントロールの両方) を反復処理し、目的とする型のホスト コントロールと一致する項目を検索します。 次に示すコード例では、Word 文書の各コントロールを調べ、そのコントロールが Bookmarkかどうかを確認しています。

foreach (object targetControl in this.Controls)
{
    Microsoft.Office.Tools.Word.Bookmark bookMark =
        targetControl as Microsoft.Office.Tools.Word.Bookmark;

    if (bookMark != null)
    {
        // Do some work with the bookmark here.
    }
}

ホスト項目の Controls プロパティの詳細については、「実行時に Office 文書にコントロールを追加する」を参照してください。

Word と Excel オブジェクト モデルには、文書とワークシートのネイティブ コントロールのコレクションを公開するプロパティが含まれています。 これらのプロパティを使用してマネージド コントロールにアクセスすることはできません。 たとえば、 BookmarkBookmarks プロパティや DocumentBookmarks プロパティを使用して、文書内の各 Documentホスト コントロールを列挙することはできません。 これらのプロパティには、文書内の Bookmark コントロールのみが含まれています。つまり、文書内の Bookmark ホスト コントロールは含まれていないということです。