SPFieldCollection.AddDependentLookup Method

2014-07-24

Adds a secondary lookup field that depends on a primary lookup field for its relationship to the list where it gets its information.

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

Syntax

'Declaration
Public Function AddDependentLookup ( _
    displayName As String, _
    primaryLookupFieldId As Guid _
) As String
'Usage
Dim instance As SPFieldCollection
Dim displayName As String
Dim primaryLookupFieldId As Guid
Dim returnValue As String

returnValue = instance.AddDependentLookup(displayName, _
    primaryLookupFieldId)

public string AddDependentLookup(
    string displayName,
    Guid primaryLookupFieldId
)

Parameters

displayName
Type: System.String

The display name for the secondary lookup field.

primaryLookupFieldId
Type: System.Guid

The value of the Id property of the SPFieldLookup object that represents the primary field.

Return Value

Type: System.String
The field's internal name.

Exceptions

Exception	Condition
ArgumentNullException	The value passed in the displayName parameter is an empty string or null.
ArgumentNullException	The value passed in the primaryLookupFieldId parameter is Guid.Empty or null.
SPException	The field identified by the value passed in the primaryLookupFieldId parameter does not exist, is not of type SPFieldLookup, or its IsDependentLookup property returns true.

Remarks

In a multiple column lookup, the primary field is the SPFieldLookup object that establishes the relationship with the list that is the source of the lookup field's value. One or more secondary fields can then depend on the primary field for their relationship to the source list. The source list is aware of the primary field; that is, you can discover the primary field by examining the objects in the collection returned by the source list's GetRelatedFields() method. The primary field, in turn, is aware of any fields that depend on it; you can discover dependent fields by calling the primary field's GetDependentLookupInternalNames() method.

To create a multiple-column lookup, begin by creating the primary field by calling the AddLookup(String, Guid, Boolean) method. You can then use the AddDependentLookup method to create one or more secondary fields that depend on the primary field.

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"];

                    // Create the primary column.
                    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();

                    // Create the secondary column.
                    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();

                    // Make the primary column the first one on New and Edit forms.
                    SPContentType contentType = dependentList.ContentTypes[0];
                    SPFieldLinkCollection fieldRefs = contentType.FieldLinks;
                    fieldRefs.Reorder(new[] { primaryCol.InternalName });
                    contentType.Update();
                    

                    // Add the columns to the default view.
                    SPView view = dependentList.DefaultView;
                    if (view != null)
                    {
                        SPViewFieldCollection viewFields = view.ViewFields;
                        if (viewFields != null)
                        {
                            viewFields.Add(primaryCol);
                            viewFields.Add(secondaryCol);
                            viewFields.MoveFieldTo(primaryCol.InternalName, 0);
                            viewFields.MoveFieldTo(secondaryCol.InternalName, 1);
                            view.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")

                    ' Create the primary column.
                    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()

                    ' Create the secondary column.
                    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()

                    'Make the primary column the first one on New and Edit forms.
                    Dim contentType As SPContentType = dependentList.ContentTypes(0)
                    Dim fieldRefs As SPFieldLinkCollection = contentType.FieldLinks
                    fieldRefs.Reorder(New String() {primaryCol.InternalName})
                    contentType.Update()

                    ' Add the columns to the default view.
                    Dim view As SPView = dependentList.DefaultView
                    If view <> Nothing Then
                        Dim viewFields As SPViewFieldCollection = view.ViewFields
                        If viewFields <> Nothing Then
                            viewFields.Add(primaryCol)
                            viewFields.Add(secondaryCol)
                            viewFields.MoveFieldTo(primaryCol.InternalName, 0)
                            viewFields.MoveFieldTo(secondaryCol.InternalName, 1)
                            view.Update()
                        End If
                    End If
                End Using
            End Using
            Console.Write(vbLf & "Press ENTER to continue...")
            Console.ReadLine()
        End Sub
    End Class
End Namespace

Share via