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

Article
08/10/2011

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 2007, Excel 2010, Word 2007 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.

Notes

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, il existe deux cas dans lesquels vous devez utiliser la propriété InnerObject du contrôle hôte pour le passer à une méthode ou propriété :

Lorsque la méthode ou la propriété attend l'objet Excel sous-jacent.
Lorsque Microsoft.Office.Tools.Excel.ExcelLocale1033Attribute a la valeur false dans un projet qui cible le .NET Framework 3.5 et la méthode ou la propriété attend un Object au lieu de l'objet Excel sous-jacent. Pour plus d'informations sur le Microsoft.Office.Tools.Excel.ExcelLocale1033Attribute, consultez Mise en forme de données dans Excel avec différents paramètres régionaux.

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", missing].Value2 = "Monday";
this.Range["A2", missing].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.

Accès aux nouveaux membres d'Excel 2010 et de Word 2010 dans les projets ciblant le .NET Framework 3.5

Dans les projets Excel 2010 et Word 2010 qui ciblent le .NET Framework 3.5, les membres introduits dans la version Office 2010 ne sont pas disponibles dans les éléments et les contrôles hôtes. Dans ces projets, les éléments et les contrôles hôtes possèdent uniquement les membres qui étaient disponibles dans la version 2007 de Microsoft Office System. Pour accéder à l'un des nouveaux membres ajoutés à Excel 2010 ou Word 2010, utilisez la propriété InnerObject du contrôle hôte pour retourner l'objet natif sous-jacent, puis accédez au membre de cet objet.

Par exemple, dans Word 2010, les objets Microsoft.Office.Interop.Word.ContentControl ont une propriété Checked qui peut être utilisée pour déterminer si un contrôle de contenu de case à cocher est sélectionné (cette propriété n'est pas disponible dans Word 2007 car il ne possède pas ces contrôles de contenu de case à cocher). Dans les projets Word 2010 qui ciblent le .NET Framework 3.5, le contrôle hôte Microsoft.Office.Tools.Word.ContentControl n'a pas de propriété Checked. L'exemple de code suivant montre comment utiliser la propriété InnerObject pour accéder à la propriété Checked de l'objet Microsoft.Office.Interop.Word.ContentControl sous-jacent.

Me.Paragraphs(1).Range.InsertParagraphBefore()
Me.Paragraphs(1).Range.Select()
Dim checkBoxControl1 As Microsoft.Office.Tools.Word.ContentControl =
    Me.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox)

' The following line of code compiles in projects that target the .NET Framework 4, but it does not compile 
' in projects that target the .NET Framework 3.5.
checkBoxControl1.Checked = True

' In projects that target the .NET Framework 3.5, use the following code.
checkBoxControl1.InnerObject.Checked = True

this.Paragraphs[1].Range.InsertParagraphBefore();
this.Paragraphs[1].Range.Select();
Microsoft.Office.Tools.Word.ContentControl checkBoxControl1 = 
    this.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox);

// The following line of code compiles in projects that target the .NET Framework 4, but it does not compile 
// in projects that target the .NET Framework 3.5.
checkBoxControl1.Checked = true;

// In projects that target the .NET Framework 3.5, use the following code.
checkBoxControl1.InnerObject.Checked = true;