Feature to create lookup fields on Codeplex

In a recent post I posted some sample code for a feature receiver which would create lookup fields (site columns which get their data from lists). A couple of people left comments asking for full set of files.

I've put these on Codeplex at http://www.codeplex.com/SP2007LookupFields.

Some notes:-

• I've enhanced the solution to be more generic and deal with creating multiple lookup fields in one feature. Now the name of the list can be included in the CAML and the feature receiver will parse this, find the list and fix the reference via the list GUID using the API. Note currently the list must be in the root web, though it would be trivial to extend this.
• All the hardcoded values have been removed, e.g. the path to the file containing the CAML definition is now passed as a feature property.
• I mentioned in the earlier post that you could have a dependent feature so that the assembly containing the feature receiver also gets deployed automatically on feature activation. This doesn't quite make sense since assemblies can only be deployed using SharePoint solutions not features. Hence I've wrapped the feature in a SharePoint solution which deploys the assembly and feature. When the feature is activated the assembly is already in the GAC and the feature receiver runs happily. Note it would also be fairly simple to enhance the solution such that the assembly gets deployed to a site bin with appropriate CAS policy for highly-controlled environments.
• I've also included an STSADM script to take care of deploying the solution - you need to edit the URL in this file to point to your SharePoint site.

Hope this is useful, let me know if you have feedback..

Sample code - creating lookup columns as a feature

I promised in an earlier post to post the code I used to create lookup columns as a feature. The basic idea here to use CAML as far as possible to define the site column, but use code to inject the list ID which the column refers to (unknown at feature design-time since SharePoint decides the GUID for lists). Extracted below is the code for the feature receiver.

A couple of key points:-

• this assumes a file exists at the location D:\COB.Demo.ListBasedSiteColumns.Fields.xml with the following contents (note the 'List' attribute with an empty value):-

  <?xml version="1.0" encoding="utf-8"?>
  <elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <!-- _filecategory="ContentType" _filetype="File" _filename="fields.xml" _uniqueid="c0188da6-e320-44c0-b50c-cb6eaecec512" --> 
  <Field
  Type="Lookup"
  Displayname="Locations"
  Required="FALSE"
  List=""
  ShowField="LinkTitleNoMenu"
  UnlimitedLengthInDocumentlibrary="FALSE"
  Group="COBDemo"
  ID="{ae8e6ab8-b151-4fa4-8694-3cd24ad3b1bc}"
  SourceId="{8c066b26-5a3e-4e1b-85ec-7e584cf178d7}"
  StaticName="Locations"
  Name="Locations">
  </elements>

  
  
• Since most of the column definition is in CAML, this allows you to specify the ID of the column. This is useful later on when we deploy content types or lists which need to reference this site column by ID.
  
• Site columns cannot be deleted when they are in use i.e. used in content types or lists. I prefer to try to delete the column on feature deactivation or reactivation, but omit error-handling so SharePoint throws an exception. This makes it clear to me why the feature cannot be deactivated. See comments in code for more information.
  
• Note that the assembly which contains the code below must be available (in the GAC, or site bin directory with appropriate CAS policy) when the feature is activated. You must also specify the FeatureAssembly and FeatureReceiver attributes in your feature.xml file to register the feature receiver.
  
• In terms of deploying the assembly, note that whilst you certainly can deploy assemblies to the GAC or site bin using the feature framework, you can't do it in this feature. Despite the 'FeatureActivated' name of the event handler, when your code executes the CAML won't yet have been processed. Hence your assembly won't yet have been copied and you'll get a FileNotFoundException when it tries to load the assembly. A good solution is to use a feature dependency. Here you can create a 2nd feature which deploys the assembly, and set the main feature to be dependent on this one. Additionally you can mark the assembly deployment feature to be hidden thus making the implementation a bit tidier. If it's useful to see the entire set of files I used leave me a comment and I'll put them up somewhere.
  

Apologies for the formatting, I will try to do something about this when I get time:-

public class FeatureReceiver : SPFeatureReceiver
{
    private readonly string f_csSITE_COLS_DEFINITION_PATH = @"D:\COB.Demo.ListBasedSiteColumns.Fields.xml";
 
