Extension de documents Word et de classeurs Excel dans des compléments d'application au moment de l'exécution.

Article
08/10/2011

Vous pouvez utiliser un complément d'application pour personnaliser des documents Word et des classeurs Excel de différentes façons :

ajouter des contrôles gérés à tout document ou feuille de calcul ouvert ;
créer des balises actives qui sont reconnues dans un document ou classeur spécifique ;

Notes

Les balises actives sont déconseillées dans Excel 2010 et Word 2010. Pour plus d'informations, consultez Vue d'ensemble des balises actives.
convertir un objet de liste existant sur une feuille de calcul Excel en un ListObject étendu qui expose des événements et peut être lié aux données à l'aide du modèle de liaison de données Windows Forms ;
accéder à des événements au niveau de l'application qui sont exposés par Word et Excel pour des documents, des classeurs et des feuilles de calcul spécifiques.

Pour utiliser cette fonctionnalité, vous devez générer au moment de l'exécution un objet qui étend le document ou le classeur.

S'applique à : Les informations contenues dans cette rubrique s'appliquent aux projets de niveau application 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.

Génération d'objets étendus dans les compléments

Les objets étendus sont des instances de types fournies par le runtime Visual Studio Tools pour Office qui ajoute les fonctionnalités aux objets qui existent en mode natif dans les modèles objet Word ou Excel (objets Office natifs). Pour générer un objet étendu pour un objet Word ou Excel, utilisez la méthode GetVstoObject. La première fois que vous appelez la méthode GetVstoObject d'un objet spécifié Word ou Excel spécifié, elle retourne un objet qui étend l'objet spécifié. Chaque fois que vous appelez la méthode et spécifiez le même objet Word ou Excel natif, elle retourne le même objet étendu.

Le nom du type de l'objet étendu est identique à celui du type de l'objet Office natif, mais le type est défini dans l'espace de noms Microsoft.Office.Tools.Excel ou Microsoft.Office.Tools.Word. Par exemple, si vous appelez la méthode GetVstoObject pour étendre un objet Microsoft.Office.Interop.Word.Document, la méthode retourne un objet Microsoft.Office.Tools.Word.Document.

La façon dont vous accédez à ces méthodes GetVstoObject dépend de la version du .NET Framework ciblé par votre projet :

Dans les projets qui ciblent .NET Framework 3.5, utilisez les méthodes GetVstoObject d'une instance de l'un des types suivants dans les assemblys PIA (Primary Interop Assembly) de Word et Excel :
Dans les projets qui ciblent le .NET Framework 4, utilisez la méthode Globals.Factory.GetVstoObject, 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 étendre.

Les méthodes GetVstoObject sont destinées à être utilisées principalement dans les projets au niveau de l'application. Vous pouvez également les utiliser dans des projets au niveau du document, mais elles se comporteront différemment et auront moins d'applications. Pour plus d'informations, consultez Obtention d'objets étendus à partir d'objets Office natifs dans les personnalisations au niveau du document.

Pour déterminer si un objet étendu a déjà été généré pour un objet Office natif particulier, utilisez la méthode HasVstoObject. Pour plus d'informations, consultez Déterminer si un objet Office a été étendu.

Notes

Pour utiliser les méthodes GetVstoObject et HasVstoObject dans un fichier de code autre que ThisAddIn.cs ou ThisAddIn.vb dans un projet qui cible .NET Framework 3.5, vous devez modifier votre projet. Pour plus d'informations, consultez Configurer votre projet pour utiliser les méthodes GetVstoObject et HasVstoObject.

Génération d'éléments hôtes

Lorsque vous utilisez le GetVstoObject pour étendre un objet au niveau du document, c'est-à-dire Microsoft.Office.Interop.Excel.Workbook, Microsoft.Office.Interop.Excel.Worksheet ou Microsoft.Office.Interop.Word.Document), l'objet retourné est appelé élément hôte. Un élément hôte est un type d'élément qui peut contenir d'autres objets, y compris d'autres objets étendus et des contrôles. Il ressemble au type correspondant dans l'assembly PIA (Primary Interop Assembly) Word ou Excel, mais il comporte des fonctionnalités supplémentaires. Pour plus d'informations sur les éléments hôtes, consultez Vue d'ensemble des éléments hôtes et des contrôles hôtes.

