実行時に VSTO アドインで Word 文書と Excel ブックを拡張する

  • [アーティクル]

VSTO アドインを利用すれば、Word 文書と Excel ブックを次のようにカスタマイズできます。

  • 開いている文書またはブックに管理されているコントロールを追加します。

  • Excel ワークシートの既存のリスト オブジェクトを、イベントを公開し、Windows フォーム データ バインディング モデルでデータにバインディングできる拡張 ListObject に変換します。

  • 特定の文書、ブック、ワークシートに対して Word と Excel が公開するアプリケーションレベル イベントにアクセスします。

    この機能を使用するには、文書またはブックを拡張するオブジェクトを実行時に生成します。

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

VSTO アドインで拡張オブジェクトを生成する

拡張オブジェクト は Word または Excel オブジェクト モデルにネイティブで存在するオブジェクト ( ネイティブ Office オブジェクト) に機能を追加する Visual Studio Tools for Office Runtime が提供する種類のインスタンスです。 Word または Excel オブジェクトの拡張オブジェクトを生成するにはGetVstoObject メソッドを使用します。 指定した Word または Excel オブジェクトに対して GetVstoObject メソッドを初めて呼び出すと、指定したオブジェクトを拡張する新しいオブジェクトが返されます。 このメソッドを呼び出し、同じ Word または Excel を指定するたびに、同じ拡張オブジェクトが返されます。

拡張オブジェクトの種類にはネイティブ Office オブジェクトの種類と同じ名前が与えられますが、この種類は Microsoft.Office.Tools.Excel または Microsoft.Office.Tools.Word 名前空間で定義されます。 たとえば、GetVstoObject メソッドを呼び出し、Document オブジェクトを拡張した場合、このメソッドは Document オブジェクトを返します。

GetVstoObject メソッドは主に VSTO アドイン プロジェクトで使用するためのものです。 ドキュメントレベル プロジェクトでこれらのメソッドを使用することもできますが、動作が異なり、用途が少なくなります。

特定のネイティブ Office オブジェクトに対して拡張オブジェクトが既に生成されているかどうかを確認するには、HasVstoObject メソッドを使用します。 詳しくは、「Office オブジェクトが拡張されているかどうかを判断する」をご覧ください。

ホスト項目を生成する

GetVstoObject を使用してドキュメント レベルのオブジェクト (つまり、Workbook、Worksheet、Document) を拡張するとき、返されるオブジェクトは "ホスト項目" と呼ばれます。 ホスト項目は、他の拡張されたオブジェクトやコントロールなど、他のオブジェクトを含めることができる種類です。 Word または Excel プライマリ相互運用機能アセンブリの対応する種類と似ていますが、機能が多くなっています。 ホスト項目の詳細については、「ホスト項目とホスト コントロールの概要」を参照してください。

ホスト項目を生成したら、それを利用して管理されているコントロールを文書、ブック、ワークシートに追加できます。 詳しくは、「文書とワークシートにマネージド コントロールを追加する」をご覧ください。

Word 文書のホスト項目を生成するには

  • 次のコード例はアクティブな文書のホスト項目を生成する方法を示しています。

    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 ブックのホスト項目を生成するには

  • 次のコード例はアクティブなブックのホスト項目を生成する方法を示しています。

    Microsoft.Office.Interop.Excel.Workbook nativeWorkbook = 
    Globals.ThisAddIn.Application.ActiveWorkbook;
if (nativeWorkbook != null)
{
    Microsoft.Office.Tools.Excel.Workbook vstoWorkbook = 
        Globals.Factory.GetVstoObject(nativeWorkbook);
}

Excel ワークシートのホスト項目を生成するには

  • 次のコード例はプロジェクトのアクティブなワークシートのホスト項目を生成する方法を示しています。

    Microsoft.Office.Interop.Excel.Worksheet nativeWorksheet =
    Globals.ThisAddIn.Application.ActiveSheet;
if (nativeWorksheet != null)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoSheet = 
        Globals.Factory.GetVstoObject(nativeWorksheet);
}

ListObject ホスト コントロールを生成する

GetVstoObject メソッドを利用して ListObject を拡張すると、このメソッドは ListObject を返します。 この ListObject には、元の ListObject のすべての機能があります。 また、追加の機能もあり、Windows フォームのデータ バインディング モデルを使ってデータにバインドすることもできます。 詳しくは、「ListObject コントロール」をご覧ください。

