SPFieldCollection.AddLookup Method (String, Guid, Boolean)

Creates a lookup field in the collection of fields for one list that points to a field in the collection for another list in the same website.

Namespace:  Microsoft.SharePoint
Assembly:  Microsoft.SharePoint (in Microsoft.SharePoint.dll)
Available in Sandboxed Solutions: Yes
Available in SharePoint Online

Syntax

'Declaration
Public Function AddLookup ( _
    displayName As String, _
    lookupListId As Guid, _
    bRequired As Boolean _
) As String
'Usage
Dim instance As SPFieldCollection
Dim displayName As String
Dim lookupListId As Guid
Dim bRequired As Boolean
Dim returnValue As String

returnValue = instance.AddLookup(displayName, _
    lookupListId, bRequired)

public string AddLookup(
    string displayName,
    Guid lookupListId,
    bool bRequired
)

Parameters

• displayName
  Type: System.String

  A string that specifies the display name of the field.

• lookupListId
  Type: System.Guid

  A GUID that specifies the target list for the lookup field.

• bRequired
  Type: System.Boolean

  true to require that the field contain values; otherwise, false.

Return Value

Type: System.String
A string that contains the internal name that is used for the field. You can retrieve the new field by passing this value to the GetFieldByInternalName(String) method. The field that is returned is of type SPFieldLookup.

Remarks

This method creates a field of type SPFieldLookup in the current list's field collection. A lookup field in one list takes its value from a field in another list, the target list specified in the lookupListId parameter. After you add a lookup field to the collection, you should retrieve it from the collection and then identify the source field in the target list by setting the LookupField property.

The target list that is the source of the lookup field's value is aware of the lookup field; that is, you can discover the lookup field by examining the objects in the collection returned by the target list's GetRelatedFields() method.

The current user must have SPBasePermissions.ManageLists permission on the target list when you call this method.

Examples

The following example is a console application that gets the collection of fields associated with the Pending Orders list and adds a lookup field named Customer ID that points to the ID field in the Customers list. The code then creates a secondary field that depends on the Customer ID field for its relationship to the Customers list.

using System;
using Microsoft.SharePoint;

namespace RelatedLists
{
    class Program
    {
        static void Main(string[] args)
        {
            using (SPSite siteCollection = new SPSite("https://localhost"))
            {
                using (SPWeb site = siteCollection.OpenWeb())
                {
                    SPList sourceList = site.Lists["Customers"];
                    SPList dependentList = site.Lists["Pending Orders"];

                    string strPrimaryCol = dependentList.Fields.AddLookup("Customer ID", sourceList.ID, true);
                    SPFieldLookup primaryCol = (SPFieldLookup)dependentList.Fields.GetFieldByInternalName(strPrimaryCol);
                    primaryCol.LookupField = sourceList.Fields["ID"].InternalName;
                    primaryCol.Indexed = true;
                    primaryCol.RelationshipDeleteBehavior = SPRelationshipDeleteBehavior.Restrict;
                    primaryCol.Update();

                    string strSecondaryCol = dependentList.Fields.AddDependentLookup("Last Name", primaryCol.Id);
                    SPFieldLookup secondaryCol = (SPFieldLookup)dependentList.Fields.GetFieldByInternalName(strSecondaryCol);
                    secondaryCol.LookupField = sourceList.Fields["Last Name"].InternalName;
                    secondaryCol.Update();
                }
            }
            Console.Write("\nPress ENTER to continue...");
            Console.ReadLine();
        }
    }
}

Imports System
Imports Microsoft.SharePoint

Namespace RelatedLists
    Class Program
        Shared Sub Main(ByVal args As String())
            Using siteCollection As New SPSite("https://localhost")
                Using site As SPWeb = siteCollection.OpenWeb()
                    Dim sourceList As SPList = site.Lists("Customers")
                    Dim dependentList As SPList = site.Lists("Pending Orders")

                    Dim strPrimaryCol As String = dependentList.Fields.AddLookup("Customer ID", sourceList.ID, True)
                    Dim primaryCol As SPFieldLookup = DirectCast(dependentList.Fields.GetFieldByInternalName(strPrimaryCol), SPFieldLookup)
                    primaryCol.LookupField = sourceList.Fields("ID").InternalName
                    primaryCol.Indexed = True
                    primaryCol.RelationshipDeleteBehavior = SPRelationshipDeleteBehavior.Restrict
                    primaryCol.Update()

                    Dim strSecondaryCol As String = dependentList.Fields.AddDependentLookup("Last Name", primaryCol.Id)
                    Dim secondaryCol As SPFieldLookup = DirectCast(dependentList.Fields.GetFieldByInternalName(strSecondaryCol), SPFieldLookup)
                    secondaryCol.LookupField = sourceList.Fields("Last Name").InternalName
                    secondaryCol.Update()
                End Using
            End Using
            Console.Write(vbLf & "Press ENTER to continue...")
            Console.ReadLine()
        End Sub
    End Class
End Namespace

See Also

Reference

SPFieldCollection Class

SPFieldCollection Members

AddLookup Overload

Microsoft.SharePoint Namespace

SPFieldLookup

LookupField

GetFieldByInternalName(String)

AddDependentLookup(String, Guid)

GetRelatedFields()