Procédure pas à pas : liaison de contrôles de contenu à des parties XML personnalisées

Article
08/10/2011

Cette procédure pas à pas montre comment lier des contrôles de contenu dans une personnalisation au niveau du document pour Word à des données XML stockées dans ce document.

S'applique à : Les informations contenues dans cette rubrique s'appliquent aux projets de niveau document pour Word 2007 et Word 2010. Pour en savoir plus, consultez Fonctionnalités disponibles par type d'application et de projet Office.

Word vous permet de stocker des données XML, appelées parties XML personnalisées, dans un document. Vous pouvez déterminer l'affichage de ces données en liant des contrôles de contenu à des éléments d'une partie XML personnalisée. L'exemple de document présenté dans cette procédure affiche des informations sur les employés stockées dans une partie XML personnalisée. Lorsque vous ouvrez le document, le contenu détermine l'affichage des valeurs des éléments XML. Toutes les modifications apportées au texte dans les contrôles de contenu sont enregistrées dans la partie XML personnalisée.

Cette procédure pas à pas décrit les tâches suivantes :

Ajout de contrôles de contenu au document Word dans un projet au niveau du document au moment du design.
Création d'un fichier de données XML et d'un schéma XML qui définit les éléments à lier aux contrôles de contenu.
Liaison du schéma XML au document au moment du design.
Ajout du contenu du fichier XML à une partie XML personnalisée dans le document au moment de l'exécution.
Liaison des contrôles de contenu aux éléments de la partie XML personnalisée.
Liaison de DropDownListContentControl à un jeu de valeurs définies dans le schéma XML.

Notes

Il est possible que votre ordinateur affiche des noms ou des emplacements différents pour certains des éléments d'interface utilisateur de Visual Studio dans les instructions suivantes. L'édition de Visual Studio dont vous disposez et les paramètres que vous utilisez déterminent ces éléments. Pour plus d'informations, consultez Paramètres Visual Studio.

Composants requis

Pour exécuter cette procédure pas à pas, vous devez disposer des composants suivants :

Une édition de Visual Studio 2010 qui inclut les outils de développement Microsoft Office. Pour plus d'informations, consultez [Configuration d'un ordinateur pour développer des solutions Office](bb398242\(v=vs.100\).md).

Microsoft Office Word 2007 ou Word 2010.

lien vers la vidéo Pour obtenir une version vidéo de cette rubrique, consultez la page Vidéo Comment : Lier des contrôles de contenu à des parties XML personnalisées (éventuellement en anglais).

Création d'un projet de document Word

Créez un document Word que vous utiliserez dans le cadre de cette procédure pas à pas.

Pour créer un projet de document Word

Créez un projet de document Word et appelez-le EmployeeControls. Créez un document pour la solution. Pour plus d'informations, consultez Comment : créer des projets Office dans Visual Studio.

Visual Studio ouvre le nouveau document Word dans le concepteur et ajoute le projet EmployeeControls à l'Explorateur de solutions.

Ajout de contrôles de contenu au document

Créez un tableau contenant trois types différents de contrôles de contenu où l'utilisateur peut afficher ou modifier des informations à propos d'un employé.

Pour ajouter des contrôles de contenu au document

Dans le document Word hébergé dans le concepteur Visual Studio, sur le ruban, cliquez sur l'onglet Insertion.
Dans le groupe Tableaux, cliquez sur Tableau, puis insérez un tableau comportant 2 colonnes et 3 lignes.
Tapez du texte dans la première colonne de manière à obtenir quelque chose qui ressemble à ceci :

Nom de l'employé

Date d'embauche

