SPFieldLookupValue class

Contains the value for an SPFieldLookup object.

Inheritance hierarchy

System.Object
  Microsoft.SharePoint.SPFieldLookupValue
    Microsoft.SharePoint.SPFieldUserValue

Namespace:  Microsoft.SharePoint
Assembly:  Microsoft.SharePoint (in Microsoft.SharePoint.dll)

Syntax

'Declaration
Public Class SPFieldLookupValue
'Usage
Dim instance As SPFieldLookupValue
public class SPFieldLookupValue

Remarks

Instances of this class represent a single field value for a lookup field. Lookup fields can have multiple values or just one. You can determine which is the case by checking the value of the lookup field's AllowMultipleValues property. If the property returns true, the field can have multiple values; if it returns false, it cannot.

If a lookup field does not allow multiple values, the field value is an object of type String that contains the ID of the item in the list that the lookup field points to plus the value of the field in the item that the lookup field points to. You can pass this string as an argument to the SPFieldLookupValue(String) constructor to create an SPFieldLookupValue object. Then you can get the list item ID from the LookupId property and the value of the field in the list item from the LookupValue property.

If a lookup field allows multiple values, then the field value is an object of type SPFieldLookupValueCollection that is boxed as type Object. The SPFieldLookupValueCollection object is a collection of SPFieldLookupValue objects. You can extract the field values by enumerating the collection and accessing each object's LookupValue property.

Examples

The following example demonstrates how to set the value of a lookup field.

The example code is a console application that gets references to two related lists, Customers and Orders. Each item in the Customers list represents a customer record, and the ID field in the item is used to identify a customer. Each item in the Orders list represents an order placed by a customer. The Orders list has a lookup field named Customer ID that points to the ID field in the Customers list, identifying the customer who placed the order.

Code in a foreach loop iterates through the list of customers, adding a new item to the Orders list for each customer on the Customers list. In each case, the code sets the value of the lookup field, Customer ID, to link the order to the customer.

using System;
using Microsoft.SharePoint;

namespace ConsoleApp
{
    class Program
    {
        static void Main(string[] args)
        {
            using (SPSite site = new SPSite("https://localhost"))
            {
                using (SPWeb web = site.RootWeb)
                {
                    SPList customerList = web.Lists.TryGetList("Contoso Customers");
                    SPList orderList = web.Lists.TryGetList("Contoso Orders");

                    if (customerList != null && orderList != null)
                    {
                        SPListItemCollection customers = customerList.Items;
                        SPListItemCollection orders = orderList.Items;

                        string fieldName = "CustIDLookup";
                        if (!orderList.Fields.ContainsField(fieldName))
                            return;
                        
                        SPField lookupFld = orderList.Fields.GetField(fieldName);

                        foreach (SPListItem customer in customers)
                        {
                            SPListItem order = orders.Add();
                            order[SPBuiltInFieldId.Title] = "Thank you!";
                            order.Update();

                            SPFieldLookupValue value = new SPFieldLookupValue(customer.ID, customer.ID.ToString());
                            order[lookupFld.Id] = value.ToString();
                            order.Update();
                        }
                    }
                }
            }
        }
    }
}
Imports System
Imports Microsoft.SharePoint

Module ConsoleApp

    Sub Main()
        Using site As New SPSite("https://localhost")
            Using web As SPWeb = site.OpenWeb()

                Dim customerList As SPList = web.Lists.TryGetList("Contoso Customers")
                Dim orderList As SPList = web.Lists.TryGetList("Contoso Orders")

                If customerList IsNot Nothing AndAlso orderList IsNot Nothing Then
                    Dim customers As SPListItemCollection = customerList.Items
                    Dim orders As SPListItemCollection = orderList.Items

                    Dim fieldName As String = "CustIDLookup"
                    If Not orderList.Fields.ContainsField(fieldName) Then
                        Return
                    End If

                    Dim lookupFld As SPField = orderList.Fields.GetField(fieldName)

                    For Each customer As SPListItem In customers
                        Dim order As SPListItem = orders.Add()
                        order(SPBuiltInFieldId.Title) = "Thank you!"
                        order.Update()

                        Dim value As New SPFieldLookupValue(customer.ID, customer.ID.ToString())
                        order(lookupFld.Id) = value.ToString()
                        order.Update()
                    Next
                End If

            End Using
        End Using
    End Sub
End Module

Thread safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

See also

Reference

SPFieldLookupValue members

Microsoft.SharePoint namespace