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

Les objets étendus sont des instances des types fournis par le runtime de Visual Studio Tools pour Office qui ajoutent des fonctionnalités aux objets qui existent en mode natif dans Word ou les modèles objet 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 d' GetVstoObject pour un objet spécifié Word ou excel, il 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, il 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.

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 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.

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

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

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.

Remarque
Vous ne pouvez pas ajouter de contrôle d' XmlMappedRange à une feuille de calcul, ou un contrôle d' XMLNode ou d' XMLNodes à un document, à l'aide d'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

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

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

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

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.

Utilisez la méthode Globals.Factory.HasVstoMethod. Passez dans l'objet Word ou Excel natif, tel qu' Microsoft.Office.Interop.Word.Document ou Microsoft.Office.Interop.Excel.Worksheet, que vous souhaitez 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.

Concepts

Autres ressources