Titre
Dans la deuxième colonne du tableau, cliquez sur la première ligne (en regard de Nom de l'employé).
Dans le ruban, cliquez sur l'onglet Développeur.

Notes

Si l'onglet Développeur n'est pas visible, vous devez d'abord l'afficher. Pour plus d'informations, consultez Comment : afficher l'onglet Développeur sur le ruban.
Dans le groupe Contrôles, cliquez sur le bouton Texte pour ajouter PlainTextContentControl à la première cellule.
Dans la deuxième colonne du tableau, cliquez sur la deuxième ligne (en regard de Date d'embauche).
Dans le groupe Contrôles, cliquez sur le bouton Sélecteur de dates pour ajouter DatePickerContentControl à la deuxième cellule.
Dans la deuxième colonne du tableau, cliquez sur la troisième ligne (en regard de Titre).
Dans le groupe Contrôles, cliquez sur le bouton Liste déroulante pour ajouter DropDownListContentControl à la dernière cellule.

Vous disposez à présent de l'interface utilisateur entière pour ce projet. Si vous exécutez le projet maintenant, vous pouvez taper du texte dans la première ligne et sélectionner une date dans la deuxième ligne. L'étape suivante consiste à lier les données à afficher au document dans un fichier XML.

Création du fichier de données XML

En général, vous obtenez des données XML à stocker dans une partie XML personnalisée d'une source externe, telle qu'un fichier ou une base de données. Dans cette procédure pas à pas, vous créez un fichier XML qui contient les données d'employé, accompagnées des éléments que vous souhaitez lier aux contrôles de contenu du document. Pour que les données soient disponibles pendant l'exécution, incorporez le fichier XML en tant que ressource dans l'assembly de personnalisation.

Pour créer le fichier de données

Dans le menu Projet, cliquez sur Ajouter un nouvel élément.

La boîte de dialogue Ajouter un nouvel élément s'affiche alors.
Dans le volet Modèles, sélectionnez Fichier XML.
Nommez le fichier employés.xml, puis cliquez sur Ajouter.

Le fichier employés.xml s'ouvre dans l'Éditeur de code.

Remplacez le contenu du fichier employés.xml par le texte ci-dessous.

<?xml version="1.0" encoding="utf-8" ?>
<employees xmlns="https://schemas.microsoft.com/vsto/samples">
  <employee>
    <name>Karina Leal</name>
    <hireDate>1999-04-01</hireDate>
    <title>Manager</title>
  </employee>
</employees>

Dans l'Explorateur de solutions, cliquez sur employés.xml.
Dans la fenêtre Propriétés, sélectionnez la propriété Action de génération, puis remplacez la valeur par Ressource incorporée.

Cette étape incorpore le fichier XML en tant que ressource dans l'assembly lorsque vous générez le projet. Vous pouvez ainsi accéder au contenu du fichier XML au moment de l'exécution.

Création d'un schéma XML

Si vous souhaitez lier un contrôle de contenu à un élément d'une partie XML personnalisée, vous ne devez pas utiliser de schéma XML. Toutefois, pour lier DropDownListContentControl à un jeu de valeurs, vous devez créer un schéma XML qui valide le fichier de données XML créé précédemment. Le schéma XML définit les valeurs possibles pour l'élément title. À une étape ultérieure de cette procédure, vous lierez DropDownListContentControl à cet élément.

Pour créer un schéma XML

Dans le menu Projet, cliquez sur Ajouter un nouvel élément.

La boîte de dialogue Ajouter un nouvel élément s'affiche alors.
Dans le volet Modèles, sélectionnez Schéma XML.
Nommez le schéma employés.xsd, puis cliquez sur Ajouter.

Le concepteur de schéma s'ouvre.
Dans l'Explorateur de solutions, cliquez avec le bouton droit sur employés.xsd, puis cliquez sur Afficher le code.

Remplacez le contenu du fichier employés.xsd par le schéma suivant.

<?xml version="1.0" encoding="utf-8" ?>
<xs:schema xmlns="https://schemas.microsoft.com/vsto/samples" 
    targetNamespace="https://schemas.microsoft.com/vsto/samples"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    elementFormDefault="qualified">
  <xs:element name="employees" type="EmployeesType"></xs:element>
  <xs:complexType name="EmployeesType">
    <xs:all>
      <xs:element name="employee" type="EmployeeType"/>
    </xs:all>
  </xs:complexType>
  <xs:complexType name="EmployeeType">
    <xs:sequence>
      <xs:element name="name" type="xs:string" minOccurs="1" maxOccurs="1"/>
      <xs:element name="hireDate" type="xs:date" minOccurs="1" maxOccurs="1"/>
      <xs:element name="title" type="TitleType" minOccurs="1" maxOccurs="1"/>
    </xs:sequence>
  </xs:complexType>
  <xs:simpleType name="TitleType">
    <xs:restriction base="xs:string">
      <xs:enumeration value ="Engineer"/>
      <xs:enumeration value ="Designer"/>
      <xs:enumeration value ="Manager"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

Dans le menu Fichier, cliquez sur Enregistrer tout pour enregistrer les modifications apportées aux fichiers employés.xml et employés.xsd.

Liaison du schéma XML au document

Vous devez joindre le schéma XML au document afin de lier DropDownListContentControl aux valeurs valides de l'élément title.

Pour joindre le schéma XML au document

Activez ContrôlesEmployé.docx dans le concepteur.
Dans le ruban, cliquez sur l'onglet Développeur.
Dans le groupe XML, cliquez sur Schéma.
Dans la boîte de dialogue Modèles et compléments, cliquez sur l'onglet Schéma XML, puis sur Ajouter un schéma.
Accédez au schéma employés.xsd créé précédemment et situé dans le répertoire du projet, puis cliquez sur Ouvrir.
Cliquez sur OK dans la boîte de dialogue Paramètres du schéma.
Cliquez sur OK pour fermer la boîte de dialogue Modèles et compléments.

Le volet de tâches Structure XML s'affiche.
Fermez le volet de tâches Structure XML.

Ajout d'une partie XML personnalisée au document

Pour lier les contrôles de contenu aux éléments du fichier XML, vous devez d'abord ajouter le contenu du fichier XML à une nouvelle partie XML personnalisée dans le document.

Pour ajouter une partie XML personnalisée au document

Dans l'Explorateur de solutions, cliquez avec le bouton droit sur ThisDocument.cs ou ThisDocument.vb, puis sélectionnez Afficher le code.

Ajoutez les déclarations suivantes à la classe ThisDocument. Ce code déclare plusieurs objets servant à ajouter une partie XML personnalisée au document.

<Cached()> _
Public employeeXMLPartID As String = String.Empty
Private employeeXMLPart As Office.CustomXMLPart
Private Const prefix As String = "xmlns:ns='https://schemas.microsoft.com/vsto/samples'"

[CachedAttribute()]
public string employeeXMLPartID = string.Empty;
private Office.CustomXMLPart employeeXMLPart;
private const string prefix = "xmlns:ns='https://schemas.microsoft.com/vsto/samples'";

Ajoutez la méthode suivante à la classe ThisDocument. Cette méthode extrait le contenu du fichier de données XML incorporé comme ressource dans l'assembly, puis retourne le contenu sous la forme d'une chaîne XML.

Private Function GetXmlFromResource() As String
    Dim asm As System.Reflection.Assembly = _
        System.Reflection.Assembly.GetExecutingAssembly()
    Dim stream1 As System.IO.Stream = asm.GetManifestResourceStream( _
            "EmployeeControls.employees.xml")

    Using resourceReader As System.IO.StreamReader = _
        New System.IO.StreamReader(stream1)
        If resourceReader IsNot Nothing Then
            Return resourceReader.ReadToEnd()
        End If
    End Using

    Return Nothing
End Function

private string GetXmlFromResource()
{
    System.Reflection.Assembly asm =
        System.Reflection.Assembly.GetExecutingAssembly();
    System.IO.Stream stream1 = asm.GetManifestResourceStream(
        "EmployeeControls.employees.xml");

    using (System.IO.StreamReader resourceReader =
            new System.IO.StreamReader(stream1))
    {
        if (resourceReader != null)
        {
            return resourceReader.ReadToEnd();
        }
    }

    return null;
}

Ajoutez la méthode suivante à la classe ThisDocument. La méthode AddCustomXmlPart crée une partie XML personnalisée qui contient une chaîne XML passée à la méthode.

Pour garantir que la partie XML personnalisée n'est créée qu'une seule fois, la méthode crée cette partie uniquement si aucune partie XML personnalisée comportant un GUID correspondant n'existe dans le document. Lors de son premier appel, cette méthode enregistre la valeur de la propriété Id dans la chaîne employeeXMLPartID. La valeur de la chaîne employeeXMLPartID est rendue persistante dans le document car elle a été déclarée à l'aide de l'attribut CachedAttribute.

Private Sub AddCustomXmlPart(ByVal xmlData As String)
    If xmlData IsNot Nothing Then

        employeeXMLPart = Me.CustomXMLParts.SelectByID(employeeXMLPartID)
        If (employeeXMLPart Is Nothing) Then
            employeeXMLPart = Me.CustomXMLParts.Add(xmlData)
            employeeXMLPart.NamespaceManager.AddNamespace("ns", _
                "https://schemas.microsoft.com/vsto/samples")
            employeeXMLPartID = employeeXMLPart.Id
        End If
    End If
End Sub

private void AddCustomXmlPart(string xmlData)
{
    if (xmlData != null)
    {
        employeeXMLPart = this.CustomXMLParts.SelectByID(employeeXMLPartID);
        if (employeeXMLPart == null)
        {
            employeeXMLPart = this.CustomXMLParts.Add(xmlData, missing);
            employeeXMLPart.NamespaceManager.AddNamespace("ns", 
                @"https://schemas.microsoft.com/vsto/samples");
            employeeXMLPartID = employeeXMLPart.Id;
        }
    }
}

Liaison des contrôles de contenu aux éléments de la partie XML personnalisée

Liez chaque contrôle de contenu à un élément de la partie XML personnalisée à l'aide de la propriété XMLMapping de chaque contrôle de contenu.

Pour lier les contrôles de contenu aux éléments de la partie XML personnalisée

Ajoutez la méthode suivante à la classe ThisDocument. Cette méthode lie chaque contrôle de contenu à un élément de la partie XML personnalisée et définit le format d'affichage de la date de DatePickerContentControl.

Private Sub BindControlsToCustomXmlPart()
    Dim xPathName As String = "ns:employees/ns:employee/ns:name"
    Me.PlainTextContentControl1.XMLMapping.SetMapping(xPathName, _
        prefix, employeeXMLPart)

    Dim xPathDate As String = "ns:employees/ns:employee/ns:hireDate"
    Me.DatePickerContentControl1.DateDisplayFormat = "MMMM d, yyyy"
    Me.DatePickerContentControl1.XMLMapping.SetMapping(xPathDate, _
        prefix, employeeXMLPart)

    Dim xPathTitle As String = "ns:employees/ns:employee/ns:title"
    Me.DropDownListContentControl1.XMLMapping.SetMapping(xPathTitle, _
        prefix, employeeXMLPart)
End Sub

private void BindControlsToCustomXmlPart()
{
    string xPathName = "ns:employees/ns:employee/ns:name";
    this.plainTextContentControl1.XMLMapping.SetMapping(xPathName,
        prefix, employeeXMLPart);

    string xPathDate = "ns:employees/ns:employee/ns:hireDate";
    this.datePickerContentControl1.DateDisplayFormat = "MMMM d, yyyy";
    this.datePickerContentControl1.XMLMapping.SetMapping(xPathDate,
        prefix, employeeXMLPart);

    string xPathTitle = "ns:employees/ns:employee/ns:title";
    this.dropDownListContentControl1.XMLMapping.SetMapping(xPathTitle,
        prefix, employeeXMLPart);
}

Exécution du code à l'ouverture du document

Créez la partie XML personnalisée et liez les contrôles personnalisés aux données lorsque le document est ouvert.

Pour exécuter le code à l'ouverture du document

Ajoutez le code suivant à la méthode ThisDocument_Startup de la classe ThisDocument. Ce code extrait la chaîne XML du fichier employés.xml, ajoute la chaîne XML à une nouvelle partie XML personnalisée du document, puis lie les contrôles de contenu aux éléments de la partie XML personnalisée.
```
Dim xmlData As String = GetXmlFromResource()
If xmlData IsNot Nothing Then
    AddCustomXmlPart(xmlData)
    BindControlsToCustomXmlPart()
End If
```
```
string xmlData = GetXmlFromResource();

if (xmlData != null)
{
    AddCustomXmlPart(xmlData);
    BindControlsToCustomXmlPart();
}
```

Test du projet

Lorsque vous ouvrez le document, les contrôles de contenu affichent les données issues des éléments de la partie XML personnalisée. Cliquez sur DropDownListContentControl pour sélectionner l'une de trois valeurs valides pour l'élément title, définies dans le fichier employés.xsd. Si vous modifiez les données d'un contrôle de contenu, les nouvelles valeurs sont enregistrées dans la partie XML personnalisée du document.

Pour tester les contrôles de contenu

Appuyez sur F5 pour exécuter le projet.
Assurez-vous que le tableau du document se présente comme suit. Chaque chaîne de la deuxième colonne dérive d'un élément de la partie XML personnalisée dans le document.

Nom de l'employé

Karina Leal

Date d'embauche

1 avril 1999

Titre

Manager
Cliquez dans la cellule à droite de Nom de l'employé et tapez un autre nom.
Cliquez dans la cellule à droite de Date d'embauche et sélectionnez une autre date dans le sélecteur de dates.
Cliquez dans la cellule à droite de la cellule Titre et sélectionnez un nouvel élément dans la liste déroulante.
Enregistrez et fermez le document.
Dans l'Explorateur Windows, ouvrez le dossier \bin\Debug situé dans l'emplacement du projet.
Cliquez avec le bouton droit sur EmployeeControls.docx, puis cliquez sur Renommer.
Attribuez le nom ContrôlesEmployé.docx.zip au fichier.

Le document ContrôlesEmployé.docx est enregistré au format Open XML. Si vous renommez ce document en lui ajoutant l'extension de nom de fichier .zip, vous pouvez examiner le contenu du document. Pour plus d'informations sur Open XML, consultez l'article technique Présentation des formats de fichier Open XML Microsoft Office (2007).
Double-cliquez sur le fichier ContrôlesEmployé.docx.zip.
Double-cliquez sur le dossier customXml.
Cliquez avec le bouton droit sur item2.xml, puis cliquez sur Ouvrir.

Ce fichier contient la partie XML personnalisée que vous avez ajoutée au document.
Vérifiez que les éléments name, hireDate et title contiennent les nouvelles valeurs entrées dans les contrôles de contenu du document.
Fermez le fichier item2.xml.

Étapes suivantes

Pour en savoir plus sur l'utilisation des contrôles de contenu, consultez les rubriques suivantes :

Utiliser tous les contrôles de contenu disponibles pour créer un modèle. Pour plus d'informations, consultez Procédure pas à pas : création d'un modèle à l'aide de contrôles de contenu.
Modifier les données des parties XML personnalisées lorsque le document est fermé. La prochaine fois qu'un utilisateur ouvre le document, les contrôles de contenu liés aux éléments XML affichent les nouvelles données. Pour plus d'informations, consultez Comment : ajouter des parties XML personnalisées à des documents sans démarrer Microsoft Office.
Utiliser les contrôles de contenu pour protéger les parties d'un document. Pour plus d'informations, consultez Comment : protéger des parties de documents à l'aide de contrôles de contenu.