    public override void FeatureActivated(SPFeatureReceiverProperties properties)
    {
       // feature is scoped at Site, so the parent is type SPSite rather than SPWeb..
       using (SPSite site = properties.Feature.Parent as SPSite)
       {
          SPWeb currentWeb = null;
          Guid gRootWebId = Guid.Empty;
          if (site != null)
          {
             currentWeb = site.RootWeb;
             gRootWebId = currentWeb.ID;
          }
          else
          { 
             currentWeb = properties.Feature.Parent as SPWeb;
             gRootWebId = currentWeb.Site.RootWeb.ID;
          }





          using (currentWeb)
          {
             // get reference to the list..
             SPList referencedList = currentWeb.Site.RootWeb.Lists["LocationsList"];
             string sFieldElement = null;
             XmlTextReader xReader = new XmlTextReader(f_csSITE_COLS_DEFINITION_PATH);
             while (xReader.Read())
             {
                if (xReader.LocalName == "Field")
                {
                   sFieldElement = xReader.ReadOuterXml();
                   break;
                }
             }


             string sFinalCaml = replaceListGuidString(sFieldElement, referencedList);
             createLookupColumn(currentWeb, sFinalCaml, "Locations");
             currentWeb.Update();
         }
     }
   }

   private string replaceListGuidString(string sFieldElement, SPList referencedList)
   {
      string sPopulatedGuid = string.Format("List=\"{0}\"", referencedList.ID);
      return sFieldElement.Replace("List=\"\"", sPopulatedGuid);
   }

   /// <summary>
   /// Attempt to delete the column. Note that this will fail if the column is inuse,
   /// i.e. it is used in a content type or list. I prefer to not catch the exception
   /// (though it may be useful to add extra logging), hence feature deactivation/re- /// activation will fail. This effectively means this feature cannot be deactivated whilst the column is in use.
   /// </summary>
   /// <param name="column">Column to delete.</param>

   private void attemptColumnDelete(SPFieldLookup column)
   {
      try
      {
         column.Delete();
      }
      catch (SPException e)
      {
         // consider logging full explanation..
         throw;
      }
   }

   private void createLookupColumn(SPWeb web, string sColumnDefinitionXml, string sColumnName)
   {
      // delete the column if it exists already and is not yet in use..
      SPFieldLookup lookupColumn = null;
      lookupColumn = web.Fields[sColumnName] as SPFieldLookup;
      if (lookupColumn != null)
      {
         attemptColumnDelete(lookupColumn);
      }

      // now create the column from the CAML definition..
      string sCreatedColName = web.Fields.AddFieldAsXml(sColumnDefinitionXml);
  
      // also set LookupWebId so column can be used in webs other than web which hosts list..
      lookupColumn = web.Fields[sCreatedColName] as SPFieldLookup;
      lookupColumn.LookupWebId = web.Site.RootWeb.ID;
      lookupColumn.Update();
   }

   public override void FeatureDeactivating(SPFeatureReceiverProperties properties)
   {
      // delete the column if it exists already and is not yet in use..

// feature is scoped at Site, so the parent is type SPSite rather than SPWeb..
using (SPSite site = properties.Feature.Parent as SPSite)
{
SPWeb currentWeb = null;
Guid gRootWebId = Guid.Empty;
if (site != null)
{
currentWeb = site.RootWeb;
gRootWebId = currentWeb.ID;
}
else
{
currentWeb = properties.Feature.Parent as SPWeb;
gRootWebId = currentWeb.Site.RootWeb.ID;
}

SPFieldLookup lookupColumn = null;
lookupColumn = currentWeb.Fields["LocationsList"] as SPFieldLookup;

if (lookupColumn != null)
{
attemptColumnDelete(lookupColumn);
}
}
}

   public override void FeatureInstalled(SPFeatureReceiverProperties properties)
   {
   }


   public override void FeatureUninstalling(SPFeatureReceiverProperties properties)
   {
   }
}

If it's useful to have the full set of files illustrating the 2 features(particularly since the above isn't very readable!), leave me a comment and I'll make them available somewhere..

