Declaratively adding a lookup field to a list schema using the name of the referenced list

This topic is really not a new one. I read already debates several times about if it is possible or not, see for example this post in Josh Gaffey’s blog:

Add SharePoint lookup column declaratively through CAML XML

or this post from Chris O’Brien’s blog:

Creating lookup columns as a feature

There are a lot of comments pro and cons in these posts.

Since I’ve got this question again on the MSDN forum (see create lookup column in list template without guid of parent list), I decided to check the issue myself.

In the past I deployed lists with lookup fields using the name of the referenced list formerly using a custom deployment tool, now I had to create a declarative feature using CAML definitions.

In my test I was to create a lookup field to the Title field of the standard Tasks list.

Based on the guide of Josh in the above post I first try to create a lookup site column.

To achieve this, I’ve created a simple feature that included the following fields.xml file:

1. <?xml version="1.0" encoding="utf-8"?>
2. <Elements xmlns="http://schemas.microsoft.com/sharepoint/">
3.     <Field ID="{95d89725-eb97-428b-bc79-ee02ca8b724c}"
4.         Name="TestField"
5.         SourceID="http://schemas.microsoft.com/sharepoint/v3"
6.         StaticName="TestField"
7.         Group="Test site columns"
8.         Type="Lookup"
9.         DisplayName="Test field"
10.         List="Lists/Tasks"
11.         FieldRef="ID"
12.         ShowField="Title" />
13. </Elements>

The feature.xml file looks like this:

1. <?xml version="1.0" encoding="utf-8"?>
2.   <FeatureId="2AABD552-10B1-4561-8A19-2311D39C9A2E"
3.           Title="List name based lookup field demo feature (site column)"
4.           Description="The sole purpose of this feature is to demonstrate how to create list name based lookup field in WSS 3.0 using a site column"
5.           Version="1.0.0.0"
6.           Hidden="FALSE"
7.           Scope="Site"
8.           xmlns="http://schemas.microsoft.com/sharepoint/">
9.   <ElementManifests>
10.     <ElementManifest Location="fields.xml"/>
11.   </ElementManifests>
12. </Feature>

Activating the feature resulted in the following in the site columns list:

At first sight that was OK, but after checking the details it turned out to be not perfect:

As you can see on the image above, the place of the parent list was empty.

Checking the field from code showed that the LookupList property of the site column was “Lists/Tasks”, so it was not resolved to the list GUID on feature activation.

When I tried to add the site column to a list, I’ve received the following exception:

Exception from HRESULT: 0x80040E07   at Microsoft.SharePoint.Library.SPRequestInternalClass.AddField(String bstrUrl, String bstrListName, String bstrSchemaXml, Int32 grfAdd)

  at Microsoft.SharePoint.Library.SPRequest.AddField(String bstrUrl, String bstrListName, String bstrSchemaXml, Int32 grfAdd)

I’ve also tried to create a custom list definition in the same feature, but when I tried to create a new instance based on that definition, I received the following exception:

Cannot complete this action.
Please try again.   at Microsoft.SharePoint.Library.SPRequestInternalClass.CreateListFromFormPost(String bstrUrl, String& pbstrGuid, String& pbstrNextUrl)
   at Microsoft.SharePoint.Library.SPRequest.CreateListFromFormPost(String bstrUrl, String& pbstrGuid, String& pbstrNextUrl)

Although some comments suggested to remove the ShowField attribute to get it work, in my experience it did not help. It only made the case even worse, as now the column information was also empty (as one could expect logically):

So I have to find an alternative way. I decided to try it with a custom list definition that contains the field definition itself.

If you are new to creating custom list definitions, you can read more about that here:

How to: Create a Custom List Definition

I’ve created a feature that contains the custom list definition. The main modifications of the simple custom list schema are the followings:

1. <ContentTypes>
2.     <ContentTypeID="0x01"
3.     Name="Item"
4.     Group="Item group"
5.     Description="Item description"
6.     Version="0">
7.     <FieldRefs>
8.       <FieldRef ID="{fa564e0f-0c70-4ab9-b863-0177e6ddd247}" Name="Title" Required="TRUE" ShowInNewForm="TRUE" ShowInEditForm="TRUE"/>
9.       <!– Title –>
10.       <FieldRef ID="{95d89725-eb97-428b-bc79-ee02ca8b7225}" Name="TestField" Required="FALSE" ShowInNewForm="TRUE" ShowInEditForm="TRUE"/>
11.       <!– Test field –>
12.     </FieldRefs>
13.     <XmlDocuments>
14.       <XmlDocument NamespaceURI="http://schemas.microsoft.com/sharepoint/v3/contenttype/forms">
15.         <FormTemplates xmlns="http://schemas.microsoft.com/sharepoint/v3/contenttype/forms">
16.           <Display>ListForm</Display>
17.           <Edit>ListForm</Edit>
18.           <New>ListForm</New>
19.         </FormTemplates>
20.       </XmlDocument>
21.     </XmlDocuments>
22.   </ContentType>
23.   <ContentTypeRef ID="0x0120" />
24. </ContentTypes>
25. <Fields>
26.   <Field Type="Lookup"
27.          DisplayName="Test field"
28.          Required="FALSE"
29.          List="Lists/Tasks"
30.          ShowField="Title"
31.          UnlimitedLengthInDocumentLibrary="FALSE"
32.          ID="{95d89725-eb97-428b-bc79-ee02ca8b7225}"
33.          SourceID="http://schemas.microsoft.com/sharepoint/v3"
34.          StaticName="TestField"
35.          Name="TestField" />
36. </Fields>

and a reference for the lookup field was added to the ViewFields:

1. <ViewFields>
2.   <FieldRef Name="Attachments">
3.   </FieldRef>
4.   <FieldRef Name="LinkTitle">
5.   </FieldRef>
6.   <FieldRef Name="TestField">
7.   </FieldRef>
8. </ViewFields>

Next, I’ve installed and activated the feature:

stsadm -o installfeature -name ListNameBasedLookUp
stsadm -o activatefeature -name ListNameBasedLookUp -url http://yoursite

The custom list definition appeared on the available list types:

I’ve created a new instance called LookUpList1:

The new list instance contained the lookup field:

And the definition of the field was correct. It pointed to the right list (Tasks) and to the right field (Title):

The field was added to the default view as expected:

In the meantime I’ve created to item in the Tasks list:

When I created a new item, the values of the lookup field came from the specified source list and field:

And last but not least, the item is saved correctly to the list:

So my experience matches to Scott’s comment in Josh’s post:

“To make this method work, the field definition must exist in a list definition since the wiring up to the GUID happens when you the provision the list, rather than when you add a column to an existing content type/list.”

At the end some note:

If you want to alter the feature XML files and would like to avoid caching issues, I suggest you to alter the feature and field GUIDs each time you deploy (deactivate/uninstall/alter/install/activate/IISRESET) the feature. Ignoring this hint may cause you a lot of headache. Believe me, I tell you that from my own experience!

Another side note, that the experience may depend on the version number of SharePoint in my environment I tested it with the December 2009 Cumulative Update (12.0.0.6524).

You can find the full sample feature here.