Obtention d'objets étendus à partir d'objets Office natifs dans les personnalisations au niveau du document
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'une des feuilles de calcul d'un classeur personnalisé, mais pas lorsqu'il active une feuille de calcul d'un autre classeur qui se trouve ouvert au même moment.
Lorsque vous avez un objet Office natif, vous pouvez vérifier si cet objet a été étendu en un élément hôte ou en un contrôle hôte dans une personnalisation de niveau document. Les éléments hôtes et contrôles hôtes sont des types fournis par le Visual Studio Tools pour Office Runtime 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. Les éléments hôtes et contrôles hôtes sont rassemblés sous le nom d'objets étendus. Pour plus d'informations sur les éléments hôtes et contrôles hôtes, consultez Vue d'ensemble des éléments hôtes et des contrôles hôtes.
S'applique à : Les informations contenues dans cette rubrique s'appliquent aux projets de niveau document pour les applications suivantes : Excel 2007, Excel 2010, Word 2007 et Word 2010. Pour en savoir plus, consultez Fonctionnalités disponibles par type d'application et de projet Office.
Compréhension des méthodes GetVstoObject et HasVstoObject
Pour tester un objet Office natif, utilisez les méthodes HasVstoObject et GetVstoObject dans votre projet :
Utilisez la méthode HasVstoObject si vous souhaitez simplement déterminer si l'objet Office natif a un objet étendu dans votre personnalisation. 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.
Utilisez la méthode GetVstoObject si vous souhaitez obtenir l'objet étendu d'un objet Office natif. 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 spécifié en a un. Sinon, GetVstoObject retourne null. Par exemple, la méthode GetVstoObject retourne un Microsoft.Office.Tools.Word.Document si le Microsoft.Office.Interop.Word.Document spécifié est un objet sous-jacent du document de votre projet de document Word.
Dans les projets de niveau document, vous ne pouvez pas utiliser la méthode GetVstoObject pour créer un nouvel élément hôte Microsoft.Office.Tools.Excel.Workbook, Microsoft.Office.Tools.Excel.Worksheet ou Microsoft.Office.Tools.Word.Document au moment de l'exécution. Vous ne pouvez utiliser cette méthode que pour accéder aux éléments hôtes existants générés dans votre projet au moment du design. Si vous souhaitez créer des éléments hôtes au moment de l'exécution, vous devez développer un projet de niveau application. Pour plus d'informations, consultez Limitations de programmation des éléments hôtes et des contrôles hôtes et Extension de documents Word et de classeurs Excel dans des compléments d'application au moment de l'exécution..
Utilisation des méthodes GetVstoObject et HasVstoObject
La façon dont vous appelez les méthodes HasVstoObject et GetVstoObject dépend de la version de .NET Framework ciblée par votre projet :
Dans les projets qui ciblent le .NET Framework 4, utilisez la méthode Globals.Factory.GetVstoObject ou Globals.Factory.HasVstoObject et passez dans l'objet Word ou Excel natif (tel qu'un Microsoft.Office.Interop.Word.Document ou Microsoft.Office.Interop.Excel.Worksheet) que vous voulez tester.
Dans les projets qui ciblent .NET Framework 3.5, accédez aux méthodes sur une instance de l'un des types suivants dans les assemblys PIA (Primary Interop Assembly) de Word et Excel :
Notes
Pour utiliser les méthodes GetVstoObject et HasVstoObject dans les projets au niveau du document qui ciblent .NET Framework 3.5, 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 en haut de votre fichier de code. Les méthodes GetVstoObject et HasVstoObject sont implémentées comme des méthodes d'extension, et ces instructions vous permettent d'appeler ces méthodes.
Exemple : 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.Base
ElseIf Type.ReferenceEquals(Globals.Sheet2.InnerObject, Sh) Then
vstoWorksheet = Globals.Sheet2.Base
ElseIf Type.ReferenceEquals(Globals.Sheet3.InnerObject, Sh) Then
vstoWorksheet = Globals.Sheet3.Base
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.Base;
else if (Type.ReferenceEquals(Globals.Sheet2.InnerObject, Sh))
vstoWorksheet = Globals.Sheet2.Base;
else if (Type.ReferenceEquals(Globals.Sheet3.InnerObject, Sh))
vstoWorksheet = Globals.Sheet3.Base;
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. Cet exemple montre comment appeler ces méthodes dans un projet qui cible le .NET Framework 4.
Private Sub ThisWorkbook_SheetActivate2(ByVal Sh As Object)
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
Globals.Factory.HasVstoObject(interopWorksheet) Then
vstoWorksheet = Globals.Factory.GetVstoObject(interopWorksheet)
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 && Globals.Factory.HasVstoObject(interopWorksheet))
{
vstoWorksheet = Globals.Factory.GetVstoObject(interopWorksheet);
}
if (vstoWorksheet != null)
{
// Do something with the VSTO worksheet here.
}
}
L'exemple suivant montre la même tâche dans un projet qui cible .NET Framework 3.5.
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.
}
}
Voir aussi
Référence
Méthodes d'extension (Guide de programmation C#)
Concepts
Vue d'ensemble des éléments hôtes et des contrôles hôtes
Méthodes d'extension (Visual Basic)