[Update - these have now been uploaded to Codeplex, see http://sharepointnutsandbolts.blogspot.com/2007/04/feature-to-create-lookup-fields-on.html]

Creating lookup columns as a feature

This is the second article in a series aimed at explaining the process of creating a MOSS site using SharePoint features. For the full series contents, see my introduction.

Last time we looked at the process of creating some SharePoint lists using VSeWSS. Sure, creating a list is a simple end-user task using the SharePoint UI, but in some scenarios such as when your site is a highly controlled internet/WCM site (or generally anywhere where we have multiple environments for dev/QA/staging/production) this deployment technique doesn't really cut it. Instead we probably want to use something more automated and repeatable than recreating such site artifacts manually each time. SharePoint 2007 supports this with Features.

Today we'll look at creating site columns which get their data from lists (lookup columns). This is a fairly common set-up, used for things like assigning metadata to a page or performing some other classification using a restricted set of values. Often the user would select the appropriate value using a dropdown shown when creating/editing a page.

Note that a similar method is to define a site column with several CHOICE elements, as below:-

However, this doesn't offer the same functionality as retrieving the values from a list. Consider the following:-

• lists can have multiple columns whereas a choice element is effectively just one column
• lists can have item-level permissions
• lists can have events, workflow, versioning etc etc.

So it's clear many scenarios are better served from a site column which gets it's data from a list.

Now, when creating site artifacts as a feature, the developer will typically construct the definition in CAML, or allow VSeWSS to do this for him/her. Sometimes however, it's just not possible to do what you want with CAML. In these cases, the solution is to use a feature receiver. This is a class in compiled code (hopefully you still remember this ;-)) in which you override some methods and use the SharePoint API to define what should happen when the feature gets activated.

So why is it not possible to create a lookup column with CAML? After all, the following fragment successfully creates a site column which gets it's data from the list with the GUID specified in the 'List' attribute:-

<field id="{ae8e6ab8-b151-4fa4-8694-3cd24ad3b1bc}" type="Lookup" displayname="Locations" required="FALSE" list="{853CEC87-259E-47CA-97A7-42630F882FB7}" showfield="LinkTitleNoMenu" unlimitedlengthindocumentlibrary="FALSE" group="COB Metadata" sourceid="{8c066b26-5a3e-4e1b-85ec-7e584cf178d7}" staticname="Locations" name="Locations">

The answer is because list GUIDs are not deterministic. When a list gets created, whether through the UI, CAML or the API, it's GUID is assigned by SharePoint. There is no way to create a list with a GUID you have assigned. And if a list gets a new GUID each time it's created, this means it will have a different GUID in each of your dev/QA/staging/production environments. If this is your scenario suddenly that CAML fragment isn't so useful. Using this technique I would have to update the list GUID in my site column's <field> element and rebuild my site column feature every time the list got deployed to a new environment (or even redeployed). Clearly, this isn't pretty since, in addition to the extra effort, you're no longer deploying the exact same thing to live that has been tested in staging.

Hence I'd suggest any artifacts which reference a list should not refer to it in a declarative CAML. A better idea is to dynamically retrieve the list's GUID using the API (i.e. in a feature receiver), and create your site column in code. Briefly, the technique I use is this:

• define site column in CAML using the fragment above
• in my feature receiver, read this XML into memory
• replace the list GUID with the real value retrieved from the API
• create the site column using SPWeb.Fields.AddFieldAsXml(sXml) where sXml is the XML <field> element as a string

So this is kind of a cross between creating the site column in CAML and creating it in code. This gives a certain amount of flexibility since other properties of the column can be changed without having to recompile the code (simply change the value in the CAML, next time the feature runs it will read the modified values).

Note one other thing you are likely to need to do is to set the LookupWebId property on the column. This allows your column to be used in different sites in your site collection, yet still correctly reference the same list in your (for example) root site.

I'll post some sample code to do this in forthcoming post.

Assuming your CAML and the code to find the ID of your list was valid, you should see that you now have a site column which gets it's data from the list you specified when the feature is activated:-


One thing to note is that it's not really possible to delete the site column when the feature is deactivated. Generally, tidying up in this way is something you should do, but a site column cannot be deleted when it is has been provisioned on a list and has data. In this case, it's valid to not do any work on feature deactivation.

We're now well on our way to having page layouts which use content types with lookup columns. Phew! Next time, creating content types as a feature.