Limitations de programmation des éléments hôtes et des contrôles hôtes

Article
03/04/2013

Chaque élément hôte et chaque contrôle hôte sont conçus pour se comporter comme un objet Microsoft Office Word ou Microsoft Office Excel natif, avec des fonctionnalités supplémentaires.Toutefois, il existe des différences fondamentales entre le comportement d'éléments hôtes et de contrôles hôtes et celui des objets Office natifs au moment de l'exécution.

Pour obtenir des informations générales sur les éléments hôtes et les 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 et de niveau application pour les applications suivantes : Excel 2013, Excel 2010, Word 2013 et Word 2010. Pour en savoir plus, consultez Fonctionnalités disponibles par type d'application et de projet Office.

Création d'éléments hôtes par programmation

Lorsque vous créez ou ouvrez par programmation un document, un classeur ou une feuille de calcul au moment de l'exécution à l'aide du modèle objet Word ou Excel, l'élément n'est pas un élément hôte.Le nouvel objet est en fait un objet Office natif.Par exemple, si vous utilisez la méthode Documents.Add pour créer un document Word au moment de l'exécution, il s'agira d'un objet Microsoft.Office.Interop.Word.Document natif plutôt que d'un élément hôte Microsoft.Office.Tools.Word.Document.De la même façon, lorsque vous créez une feuille de calcul au moment de l'exécution à l'aide de la méthode Worksheets.Add, vous obtenez un objet natif Microsoft.Office.Interop.Excel.Worksheet plutôt qu'un élément hôte Microsoft.Office.Tools.Excel.Worksheet.

Dans les projets au niveau du document, vous ne pouvez pas créer d'éléments hôtes au moment de l'exécution.Dans les projets au niveau du document, les éléments hôtes ne peuvent être créés qu'au moment du design.Pour plus d'informations, consultez les rubriques Élément hôte de document, Élément hôte de classeur et Élément hôte de feuille de calcul.

Dans les projets au niveau de l'application, vous pouvez créer les éléments hôtes Microsoft.Office.Tools.Word.Document, Microsoft.Office.Tools.Excel.Workbook ou Microsoft.Office.Tools.Excel.Worksheet 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..

Création de contrôles hôtes par programmation

Vous pouvez ajouter des contrôles hôtes à un élément hôte Microsoft.Office.Tools.Word.Document ou Microsoft.Office.Tools.Excel.Worksheet par programmation au moment de l'exécution.Pour plus d’informations, consultez Ajout de contrôles à des documents Office au moment de l'exécution.

Vous ne pouvez pas ajouter de contrôles hôtes à un Microsoft.Office.Interop.Word.Document ou Microsoft.Office.Interop.Excel.Worksheet natif.

[!REMARQUE]

Les contrôles hôtes suivants ne peuvent pas être ajoutés par programmation aux feuilles de calcul ou aux documents : XmlMappedRange, XMLNodeet XMLNodes.

Description des différences de type entre les éléments hôtes, les contrôles hôtes et les objets Office natifs

Pour chaque élément hôte et contrôle hôte, il existe un objet Microsoft Office Word ou Microsoft Office Excel natif sous-jacent.Vous pouvez accéder à l'objet sous-jacent en utilisant la propriété InnerObject de l'élément hôte ou du contrôle hôte.Toutefois, il n'est pas possible de caster un objet Office natif vers son élément hôte ou son contrôle hôte correspondant.Si vous essayez d'effectuer un cast d'un objet Office natif en élément ou contrôle hôte, une exception InvalidCastException est levée.

Il existe plusieurs scénarios dans lesquels les différences entre les types d'éléments hôtes et contrôles hôtes et les objets Office natifs sous-jacents peuvent affecter votre code.

Passage de contrôles hôtes aux méthodes et propriétés

Dans Word, vous ne pouvez pas passer de contrôle hôte à une méthode ou une propriété qui requiert un objet Word natif comme paramètre.Vous devez utiliser la propriété InnerObject du contrôle hôte pour retourner l'objet Word natif sous-jacent.Par exemple, vous pouvez passer un objet Microsoft.Office.Interop.Word.Bookmark à une méthode en passant la propriété InnerObject du contrôle hôte Microsoft.Office.Tools.Word.Bookmark à la méthode.

