SPRelatedField Class
Provides information about a lookup field on a child list that gets information from a parent list.
Inheritance Hierarchy
System.Object
Microsoft.SharePoint.SPRelatedField
Namespace: Microsoft.SharePoint
Assembly: Microsoft.SharePoint (in Microsoft.SharePoint.dll)
Available in Sandboxed Solutions: Yes
Available in SharePoint Online
Syntax
'Declaration
<SubsetCallableTypeAttribute> _
Public Class SPRelatedField
'Usage
Dim instance As SPRelatedField
[SubsetCallableTypeAttribute]
public class SPRelatedField
Remarks
In Microsoft SharePoint Foundation two lists become related when a user creates a lookup field on one list that takes its value from a field on another list. You can think of the list that provides data as the parent and the list that looks up data as the child. To discover which fields in child lists depend on information in a parent list, call the GetRelatedFields() method on an SPList object that represents the parent list.
The GetRelatedFields method returns a collection of SPRelatedField objects with the following properties:
LookupList. Gets the SPList object that represents the parent list.
WebId. Gets the ID of the Web site where the child list is located.
RelationshipDeleteBehavior. Gets the data integrity constraint defined for the list relationship.
The last property, RelationshipDeleteBehavior, represents an important aspect of list relationships. A user who creates a lookup field, either through the user interface or through the object model, can set constraints on how deletions from one list affect deletions from the other. For example, the user can specify that deletions from the parent list cascade to the child; that is, when an item is deleted from the parent list, all related items on the child list are also deleted. The user can also specify that deletions from the parent list are restricted; an item cannot be deleted from the parent list if related items exist on the child list. For more information, see the SPRelationshipDeleteBehavior enumeration.
Note
In order to restrict deletions, the user must have SPBasePermissions.ManageLists permission on the parent list.
In SharePoint Foundation a user can also create a multiple-column lookup. In this case, the child list has a primary column that defines the relationship with the parent list, and it has one or more secondary columns that read values from fields on the parent list but depend on the primary column for the list relationship. SPRelatedField objects contain information about only the primary column. To get information about secondary columns, call the GetDependentLookupInternalNames method of the SPFieldLookup object that represents the primary column.
Examples
The following example is a console application that reports information about fields in the Customers list that provide data to lookup fields in other lists. For each related field that represents a primary column, the application calls the GetDependentLookupInternalNames method to get a list of fields that represent secondary columns.
using System;
using System.Collections.Generic;
using Microsoft.SharePoint;
namespace ConsoleApp
{
class Program
{
static void Main(string[] args)
{
using (SPSite siteCollection = new SPSite("https://localhost"))
{
using (SPWeb site = siteCollection.OpenWeb())
{
SPList targetList = site.Lists.TryGetList("Customers");
SPRelatedFieldCollection relatedFields = targetList.GetRelatedFields();
string strSeparator = new String('=', 70);
string strUnderline = new String('-', 20);
string strFormat = "Target Field: {0} | Related Field: {1}";
Console.WriteLine(strSeparator);
foreach (SPRelatedField fieldInfo in relatedFields)
{
using (SPWeb relatedSite = siteCollection.AllWebs[fieldInfo.WebId])
{
SPList relatedList = relatedSite.Lists.GetList(fieldInfo.ListId, false);
SPFieldLookup relatedField = relatedList.Fields[fieldInfo.FieldId] as SPFieldLookup;
SPField targetField = targetList.Fields.GetFieldByInternalName(relatedField.LookupField);
Console.WriteLine("\nTarget List: {0} ({1}) | Related List: {2} ({3})",
targetList.Title, site.Title, relatedList.Title, relatedSite.Title);
Console.WriteLine("\nPrimary Column");
Console.WriteLine(strUnderline);
Console.WriteLine(strFormat, targetField.Title, relatedField.Title);
Console.WriteLine("Deletion behavior: {0}", relatedField.RelationshipDeleteBehavior);
Console.WriteLine("\nSecondary Columns");
Console.WriteLine(strUnderline);
List<string> dependents = relatedField.GetDependentLookupInternalNames();
for (int i = 0; i < dependents.Count; i++)
{
SPFieldLookup lookup = relatedList.Fields.GetFieldByInternalName(dependents[i]) as SPFieldLookup;
SPField field = targetList.Fields.GetFieldByInternalName(lookup.LookupField);
Console.WriteLine(strFormat, field.Title, lookup.Title);
}
Console.WriteLine();
Console.WriteLine(strSeparator);
}
}
}
}
Console.Write("\nPress ENTER to continue...");
Console.ReadLine();
}
}
}
Imports System
Imports System.Collections.Generic
Imports Microsoft.SharePoint
Module ConsoleApp
Sub Main()
Using siteCollection As New SPSite("https://localhost")
Using site As SPWeb = siteCollection.OpenWeb()
Dim targetList As SPList = site.Lists.TryGetList("Customers")
Dim relatedFields As SPRelatedFieldCollection = targetList.GetRelatedFields()
Dim strSeparator As String = New [String]("="c, 70)
Dim strUnderline As String = New [String]("-"c, 20)
Dim strFormat As String = "Target Field: {0} | Related Field: {1}"
Console.WriteLine(strSeparator)
For Each fieldInfo As SPRelatedField In relatedFields
Using relatedSite As SPWeb = siteCollection.AllWebs(fieldInfo.WebId)
Dim relatedList As SPList = relatedSite.Lists.GetList(fieldInfo.ListId, False)
Dim relatedField As SPFieldLookup = TryCast(relatedList.Fields(fieldInfo.FieldId), SPFieldLookup)
Dim targetField As SPField = targetList.Fields.GetFieldByInternalName(relatedField.LookupField)
Console.WriteLine(vbLf & "Target List: {0} ({1}) | Related List: {2} ({3})", _
targetList.Title, site.Title, relatedList.Title, relatedSite.Title)
Console.WriteLine(vbLf & "Primary Column")
Console.WriteLine(strUnderline)
Console.WriteLine(strFormat, targetField.Title, relatedField.Title)
Console.WriteLine("Deletion behavior: {0}", relatedField.RelationshipDeleteBehavior)
Console.WriteLine(vbLf & "Secondary Columns")
Console.WriteLine(strUnderline)
Dim dependents As List(Of String) = relatedField.GetDependentLookupInternalNames()
Dim i As Integer = 0
While i < dependents.Count
Dim lookup As SPFieldLookup = _
TryCast(relatedList.Fields.GetFieldByInternalName(dependents(i)), SPFieldLookup)
Dim field As SPField = targetList.Fields.GetFieldByInternalName(lookup.LookupField)
Console.WriteLine(strFormat, field.Title, lookup.Title)
i = i + 1
End While
Console.WriteLine()
Console.WriteLine(strSeparator)
End Using
Next
End Using
End Using
Console.Write(vbLf & "Press ENTER to continue...")
Console.ReadLine()
End Sub
End Module
The console application prints output that resembles the following example.
======================================================================
Target List: Customers (Team Site) | Related List: Complete Orders (Team Site)
Primary Column
--------------------
Target Field: ID | Related Field: Customer ID
Deletion behavior: None
Secondary Columns
--------------------
Target Field: Last Name | Related Field: Customer
======================================================================
Target List: Customers (Team Site) | Related List: Addresses (Team Site)
Primary Column
--------------------
Target Field: ID | Related Field: Customer ID
Deletion behavior: Cascade
Secondary Columns
--------------------
Target Field: Last Name | Related Field: Last Name
Target Field: First Name | Related Field: First Name
======================================================================
Target List: Customers (Team Site) | Related List: Pending Orders (Team Site)
Primary Column
--------------------
Target Field: ID | Related Field: Customer ID
Deletion behavior: Restrict
Secondary Columns
--------------------
Target Field: First Name | Related Field: First Name
Target Field: Last Name | Related Field: Last Name
Target Field: Phone | Related Field: Phone
======================================================================
Press ENTER to continue...
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
Microsoft.SharePoint Namespace