Après avoir généré un élément hôte, vous pouvez l'utiliser pour ajouter des balises actives ou des contrôles gérés au document, au classeur ou à la feuille de calcul. Pour plus d'informations, consultez Ajout de balises actives aux documents et classeurs et Ajout de contrôles gérés aux documents et feuilles de calcul.

Pour générer un élément hôte pour un document Word

L'exemple de code suivant montre comment générer un élément hôte pour le document actif dans un projet qui cible le .NET Framework 4.

If Globals.ThisAddIn.Application.Documents.Count > 0 Then
    Dim NativeDocument As Microsoft.Office.Interop.Word.Document = _
        Globals.ThisAddIn.Application.ActiveDocument
    Dim VstoDocument As Microsoft.Office.Tools.Word.Document = _
        Globals.Factory.GetVstoObject(NativeDocument)
End If

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

L'exemple de code suivant montre la même tâche dans un projet qui cible .NET Framework 3.5.

If Globals.ThisAddIn.Application.Documents.Count > 0 Then
    Dim NativeDocument As Microsoft.Office.Interop.Word.Document =
        Globals.ThisAddIn.Application.ActiveDocument
    If NativeDocument IsNot Nothing Then
        Dim vstoDocument As Microsoft.Office.Tools.Word.Document =
            NativeDocument.GetVstoObject()
    End If
End If

if (Globals.ThisAddIn.Application.Documents.Count > 0)
{
    Microsoft.Office.Interop.Word.Document nativeDocument =
        Globals.ThisAddIn.Application.ActiveDocument;
    Microsoft.Office.Tools.Word.Document vstoDocument =
        nativeDocument.GetVstoObject();
}

Pour générer un élément hôte pour un classeur Excel

L'exemple de code suivant montre comment générer un élément hôte pour le classeur actif dans un projet qui cible le .NET Framework 4.

Dim NativeWorkbook As Microsoft.Office.Interop.Excel.Workbook =
    Globals.ThisAddIn.Application.ActiveWorkbook
If NativeWorkbook IsNot Nothing Then
    Dim vstoWorkbook As Microsoft.Office.Tools.Excel.Workbook =
        Globals.Factory.GetVstoObject(NativeWorkbook)
End If

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

L'exemple de code suivant montre la même tâche dans un projet qui cible .NET Framework 3.5.

Dim NativeWorkbook As Microsoft.Office.Interop.Excel.Workbook = _
    Globals.ThisAddIn.Application.ActiveWorkbook

If NativeWorkbook IsNot Nothing Then
    Dim VstoWorkbook As Microsoft.Office.Tools.Excel.Workbook = _
        NativeWorkbook.GetVstoObject()
End If

Microsoft.Office.Interop.Excel.Workbook nativeWorkbook =
    Globals.ThisAddIn.Application.ActiveWorkbook;

if (nativeWorkbook != null)
{
    Microsoft.Office.Tools.Excel.Workbook vstoWorkbook =
        nativeWorkbook.GetVstoObject();
}

Pour générer un élément hôte pour une feuille de calcul Excel

L'exemple de code suivant montre comment générer un élément hôte pour la feuille de calcul active dans un projet qui cible le .NET Framework 4.

Dim NativeWorksheet As Microsoft.Office.Interop.Excel.Worksheet =
    Globals.ThisAddIn.Application.ActiveSheet
If NativeWorksheet IsNot Nothing Then
    Dim vstoSheet As Microsoft.Office.Tools.Excel.Worksheet =
        Globals.Factory.GetVstoObject(NativeWorksheet)
End If

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

L'exemple de code suivant montre la même tâche dans un projet qui cible .NET Framework 3.5.

Dim NativeSheet As Microsoft.Office.Interop.Excel.Worksheet = _
    TryCast(Globals.ThisAddIn.Application.ActiveSheet,  _
    Microsoft.Office.Interop.Excel.Worksheet)

If NativeSheet IsNot Nothing Then
    Dim VstoSheet As Microsoft.Office.Tools.Excel.Worksheet = _
        NativeSheet.GetVstoObject()