Dans Excel, vous devez utiliser la propriété d' InnerObject du contrôle hôte pour passer le contrôle hôte à une méthode ou une propriété lorsque la méthode ou la propriété attend l'objet excel sous-jacent.

L'exemple suivant crée un contrôle Microsoft.Office.Tools.Excel.NamedRange et le passe à la méthode AutoFill.Le code utilise la propriété InnerObject sur la plage nommée pour retourner le contrôle Microsoft.Office.Interop.Excel.Range Office sous-jacent qui est requis par la méthode AutoFill.

Me.Range("A1").Value2 = "Monday"
Me.Range("A2").Value2 = "Tuesday"

Dim dayRange As Microsoft.Office.Tools.Excel.NamedRange = _
    Me.Controls.AddNamedRange(Me.Range("A1", "A7"), "dayRange")
Me.Range("A1", "A2").AutoFill(dayRange.InnerObject, Excel.XlAutoFillType.xlFillDays)

this.Range["A1"].Value2 = "Monday";
this.Range["A2"].Value2 = "Tuesday";

Microsoft.Office.Tools.Excel.NamedRange dayRange = 
    this.Controls.AddNamedRange(this.Range["A1", "A7"], "dayRange");
this.Range["A1", "A2"].AutoFill(dayRange.InnerObject, Excel.XlAutoFillType.xlFillDays);

Types de retour de méthodes et propriétés Office natives

La plupart des méthodes et propriétés des éléments hôtes retournent l'objet Office natif sous-jacent sur lequel l'élément hôte repose.Par exemple, la propriété Parent d'un contrôle hôte NamedRange dans Excel retourne un objet Microsoft.Office.Interop.Excel.Worksheet plutôt qu'un élément hôte Microsoft.Office.Tools.Excel.Worksheet.De la même façon, la propriété Parent d'un contrôle hôte RichTextContentControl dans Word retourne un objet Microsoft.Office.Interop.Word.Document plutôt qu'un élément hôte Microsoft.Office.Tools.Word.Document.

Accès à des collections de contrôles hôtes

Visual Studio Tools pour Office Runtime ne fournit pas de collections pour chaque type de contrôle hôte.Utilisez plutôt la propriété Controls d'un élément hôte pour itérer au sein de tous les contrôles managés (contrôles hôtes et contrôles Windows Forms) du document ou de la feuille de calcul, puis recherchez les éléments qui correspondent au type du contrôle hôte qui vous intéresse.L'exemple de code suivant examine chaque contrôle d'un document Word et détermine si le contrôle est un Microsoft.Office.Tools.Word.Bookmark.

Dim targetControl As Object
For Each targetControl In Me.Controls

    If TypeOf (targetControl) Is Microsoft.Office.Tools.Word.Bookmark Then
        Dim bookMark As Microsoft.Office.Tools.Word.Bookmark = _
            CType(targetControl, Microsoft.Office.Tools.Word.Bookmark)

        ' Do some work with the book mark here.
    End If
Next

foreach (object targetControl in this.Controls)
{
    Microsoft.Office.Tools.Word.Bookmark bookMark =
        targetControl as Microsoft.Office.Tools.Word.Bookmark;

    if (bookMark != null)
    {
        // Do some work with the bookmark here.
    }
}

Pour plus d'informations sur la propriété Controls des éléments hôtes, consultez Ajout de contrôles à des documents Office au moment de l'exécution.

Les modèles objets Excel et Word incluent des propriétés qui exposent des collections de contrôles natifs sur les documents et les feuilles de calcul.Vous ne pouvez pas accéder aux contrôles managés à l'aide de ces propriétés.Par exemple, il n'est pas possible d'énumérer chaque contrôle hôte Microsoft.Office.Tools.Word.Bookmark dans un document à l'aide de la propriété Bookmarks d'un Microsoft.Office.Interop.Word.Document ou la propriété Bookmarks d'un Microsoft.Office.Tools.Word.Document.Ces propriétés incluent uniquement les contrôles Microsoft.Office.Interop.Word.Bookmark du document ; elles ne contiennent pas les contrôles hôtes Microsoft.Office.Tools.Word.Bookmark du document.