Utilisation des classes XPathNavigator et XPathNodeIterator

Article
05/27/2010

Pour accéder aux données XML dans les sources de données du modèle de formulaire et les manipuler, un grand nombre de membres du modèle objet avec code managé fourni par l'espace de noms Microsoft.Office.InfoPath créent ou se voient attribuer une instance de la classe XPathNavigator de l'espace de noms System.Xml.XPath. Après avoir accédé à un objet XPathNavigator retourné par un membre du modèle objet InfoPath, vous pouvez utiliser les propriétés et les méthodes de la classe XPathNavigator pour travailler avec les données.

Le membre le plus couramment utilisé de l'espace de noms Microsoft.Office.InfoPath qui utilise la classe XPathNavigator est la méthode CreateNavigator de la classe DataSource qui vous permet d'utiliser les données stockées représentées par un objet DataSource. La méthode CreateNavigator crée un objet XPathNavigator placé à la racine de la source de données représentée par l'objet DataSource.

Conseil

Si vous avez l'habitude d'utiliser MSXML5 à partir du script pour travailler avec des données dans Microsoft InfoPath 2003, vous pouvez considérer la méthode CreateNavigator en remplacement de la propriété DOM de l'objet DataObject.

Utilisation de la classe XPathNavigator pour accéder à la source principale de données du formulaire

