Obtention d'objets étendus à partir d'objets Office natifs dans les personnalisations au niveau du document

Article
04/28/2010

Mise à jour : Juillet 2008

S'applique à
Les informations de cette rubrique s'appliquent uniquement aux projets Visual Studio Tools pour Office et versions de Microsoft Office spécifiés. Type de projet Projets au niveau du document Version de Microsoft Office Excel 2007 Word 2007 Pour plus d'informations, consultez Fonctionnalités disponibles par type d'application et de projet.

Les informations de cette rubrique s'appliquent uniquement aux projets Visual Studio Tools pour Office et versions de Microsoft Office spécifiés.

Type de projet

Projets au niveau du document

Version de Microsoft Office

Excel 2007
Word 2007

Pour plus d'informations, consultez Fonctionnalités disponibles par type d'application et de projet.

De nombreux gestionnaires d'événements pour Office reçoivent un objet Office natif qui représente le classeur, la feuille de calcul ou le document qui a déclenché l'événement. Il peut arriver que vous ne souhaitiez exécuter du code que si le classeur ou le document de votre personnalisation au niveau du document a déclenché l'événement. Par exemple, dans une personnalisation au niveau du document pour Excel, vous pouvez souhaiter exécuter du code lorsque l'utilisateur active l'un des éléments hôtes Microsoft.Office.Tools.Excel.Worksheet dans la personnalisation, mais pas lorsqu'il active une feuille de calcul dans un autre classeur qui se trouve par hasard ouvert au même moment.

À compter de Visual Studio 2008 Service Pack 1 (SP1), lorsque vous obtenez un objet Office natif, vous pouvez tester si cet objet a été étendu dans un élément hôte ou contrôle hôte Microsoft.Office.Tools.Excel.ListObject dans une personnalisation au niveau du document.

Les éléments hôtes et contrôles hôtes sont des objets Visual Studio Tools pour Office qui ajoutent les fonctionnalités aux objets qui existent en mode natif dans les modèles objets (appelés objets Office natifs) de Word ou d'Excel. Ils sont désignés collectivement sous les termes d'objets étendus. Pour plus d'informations sur la création d'éléments hôtes et de contrôles hôtes, consultez Vue d'ensemble des éléments hôtes et des contrôles hôtes.

Utilisation des méthodes GetVstoObject et HasVstoObject

Pour tester un objet Office natif, utilisez les méthodes HasVstoObject et GetVstoObject d'une instance de l'un des objets Office natifs suivants :

Si vous souhaitez simplement déterminer si l'objet Office natif a un objet étendu dans votre personnalisation, utilisez la méthode HasVstoObject. Cette méthode retourne la valeur true si l'objet Office natif a un objet étendu, et false si ce n'est pas le cas.

Si vous souhaitez obtenir l'objet étendu, utilisez la méthode GetVstoObject. Cette méthode retourne un objet Microsoft.Office.Tools.Excel.ListObject, Microsoft.Office.Tools.Excel.Workbook, Microsoft.Office.Tools.Excel.Worksheetou Microsoft.Office.Tools.Word.Document si l'objet Office natif en a un. Sinon, GetVstoObject retourne null. Par exemple, la méthode GetVstoObject d'un objet Microsoft.Office.Interop.Word.Document retourne Microsoft.Office.Tools.Word.Document si Microsoft.Office.Interop.Word.Document est l'objet sous-jacent du document dans votre projet de document Word.

Vous ne pouvez pas utiliser GetVstoObject dans une solution au niveau du document pour créer un élément hôte au moment de l'exécution. Vous ne pouvez l'utiliser que pour accéder aux éléments hôtes existants générés dans votre projet au moment du design. Pour plus d'informations, consultez Limitations de programmation des éléments hôtes et des contrôles hôtes.

Dans les projets au niveau de l'application, vous pouvez utiliser la méthode GetVstoObject pour générer de nouveaux éléments hôtes au moment de l'exécution. Pour plus d'informations, consultez Extension de documents Word et de classeurs Excel dans des compléments d'application au moment de l'exécution..