End If

Microsoft.Office.Interop.Excel.Worksheet nativeSheet =
    Globals.ThisAddIn.Application.ActiveSheet as
    Microsoft.Office.Interop.Excel.Worksheet;

if (nativeSheet != null)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoSheet =
        nativeSheet.GetVstoObject();
}

Génération de contrôles hôtes ListObject

Lorsque vous utilisez la méthode GetVstoObject pour étendre un Microsoft.Office.Interop.Excel.ListObject, elle retourne un Microsoft.Office.Tools.Excel.ListObject. Le Microsoft.Office.Tools.Excel.ListObject généré possède toutes les caractéristiques du Microsoft.Office.Interop.Excel.ListObject d'origine, mais il comporte également des fonctionnalités supplémentaires, telles que la capacité de se lier aux données en utilisant le modèle de liaison de données Windows Forms. Pour plus d'informations, consultez ListObject, contrôle.

Pour générer un contrôle hôte pour un ListObject

L'exemple de code suivant montre comment générer un Microsoft.Office.Tools.Excel.ListObject pour le premier Microsoft.Office.Interop.Excel.ListObject dans la feuille de calcul active d'un projet qui cible le .NET Framework 4.

Dim sheet As Microsoft.Office.Interop.Excel.Worksheet =
    Globals.ThisAddIn.Application.ActiveSheet
If sheet.ListObjects.Count > 0 Then
    Dim listObject As Excel.ListObject = sheet.ListObjects(1)
    Dim vstoListObject As Microsoft.Office.Tools.Excel.ListObject =
        Globals.Factory.GetVstoObject(listObject)
End If

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

L'exemple de code suivant montre la même tâche dans un projet qui cible .NET Framework 3.5.

Dim sheet As Excel.Worksheet = Globals.ThisAddIn.Application.ActiveSheet

If sheet.ListObjects.Count > 0 Then
    Dim listObject As Excel.ListObject = sheet.ListObjects(1)
    Dim vstoListObject As Microsoft.Office.Tools.Excel.ListObject = _
        listObject.GetVstoObject()
End If

Microsoft.Office.Interop.Excel.Worksheet sheet =
    Globals.ThisAddIn.Application.ActiveSheet as
    Microsoft.Office.Interop.Excel.Worksheet;

if (sheet.ListObjects.Count > 0)
{
    Excel.ListObject listObject = sheet.ListObjects[1];
    Microsoft.Office.Tools.Excel.ListObject vstoListObject =
        listObject.GetVstoObject();
}

Ajout de balises actives aux documents et classeurs

Après avoir généré Microsoft.Office.Tools.Word.Document ou Microsoft.Office.Tools.Excel.Workbook, vous pouvez créer une balise active qui est reconnue dans le contexte du document ou classeur que ces objets représentent. Pour cela, utilisez la propriété VstoSmartTags de Microsoft.Office.Tools.Word.Document ou de Microsoft.Office.Tools.Excel.Workbook. Pour plus d'informations, consultez les rubriques suivantes :

Ajout de contrôles gérés aux documents et feuilles de calcul

Après avoir généré Microsoft.Office.Tools.Word.Document ou Microsoft.Office.Tools.Excel.Worksheet, vous pouvez ajouter des contrôles au document ou à la feuille de calcul que ces objets étendus représentent. Pour cela, utilisez la propriété Controls de Microsoft.Office.Tools.Word.Document ou de Microsoft.Office.Tools.Excel.Worksheet. Pour plus d'informations, consultez Ajout de contrôles à des documents Office au moment de l'exécution.

Vous pouvez ajouter des contrôles Windows Forms ou des contrôles hôtes. Un contrôle hôte est un contrôle fourni par le Visual Studio Tools pour Office Runtime qui encapsule un contrôle correspondant dans l'assembly PIA de Word ou d'Excel. Un contrôle hôte expose l'ensemble du comportement de l'objet Office natif sous-jacent, mais il déclenche également des événements et peut être lié aux données en utilisant le modèle de liaison de données Windows Forms. Pour plus d'informations, consultez Vue d'ensemble des éléments hôtes et des contrôles hôtes.

Notes

