Procédure : lire la valeur d’un champ d’un élément de liste
Dernière modification : vendredi 16 avril 2010
S’applique à : SharePoint Foundation 2010
Dans cet article
Présentation
Obtention d’une référence à une liste
Obtention d’une référence à un élément de liste
Obtention de la valeur d’un champ
Cette rubrique explique comment lire par programme la valeur d’un champ (colonne) spécifique d’un élément de liste donné.
Présentation
Pour lire la valeur d’un champ spécifique d’un élément de liste, votre code doit d’abord obtenir une référence au site Web sur lequel la liste est déployée, puis une référence à la liste elles-même, et enfin une référence au champ spécifique. Cette rubrique se concentre sur les trois dernières étapes, plus particulièrement sur la toute dernière. Pour plus d’informations sur l’obtention de références aux sites Web, voir Obtention de références aux sites, applications Web et autres objets clés.
Obtention d’une référence à une liste
Après avoir eu une référence au site Web qui contient la liste, vous obtenez une référence à la liste en appelant la méthode GetList(String) de l’objet SPWeb ou en utilisant un index de la propriété SPWeb.Lists du site Web. Pour utiliser la méthode GetList(String), votre code doit pouvoir passer l’URL relative de serveur de la liste à l’exécution. L’exemple suivant illustre l’utilisation de cette méthode quand l’URL relative de serveur littérale est connue au moment du design.
using (SPSite siteCol = new SPSite("https://server/sites/Contoso"))
{
using (SPWeb web = siteCol.RootWeb)
{
SPList list = web.GetList("/sites/Contoso/Lists/Books");
}
}
Pour plus d’informations sur les URL relatives de serveur, voir Description des formes de chaînes d’URL.
Il existe trois types d’index que vous pouvez utiliser avec la propriété SPWeb.Lists.
Le GUID de la liste ; par exemple, SPList list = web.Lists[new Guid("53bd7850-49cc-4747-aded-e053659ace79")];. Le GUID est la valeur de la propriété SPList.ID.
L’emplacement ordinal de base zéro de la liste de la collection Lists ; par exemple, SPList list = web.Lists[12];.
Le nom de la liste ; par exemple, SPList list = web.Lists["Books"];. Le nom est la valeur de la propriété SPList.Title.
Ce dernier index est le plus courant, parce qu’il est relativement rare que vous connaissiez au moment du design, ou que votre code « connaisse » à l’exécution, le GUID de la liste ou sa position dans la collection de listes du site Web. L’exemple suivant illustre cette technique en contexte.
using (SPSite siteCol = new SPSite("https://server/sites/Contoso"))
{
using (SPWeb web = siteCol.RootWeb)
{
SPList list = web.Lists["Books"];
}
}
.gif "Conseil") Conseil |
|---|
Dans Microsoft SharePoint Foundation, si une méthode « Get » est disponible pour retourner un type particulier d’objet, vous devez l’utiliser de préférence à un index de collection. En règle générale, vous obtiendrez de meilleures performances en respectant cette règle. Dans ce cas, si votre code peut transmettre l’URL relative de serveur de la liste à l’exécution, utilisez la méthode GetList(String) de préférence à un index de la propriété SPWeb.Lists. |
Obtention d’une référence à un élément de liste
Après avoir obtenu une référence à la liste, vous avez plusieurs choix pour vous procurer une référence à un élément de liste particulier. Pour obtenir les meilleures performances, le choix privilégié est d’utiliser la méthode GetItemByIdSelectedFields(Int32, []) de l’objet SPList. Le premier paramètre est le numéro d’ID de l’élément. Chaque fois qu’un élément est ajouté à une liste, il se voit attribuer un ID entier de base 1, qui est une fois plus grand que l’ID du précédent élément ajouté. Quand un élément est supprimé d’une liste, son numéro d’ID n’est pas réutilisé. Le deuxième paramètre est un tableau des noms internes des champs de l’élément que vous voulez vous voir retourner depuis la base de données de contenu. Pour optimiser les performances, incluez seulement les champs de l’élément de liste auquel votre code fera référence ultérieurement. Voici un exemple.
using (SPSite siteCol = new SPSite("https://server/sites/Contoso"))
{
using (SPWeb web = siteCol.RootWeb)
{
SPList list = web.GetList("/sites/Contoso/Lists/Books");
SPListItem item = list.GetItemByIdSelectedFields(3, "Title", "ISBN", "Retail_x0020_Price");
}
}
Notez que l’élément de liste avec ID 3 est en cours d’obtention, mais que seuls trois de ses champs sont extraits. Notez aussi que c’est la propriété InternalName du champ du prix au détail qui est utilisée, et non la propriété Title du champ, à savoir, dans ce cas, « Retail Price ».
Si vous souhaitez tous les champs de l’élément de liste, utilisez la méthode GetItemByIdAllFields(Int32). Son unique paramètre est l’ID d’élément. Il existe quelques méthodes particulières pour obtenir les éléments de liste de types spéciaux. Si vous connaissez le GUID de l’élément (la valeur de sa propriété UniqueId) plutôt que la valeur de sa propriété ID, utilisez la méthode GetItemByUniqueId(Guid).
Si vous ne connaissez ni le GUID ni l’ID de l’élément de liste, mais que vous connaissez la valeur de certains de ses autres champs ou propriétés, vous pouvez utiliser l’une des surcharges de la méthode GetItems() pour retourner plusieurs éléments de liste, puis recourir à une boucle et à des structures conditionnelles pour sélectionner celle souhaitée. Voici un exemple de cette technique.
using (SPSite siteCol = new SPSite("https://server/sites/Contoso"))
{
using (SPWeb web = siteCol.RootWeb)
{
SPList list = web.GetList("/sites/Contoso/Lists/Books");
SPListItemCollection items = list.GetItems("Title", "ISBN", "Retail_x0020_Price");
SPListItem item = null;
foreach (SPListItem it in items)
{
if (it.Title == "Great Expectations")
{
item = it;
}
}
}
Vous pouvez aussi interroger une liste pour obtenir un ensemble filtré d’éléments à l’aide du fournisseur LINQ to SharePoint. Utilisez la clause select de votre requête LINQ pour ne spécifier que les champs que vous souhaitez. Pour plus d’informations sur l’interrogation de SharePoint avec LINQ, voir Procédure : effectuer des requêtes à l’aide de LINQ to SharePoint.
Important
L’objet SPList possède une propriété Items dont les membres sont accessibles par le biais d’un index, mais nous vous déconseillons cette technique, car elle se traduit par une récupération de toutes les métadonnées de tous les éléments de liste de la base de données de contenu.
Obtention de la valeur d’un champ
Après que vous avez obtenu la référence à l’élément de liste souhaité, votre code peut lire la valeur d’un champ quelconque en utilisant un index de l’objet SPListItem. Il y a les index Guid, Int32 et String. Vous pouvez utiliser l’index Guid si vous connaissez la propriété Id du champ. Vous pouvez utiliser l’index Int32 si vous connaissez le numéro de colonne de base zéro du champ dans la liste parente. Vous pouvez utiliser l’index String si vous connaissez la propriété InternalName, Title ou StaticName du champ. Le runtime recherche d’abord dans la chaîne les noms internes, puis les intitulés des champs, et, enfin, les noms statiques de champs ; ainsi, votre code obtient de meilleures performances si vous utilisez le nom interne lorsque vous le connaissez. Vous trouverez ci-après un exemple de cette technique. Notez que l’indexeur retourne toujours la valeur du champ comme type Object. Vous aurez généralement besoin, comme dans l’exemple, d’effectuer un cast en un type plus spécifique.
using (SPSite siteCol = new SPSite("https://server/sites/Contoso"))
{
using (SPWeb web = siteCol.RootWeb)
{
SPList list = web.GetList("/sites/Contoso/Lists/Books");
SPListItem item = list.GetItemByIdSelectedFields(3, "Title", "ISBN", "Retail_x0020_Price");
String bookISBN = (String)item["ISBN"];
}
}
Si vous voulez la valeur du champ mise en forme pour l’injection dans le code HTML comme valeur d’un élément ou d’un attribut d’un élément, utilisez la méthode SPListItem.GetFormattedValue(String). Elle retourne la valeur comme chaîne, mais si la valeur contient une esperluette, des guillemets doubles, des guillemets simples, le symbole « inférieur à » ou le symbole « supérieur à », ils sont remplacés par les références d’entité HTML appropriées.
La classe SPField elle-même (et, ainsi, chaque classe qui en dérive) possède certaines méthodes pour convertir une valeur de champ de façon particulière. Dans chacune d’elles, vous obtenez d’abord une référence à la valeur du champ en utilisant un index avec l’objet SPListItem, comme décrit ci-dessus. Vous passez cette référence comme paramètre à l’une de ces méthodes ; par exemple, GetFieldValueAsText(item["ISBN"]).
GetFieldValueAsHtml(Object) Fonctionne de manière identique à SPListItem.GetFormattedValue(String). Voir ci-dessus.
GetFieldValueAsText(Object) Renvoie la valeur de champ comme String.
GetFieldValueForEdit(Object) En cas de substitution dans une classe dérivée, renvoie la valeur de champ dans un format plus approprié pour le formulaire d’élément de liste Modifier et le formulaire d’élément de liste Nouveau ; par exemple, une valeur date/heure mise en forme pour la culture de l’utilisateur.
GetValidatedString(Object) En cas de substitution dans une classe dérivée, renvoie une version chaîne de la valeur de champ qui a passé avec succès les contrôles de validation.
GetFieldValue(String) En cas de substitution dans une classe dérivée, obtient la valeur du champ lorsque la valeur sous-jacente possède un type de données complexe tel que SPFieldUrlValue ou un type de données personnalisé.
Pour utiliser l’une de ces méthodes, vous devez obtenir une référence au champ en tant qu’objet SPField. À cette fin, utilisez la propriété SPListItem.Fields de l’élément de liste. Il s’agit d’une collection des champs de la liste parente. Le type est SPFieldCollection. Cet objet, à son tour, fournit plusieurs façons de renvoyer un objet SPField spécifié.
Utilisation de la méthode GetField(String). Passez le nom interne, l’intitulé ou le nom statique du champ. Comme le nom interne est recherché en premier, utilisez, pour optimiser les performances, le nom interne lorsque vous le connaissez. Le nom statique est recherché en dernier.
Utilisation de la méthode GetFieldByInternalName(String).
Utilisation de la méthode TryGetFieldByStaticName(String).
Utilisation d’un index Guid, Int32 ou String de la propriété SPListItem.Fields de l’élément de liste. Le premier index renvoie l’objet SPField dont la propriété Id correspond à l’objet Guid passé. Le deuxième index renvoie l’objet SPField à la position ordinale de base zéro spécifiée dans la collection. Le troisième index renvoie l’objet SPField dont la propriété Title correspond à la chaîne passée. (Vous ne pouvez pas utiliser le nom interne du champ comme index de chaîne.)
Le code suivant propose quelques exemples de la façon d’utiliser les index et les méthodes des classes dérivées de SPListItem et SPField pour obtenir la valeur d’un champ.
using (SPSite siteCol = new SPSite("https://server/sites/Contoso"))
{
using (SPWeb web = siteCol.RootWeb)
{
SPList list = web.GetList("/sites/Contoso/Lists/Books");
SPListItem item = list.GetItemByIdSelectedFields(3, "Title", "ISBN", "Retail_x0020_Price");
// Get price as Double straight from the SPListItem object.
Double dblPrice = (Double)item["Retail_x0020_Price"];
// Get the SPField object by using the GetFieldByInternalName method, and then get
// price as string.
SPFieldCurrency priceField = (SPFieldCurrency)item.Fields.GetFieldByInternalName("Retail_x0020_Price");
String strPrice = priceField.GetFieldValueAsText(item["Retail_x0020_Price"])
// Get price as string from the SPField object. Use string SPFieldCollection index
// to get the SPField object (must use field object Title as index parameter). But
// use internal name of field as SPListItem index for better performance.
String strPrice2 = item.Fields["Retail Price"].GetFieldValueAsText(item["Retail_x0020_Price"]);
}
}