Pour accéder à la source de données principale du formulaire, appelez la méthode CreateNavigator directement depuis le mot clé this (C#) ou Me (Visual Basic). L’exemple suivant crée un objet XPathNavigator placé à la racine de la source de données principale à l'aide de la méthode CreateNavigator, puis utilise la propriété OuterXml de la classe XPathNavigator pour afficher le code XML retourné dans une zone de message.

XPathNavigator myNavigator = 
   this.CreateNavigator();
MessageBox.Show("Main data source XML: " +
   myNavigator.OuterXml.ToString());

Dim myNavigator As XPathNavigator  = _
   Me.CreateNavigator()
MessageBox.Show("Main data source XML: " & _
   myNavigator.OuterXml.ToString())

Notes

L’appel à la méthode CreateNavigator directement depuis le mot clé this ou Me équivaut à appeler la méthode CreateNavigator à l’aide de la propriété MainDataSource (this.MainDataSource.CreateNavigator()) ou à passer une chaîne vide à la propriété DataSources de la classe XmlForm (this.DataSources[""].CreateNavigator()).

Sélection et définition de nœuds XML pour les champs de la source de données principale

Pour sélectionner un nœud XML unique pour champ de la source de données, utilisez la méthode SelectSingleNode(String,IXmlNamespaceResolver) de la classe XPathNavigator. Si vous voulez utiliser un jeu de champs récurrents ou de groupes récurrents, utilisez la méthode Select(String,IXmlNamespaceResolver) de la classe XPathNavigator. Cette méthode retourne un objet XPathNodeIterator qui représente une collection de nœuds.

Sélection et définition de la valeur d’un nœud unique

La méthode surchargée SelectSingleNode que vous devez utiliser comprend un paramètre xpath qui prend une expression XPath sous forme de chaîne et un paramètre resolver qui prend l’objet XmlNamespaceManager pour résoudre les préfixes d’espaces de noms. Pour sélectionner un nœud unique dans la source de données principale du formulaire, transmettez une expression XPath qui spécifie le champ ou groupe que vous voulez sélectionner pour le paramètre xpath, avec l’objet XmlNamespaceManager qui est retourné par la propriété NamespaceManager de l’objet XmlForm. L’objet XmlNamespaceManager retourné est initialisé lors du chargement avec tous les espaces de noms définis par le fichier de définition de formulaire du modèle de formulaire (.xsf).

Conseil

La façon la plus simple de créer une expression XPath pour sélectionner un nœud dans la source de données du formulaire est de cliquer avec le bouton droit sur le champ ou sur le groupe dans le volet Office Champs, puis de cliquer sur Copier XPath. Pour créer et tester des expressions XPath modifiées manuellement pour accéder à des nœuds dans un schéma XML complexe ou fortement imbriqué, ajoutez un contrôle Zone d’expression au formulaire, spécifiez l’expression XPath du contrôle, puis affichez l’aperçu du formulaire pour afficher les résultats.

L’exemple qui suit utilise la méthode SelectSingleNode pour sélectionner le nœud unique du champ EmailAlias. Il utilise ensuite la méthode SetValue de la classe XPathNavigator et la propriété UserName de la classe User pour définir la valeur du champ sur celle de l’alias de l’utilisateur actuel.

XPathNavigator emailAlias = 
   this.CreateNavigator().SelectSingleNode(
      "/my:myFields/my:EmailAlias", NamespaceManager);
emailAlias.SetValue(this.Application.User.UserName.ToString());

Dim emailAlias As XPathNavigator = _
   Me.CreateNavigator().SelectSingleNode( _
      "/my:myFields/my:EmailAlias", NamespaceManager)
emailAlias.SetValue(Me.Application.User.UserName.ToString())

Pour plus d'informations sur la création d’expressions XPath, voir XPath Reference (éventuellement en anglais) sur MSDN, ainsi que les recommandations du W3C sur le langage XML Path (XPath) Version 1.0 (éventuellement en anglais).

Définition de la valeur d’un nœud qui possède l’attribut xsi:nil

Pour certains types de données, le fait de définir une valeur nulle par programme génère l’erreur « La validation de schéma a détecté des erreurs qui ne concernent pas le type de données ». En général, la cause de cette erreur est que l’attribut xsi:nil (éventuellement en anglais) de l’élément est défini sur true. Si vous examinez l’élément XML sous-jacent du champ vierge du formulaire, vous verrez ce paramètre. Par exemple, l’attribut xsi:nil du fragment XML du champ Date vierge suivant est défini sur true.

<my:myDate xsi:nil="true"></my:myDate>

Si l’attribut xsi:nil est défini sur true, il indique que l’élément est présent mais n’a pas de valeur, en d’autres termes est null. Si vous essayez de définir la valeur d’un tel nœud par programme, InfoPath affiche l’erreur « La validation de schéma a détecté des erreurs qui ne concernent pas le type de données. », car l’élément est signalé comme null. InfoPath définit l’attribut xsi:nil sur true pour les champs null des types de données suivants :

Whole Number (integer)
Decimal (double)
Date (date)
Time (time)
Date and Time (dateTime)

Pour empêcher cette erreur, votre code doit rechercher la présence de l’attribut xsi:nil. S’il est présent, supprimez-le avant de définir la valeur du nœud. La sous-routine qui suit prend un objet XpathNavigator placé sur le nœud que vous souhaitez définir, recherche l’attribut nil et le supprime s’il existe.

public void DeleteNil(XPathNavigator node)
{
   if (node.MoveToAttribute(
      "nil", "http://www.w3.org/2001/XMLSchema-instance"))
      node.DeleteSelf();
}

Public Sub DeleteNil(ByVal node As XPathNavigator)
   If (node.MoveToAttribute( _
      "nil", "http://www.w3.org/2001/XMLSchema-instance")) Then
      node.DeleteSelf()
   End If
End Sub

Vous pouvez appeler cette sous-routine avant d’essayer de définir un champ d’un type de données qui peut avoir l’attribut xsi:nil, comme présenté dans l’exemple ci-dessous, qui définit un champ Date.

// Access the main data source.
XPathNavigator myForm = this.CreateNavigator();

// Select the field.
XPathNavigator myDate = myForm.SelectSingleNode("/my:myFields/my:myDate", NamespaceManager);

// Check for and remove the "nil" attribute.
DeleteNil(myDate);

// Build the current date in the proper format. (yyyy-mm-dd)
string curDate = DateTime.Today.Year + "-" + DateTime.Today.Month + 
   "-" + DateTime.Today.Day;

// Set the value of the myDate field.
myDate.SetValue(strCurDate);

' Access the main data source.
Dim myForm As XPathNavigator = Me.CreateNavigator()

' Select the field.
Dim myDate As XPathNavigator = _
   myForm.SelectSingleNode("/my:myFields/my:myDate", NamespaceManager)

' Check for and remove the "nil" attribute.
DeleteNil(myDate)

' Build the current date in the proper format. (yyyy-mm-dd)
Dim curDate As String = DateTime.Today.Year + "-" + _
   DateTime.Today.Month + "-" + DateTime.Today.Day

' Set the value of the myDate field.
myDate.SetValue(strCurDate)

Notes

Bien que l’implémentation de l’objet XPathNavigator dans InfoPath expose la méthode SetTypedValue, qui est utilisée pour définir un nœud à l’aide d’une valeur de type spécifique, InforPath n’utilise pas cette méthode. Vous devez utiliser la méthode SetValue, et transmettre une valeur de chaîne au format correct pour le type de données du nœud.

Sélection et définition d’un jeu de nœuds récurrents

Pour spécifier des champs ou des groupes récurrents dont le nombre n’est pas déterminé, utilisez la méthode Select de la classe XPathNavigator. Cette méthode retourne un objet XPathNodeIterator que vous pouvez utiliser pour parcourir la collection de nœuds.

Dans l’exemple suivant, votre modèle de formulaire contient une Liste à puces ou un autre contrôle récurrent qui est lié à un élément récurrent appelé field1. Le XPath de ce champ est transmis à la méthode Select et la valeur XPathNodeIterator retournée est affectée à la variable nodes. Vous pouvez utiliser la méthode MoveNext pour parcourir la collection de nœuds et la propriété Current pour retourner un objet XPathNavigator placé sur le nœud actif. Enfin, utilisez la propriété Value pour récupérer et afficher la valeur de chaque champ récurrent.

string message = String.Empty;
XPathNavigator root = this.CreateNavigator();
XPathNodeIterator nodes = 
   root.Select("/my:myFields/my:group1/my:field1", NamespaceManager);

while (nodes.MoveNext())
{
    message += nodes.Current.Value + System.Environment.NewLine;
}
MessageBox.Show(message);

Dim message As String = String.Empty
Dim root As XPathNavigator = Me.CreateNavigator()
Dim nodes As XPathNodeIterator = _
   root.Select("/my:myFields/my:group1/my:field1", NamespaceManager)

Do While nodes.MoveNext
    message += nodes.Current.Value & System.Environment.NewLine
Loop

MessageBox.Show(message)

L’exemple qui précède fonctionne avec des valeurs de chaîne dans le champ récurrent spécifié. Cependant, si ce champ contient des valeurs numériques, vous pouvez utiliser un code similaire pour parcourir les valeurs du champ et effectuer des opération, par exemple le calcul du total ou de la moyenne des valeurs.

De même, plutôt que d’utiliser la propriété Value pour récupérer la valeur de chaque instance du champ récurrent, vous pouvez utiliser la méthode SetValue pour parcourir les champs et en définir les valeurs, comme illustré dans l’exemple qui suit.

XPathNavigator root = this.CreateNavigator();
XPathNodeIterator nodes = 
   root.Select("/my:myFields/my:group1/my:field1", NamespaceManager);
int myInt = 1;
while (nodes.MoveNext())
{
   nodes.Current.SetValue(myInt.ToString());
   myInt = myInt + 1;
}

Dim root As XPathNavigator = Me.CreateNavigator()
Dim nodes As XPathNodeIterator = _
   root.Select("/my:myFields/my:group1/my:field1", NamespaceManager)
Dim myInt As Integer = 1
Do While nodes.MoveNext
   nodes.Current.SetValue(myInt.ToString())
   myInt = myInt + 1
Loop

Utilisation de la classe XPathNavigator pour accéder à une source de données externe

Pour accéder à une source de données externe associée au formulaire, envoyez le nom de la source de données à la propriété DataSources de la classe XmlForm. Pour créer une connexion à une autre source de données externe, ou pour voir la liste des noms des connexions de sources de données existantes, cliquez sur Connexions de données dans l’onglet Données du Ruban.

L'exemple de code suivant illustre la création d'un objet XPathNavigator placé à la racine d'une source de données externe nommée CityList (Liste des villes) à l'aide de la méthode CreateNavigator, puis l'utilisation de la propriété OuterXml de la classe XPathNavigator pour afficher le code XML retourné dans une zone de message.

XPathNavigator myNavigator = 
   this.DataSources["CityList"].CreateNavigator();
MessageBox.Show("External data source XML: " + 
   myNavigator.OuterXml.ToString());

Dim myNavigator As XPathNavigator  = _
   Me.DataSources("CityList").CreateNavigator()
MessageBox.Show("External data source XML: " & _
   myNavigator.OuterXml.ToString())

Une fois que vous avez accédé à l’objet XPathNavigator placé à la racine de la source de données externe, vous pouvez utiliser les membres de la classe XPathNavigator tels que les méthodes SelectSingleNode et SetValue pour utiliser les données.

Membres du modèle objet InfoPath qui utilisent les classes XPathNavigator et XPathNodeIterator

Le tableau suivant recense les membres de l'espace de noms Microsoft.Office.InfoPath qui utilisent la classe XPathNavigator pour accéder aux données XMSL, les manipuler ou les envoyer.

Classe parent	Membre
AdoQueryConnection	Méthode BuildSqlFromXmlNodes
AdoSubmitConnection	Méthode BuildSqlFromXmlNodes
ClickedEventArgs	Propriété Source
ContextChangedEventArgs	Propriété Context
DataSource	Méthode CreateNavigator
	Méthode GetNamedNodeProperty
	Méthode SetNamedNodeProperty
EmailSubmitConnection	Méthode Execute
FileQueryConnection	Méthode Execute
FileSubmitConnection	Méthode Execute
FormError	Propriété Site
FormErrorCollection	Méthodes Add
FormTemplate	Propriété Manifest
MergeEventArgs	Propriété Xml
SharepointListQueryConnection	Méthode Execute
Signature	Propriété SignatureBlockXmlNode
SignedDataBlock	Propriété SignatureContainer
View	Méthodes GetContextNodes
	Méthodes SelectNodes
	Méthodes SelectText
WebServiceConnection	Méthode Execute
	Méthode GenerateDataSetDiffGram
XmlEventArgs	Propriété OldParent
	Propriété Site
XmlForm	Propriété MainDataSource qui retourne un objet DataSource qui à son tour fournit la méthode CreateNavigator permettant de créer un objet XPathNavigator placé à la racine du document XML sous-jacent du formulaire (source de données principale).
	Méthode MergeForm
XmlFormCollection	Méthode NewFromFormTemplate
XmlValidatingEventArgs	Méthodes ReportError

Outre les membres du modèle objet InfoPath qui retournent ou acceptent un objet XPathNavigator, les méthodes suivantes retournent une instance de la classe XPathNodeIterator de l'espace de noms System.Xml.XPath pour parcourir les nœuds XML des éléments qui sont spécifiés ou sélectionnés dans un affichage.

Classe parent	Membre
View	Méthodes GetContextNodes
	Méthode GetSelectedNodes