Vous ne pouvez pas ajouter de contrôle XmlMappedRange à une feuille de calcul, ni un contrôle XMLNode ou XMLNodes à un document en utilisant un complément. Ces contrôles ne peuvent pas être ajoutés par programmation. Pour plus d'informations, consultez Limitations de programmation des éléments hôtes et des contrôles hôtes.

Persistance et suppression de contrôles

Lorsque vous ajoutez des contrôles gérés à un document ou à une feuille de calcul, les contrôles ne sont pas rendus persistant lorsque le document est enregistré puis fermé. Tous les contrôles hôtes sont supprimés afin que seuls les objets Office natifs sous-jacents soient conservés (par exemple, Microsoft.Office.Tools.Excel.ListObject devient Microsoft.Office.Interop.Excel.ListObject). Tous les contrôles Windows Forms sont également supprimés, mais leurs wrappers ActiveX sont conservés dans le document. Vous devez inclure le code dans votre complément afin de nettoyer les contrôles, ou de les recréer à la prochaine ouverture du document. Pour plus d'informations, consultez Rendre des contrôles dynamiques persistants dans des documents Office.

Accès aux événements au niveau de l'application sur des documents et des classeurs

Certains événements de document, classeur et feuille de calcul dans les objets Word et Excel natifs sont déclenchés uniquement au niveau de l'application. Par exemple, l'événement DocumentBeforeSave est déclenché lorsqu'un document est ouvert dans Word, mais il est défini dans la classe Microsoft.Office.Interop.Word.Application, plutôt que dans la classe Microsoft.Office.Interop.Word.Document.

Lorsque vous utilisez uniquement des objets Office natifs dans votre complément, vous devez gérer ces événements au niveau de l'application puis écrire du code supplémentaire afin de déterminer si le document qui a déclenché l'événement est un document que vous avez personnalisé. Les éléments hôtes fournissent ces événements au niveau du document, afin qu'il soit plus facile de les gérer pour un document spécifique. Vous pouvez générer un élément hôte puis gérer l'événement pour cet élément hôte.

Exemple avec utilisation d'objets Word natifs

L'exemple de code suivant montre comment gérer un événement au niveau de l'application pour les documents Word. La méthode CreateDocument crée un nouveau document, puis définit un gestionnaire d'événements DocumentBeforeSave qui empêche ce document d'être enregistré. Étant donné qu'il s'agit d'un événement au niveau de l'application qui est déclenché pour l'objet Microsoft.Office.Interop.Word.Application, le gestionnaire d'événements doit comparer le paramètre Doc avec l'objet document1 afin de déterminer si document1 représente le document enregistré.

Private document1 As Word.Document = Nothing

Private Sub CreateDocument1()
    document1 = Me.Application.Documents.Add()
End Sub

Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
    ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) _
    Handles Application.DocumentBeforeSave
    If Type.ReferenceEquals(Doc, document1) Then
        Cancel = True
    End If
End Sub

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

Exemple avec utilisation d'un élément hôte

Les exemples de code suivants simplifient ce processus en gérant l'événement BeforeSave d'un élément hôte Microsoft.Office.Tools.Word.Document. La méthode CreateDocument2 dans ces exemples génère un Microsoft.Office.Tools.Word.Document qui étend l'objet document2, puis elle définit un gestionnaire d'événements BeforeSave qui empêche le document d'être enregistré. Étant donné que ce gestionnaire d'événements est appelé uniquement lorsque document2 est enregistré, le gestionnaire d'événements peut annuler l'action de sauvegarde sans avoir à vérifier en plus quel document a été enregistré.

L'exemple de code suivant montre cette tâche dans un projet qui cible le .NET Framework 4.

Private document2 As Word.Document = Nothing
Private WithEvents vstoDocument As Microsoft.Office.Tools.Word.Document = Nothing

Private Sub CreateDocument2()
    document2 = Me.Application.Documents.Add()
    vstoDocument = Globals.Factory.GetVstoObject(document2)
End Sub

Private Sub vstoDocument_BeforeSave(ByVal sender As Object, _
    ByVal e As SaveEventArgs) Handles vstoDocument.BeforeSave
    e.Cancel = True
End Sub

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

L'exemple de code suivant montre cette tâche dans un projet qui cible .NET Framework 3.5.