Remarque :
Pour utiliser les méthodes GetVstoObject et HasVstoObject, vous devez ajouter les instructions using (pour C#) ou Imports (pour Visual Basic) pour les espaces de noms Microsoft.Office.Tools.Excel.Extensions ou Microsoft.Office.Tools.Word.Extensions au début de votre fichier de code. Les méthodes GetVstoObject et HasVstoObject sont implémentées comme des méthodes d'extension dans le runtime Visual Studio Tools pour Office, et ces instructions vous permettent d'appeler ces méthodes.

Pour utiliser les méthodes GetVstoObject et HasVstoObject, vous devez ajouter les instructions using (pour C#) ou Imports (pour Visual Basic) pour les espaces de noms Microsoft.Office.Tools.Excel.Extensions ou Microsoft.Office.Tools.Word.Extensions au début de votre fichier de code. Les méthodes GetVstoObject et HasVstoObject sont implémentées comme des méthodes d'extension dans le runtime Visual Studio Tools pour Office, et ces instructions vous permettent d'appeler ces méthodes.

Déterminer si un élément hôte a déclenché un événement

Les exemples de code suivants illustrent l'utilisation des méthodes HasVstoObject et GetVstoObject. Les deux exemples gèrent l'événement SheetActivate de la classe ThisWorkbook dans un projet de classeur Excel.

Le premier exemple détermine si l'un des éléments hôtes Microsoft.Office.Tools.Excel.Worksheet a été activé en comparant le paramètre Sh avec la propriété InnerObject de chaque élément hôte par défaut.

Sub ThisWorkbook_SheetActivate1(ByVal Sh As Object) Handles Me.SheetActivate
    Dim vstoWorksheet As Microsoft.Office.Tools.Excel.Worksheet = Nothing

    If Type.ReferenceEquals(Globals.Sheet1.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet1
    ElseIf Type.ReferenceEquals(Globals.Sheet2.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet2
    ElseIf Type.ReferenceEquals(Globals.Sheet3.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet3
    End If

    If vstoWorksheet IsNot Nothing Then
        ' Do something with the VSTO worksheet here.
    End If
End Sub

void ThisWorkbook_SheetActivate1(object Sh)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoWorksheet = null;

    if (Type.ReferenceEquals(Globals.Sheet1.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet1;
    else if (Type.ReferenceEquals(Globals.Sheet2.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet2;
    else if (Type.ReferenceEquals(Globals.Sheet3.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet3;

    if (vstoWorksheet != null)
    {
        // Do something with the VSTO worksheet here.
    }
}

L'exemple suivant simplifie ce processus en utilisant les méthodes HasVstoObject et GetVstoObject du paramètre Sh.

Sub ThisWorkbook_SheetActivate2(ByVal Sh As Object) Handles Me.SheetActivate
    Dim vstoWorksheet As Microsoft.Office.Tools.Excel.Worksheet = Nothing
    Dim interopWorksheet As Microsoft.Office.Interop.Excel.Worksheet = _
        CType(Sh, Microsoft.Office.Interop.Excel.Worksheet)

    If interopWorksheet IsNot Nothing AndAlso _
        interopWorksheet.HasVstoObject() Then
        vstoWorksheet = interopWorksheet.GetVstoObject()
    End If

    If vstoWorksheet IsNot Nothing Then
        ' Do something with the VSTO worksheet here.
    End If
End Sub

void ThisWorkbook_SheetActivate2(object Sh)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoWorksheet = null;
    Microsoft.Office.Interop.Excel.Worksheet interopWorksheet = 
        Sh as Microsoft.Office.Interop.Excel.Worksheet;

    if (interopWorksheet != null && interopWorksheet.HasVstoObject())
    {
        vstoWorksheet = interopWorksheet.GetVstoObject();
    }

    if (vstoWorksheet != null)
    {
        // Do something with the VSTO worksheet here.
    }
}