ListObject のホスト コントロールを生成するには

  • 次のコード例はプロジェクトのアクティブなワークシートの最初の ListObject に対して ListObject を生成する方法を示しています。

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

文書とワークシートにマネージド コントロールを追加する

Document または Worksheetを生成したら、これらの拡張オブジェクトが表す文書またはワークシートにコントロールを追加できます。 コントロールを追加するには、Document または Worksheet の Controls プロパティを使用します。 詳細については、「実行時に Office 文書にコントロールを追加する」を参照してください。

Windows フォーム コントロールまたは ホスト コントロールを追加できます。 ホスト コントロールは Visual Studio Tools for Office ランタイムにより提供されるコントロールであり、Word または Excel プライマリ相互運用機能アセンブリのそれに対応するコントロールをラップします。 ホスト コントロールは、基になるネイティブ Office オブジェクトのすべての動作を公開します。 また、イベントも発生させ、Windows フォームのデータ バインディング モデルを使ってデータにバインドすることもできます。 詳細については、「ホスト項目とホスト コントロールの概要」を参照してください。

Note

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

コントロールの保持と削除

管理されているコントロールを文書またはワークシートに追加するとき、文書を保存し、閉じても、コントロールは保持されません。 基礎となるネイティブ Office オブジェクトだけが残るようにすべてのホスト コントロールが削除されます。 たとえば、 ListObject が ListObjectになります。 すべての Windows フォーム コントロールも削除されますが、ActiveX ラッパーは文書に残ります。 コントロールを消去するか、文書を次回開いたときにコントロールを再作成するには、VSTO アドインにコードを追加する必要があります。 詳しくは、「Office ドキュメントでのダイナミック コントロールの永続化」をご覧ください。

文書とブックでアプリケーション レベルのイベントにアクセスする

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

VSTO アドインでネイティブ Office オブジェクトを使用するとき、これらのアプリケーションレベル イベントを処理し、イベントを発生された文書が自分でカスタマイズした文書であるかどうかを判断する追加コードを記述する必要があります。 ホスト項目は文書レベルでこれらのイベントを提供します。そのため、特定の文書のイベントを簡単に処理できます。 ホスト項目を生成し、そのホスト項目のイベントを処理できます。

ネイティブ Word オブジェクトを使用する例

次のコード例は Word 文書のアプリケーションレベル イベントの処理方法を示しています。 CreateDocument メソッドは新しい文書を作成し、その文書が保存されないようにする DocumentBeforeSave イベント ハンドラーを定義します。 このイベントは Application オブジェクトに対して発生するアプリケーション レベルのイベントであり、イベント ハンドラーでは、Doc パラメーターと document1 オブジェクトを比較して、document1 が保存された文書を表しているかどうかを判断する必要があります。

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

ホスト項目を使用する例

次のコード例では、 BeforeSave ホスト項目の Document イベントを処理することでこのプロセスを簡略化しています。 これらの例の CreateDocument2 メソッドは Document オブジェクトを拡張する document2 を生成し、文書が保存されないようにする BeforeSave イベント ハンドラーを定義します。 このイベント ハンドラーは document2 が保存されるときにのみ呼び出され、どの文書が保存されたのかを確認するための追加の操作を行うことなく、保存操作を取り消すことができます。

次のコード例はこの作業を示しています。

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 オブジェクトが拡張されているかどうかを判断する

特定のネイティブ Office オブジェクトに対して拡張オブジェクトが既に生成されているかどうかを確認するには、HasVstoObject メソッドを使用します。 拡張オブジェクトが既に生成されている場合、このメソッドは true を返します。

Globals.Factory.HasVstoObject メソッドを使用します。 拡張オブジェクトに対してテストするネイティブの Word または Excel オブジェクト ( Document や Worksheetなど) を渡します。

HasVstoObject メソッドは、指定した Office オブジェクトに拡張オブジェクトがある場合にのみ、コードの実行で便利です。 たとえば、DocumentBeforeSave イベントを処理して、文書が保存される前に文書からマネージド コントロールを削除する Word VSTO アドインがある場合は、HasVstoObject メソッドを使って、文書が拡張されているかどうかを確認します。 文書が拡張されていない場合、マネージド コントロールは含まれないので、イベント ハンドラーは文書内のコントロールのクリーン アップを試行せずに処理を終了できます。

関連するコンテンツ