Private document2 As Microsoft.Office.Interop.Word.Document = Nothing
Private WithEvents vstoDocument As Microsoft.Office.Tools.Word.Document = Nothing

Private Sub CreateDocument2()
    document2 = Me.Application.Documents.Add()
    vstoDocument = document2.GetVstoObject()
End Sub

Private Sub vstoDocument_BeforeSave(ByVal sender As Object,
    ByVal e As SaveEventArgs) Handles vstoDocument.BeforeSave
    e.Cancel = True
End Sub

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 = document2.GetVstoObject();
    vstoDocument.BeforeSave += new SaveEventHandler(vstoDocument_BeforeSave);
}

private void vstoDocument_BeforeSave(object sender, SaveEventArgs e)
{
    e.Cancel = true;
}

Déterminer si un objet Office a été étendu

Pour déterminer si un objet étendu a déjà été généré pour un objet Office natif particulier, utilisez la méthode HasVstoObject. Cette méthode retourne la valeur true si un objet étendu a déjà été généré ; sinon, elle retourne la valeur false.

Dans les projets qui ciblent .NET Framework 3.5, la méthode HasVstoObject est disponible sur des instances de l'un des types suivants dans les assemblys PIA (Primary Interop Assembly) de Word et Excel :

Dans les projets qui ciblent le .NET Framework 4, utilisez la méthode Globals.Factory.HasVstoMethod. 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 pour un objet étendu.

La méthode HasVstoObject s'avère utile lorsque vous voulez exécuter du code uniquement lorsqu'un objet Office spécifié possède un objet étendu. Par exemple, si vous avez un complément Word qui gère l'événement DocumentBeforeSave pour supprimer des contrôles gérés d'un document avant qu'il ne soit enregistré, vous pouvez utiliser la méthode HasVstoObject pour déterminer si le document a été étendu. Si le document n'a pas été étendu, il ne peut pas contenir de contrôles gérés, et par conséquent, le gestionnaire d'événements peut simplement retourner une valeur sans essayer de nettoyer des contrôles sur le document.

Configuration de projets de .NET Framework 3.5 pour utiliser les méthodes GetVstoObject et HasVstoObject

Lorsque vous créez un projet au niveau de l'application qui cible .NET Framework 3.5, le projet est configuré automatiquement à votre place pour utiliser les méthodes GetVstoObject et HasVstoObject dans les fichiers de code ThisAddIn.cs ou ThisAddIn.vb. Pour utiliser ces méthodes dans un autre fichier que ThisAddIn.cs ou ThisAddIn.vb, vous devez apporter les modifications suivantes au fichier de code.

Pour modifier un fichier de code dans un projet Excel afin de créer des objets étendus

Ajoutez les instructions using (pour C#) ou Imports (pour Visual Basic) suivantes au début du fichier de code dans lequel vous voulez utiliser les méthodes GetVstoObject et HasVstoObject.
```
Imports Microsoft.Office.Tools.Excel.Extensions
```
```
using Microsoft.Office.Tools.Excel.Extensions;
```

Pour modifier un fichier de code dans un projet Word afin de créer des objets étendus

Ajoutez les instructions using (pour C#) ou Imports (pour Visual Basic) suivantes au début du fichier de code dans lequel vous voulez utiliser les méthodes GetVstoObject et HasVstoObject.
```
Imports Microsoft.Office.Tools.Word.Extensions
```
```
using Microsoft.Office.Tools.Word.Extensions;
```

Ces modifications sont requises parce que les méthodes GetVstoObject et HasVstoObject sont implémentées comme des méthodes d'extension. Bien que vous utilisiez les méthodes GetVstoObject et HasVstoObject comme si elles avaient été définies dans des types dans les assemblys PIA (Primary Interop Assembly) d'Excel ou de Word, elles sont en fait définies dans des types dans les espaces de noms Microsoft.Office.Tools.Excel.Extensions et Microsoft.Office.Tools.Word.Extensions de Visual Studio Tools pour Office Runtime. Pour plus d'informations sur les méthodes d'extension, consultez Méthodes d'extension (Guide de programmation C#) et Méthodes d'extension (Visual Basic).