Friday, June 20, 2008

Get a SharePoint list (SPList) Root Folder Name and Display Name (Title)


1. Introduction
2. Samples
1.1. Getting List names programmatically in c#
1.2. Retrieving a list by its names programmatically in C#
1 - Document Library
2 - Standard Lists
3. Warnings
1. Special characters
2. File Not Found exception


Reading MSDN for SPList Class , it seems it's not very obvious to:
get the name of a SharePoint list.
look for a list in a SharePoint web site using its name.
Here is the only excerpt of the SPList Class Library Reference in MSDN speaking of the list name:
Use an indexer to return a single list from the collection. For example, if the collection is assigned to a variable named collLists, use collLists[index] in C#, or collLists(index) in Visual Basic 2005, where index is the index number of the list in the collection, the display name of the list, or the GUID of the list.

For instance SPList class has no Name property or GetName method.
Furthermore, a SharePoint list will have TWO names if you had renamed it!
The Root Folder Name (like the Internal Name for a SPList Field ) is the one you have set when you have created the list.
This name will be always present in your browser Address Bar when you display the list
The display name (the one you have used if you have renamed the list).
This name will appear as your list Title, when you display the list and the as a link to the list in your QuickLaunch menu if you have added to. (If you have not renamed your List, the root folder name and the display name are the same).


1.1 Getting List names programmatically in c#

So, how to get a SharePoint list Root Folder Name and Display Name (Title) in C# programming.
The following code sample will display these two names for all lists of a SharePoint web site:

                            SPWeb myWeb = SPContext.Current.Web;

                            Debug.WriteLine("MyWeb lists : ");

                            foreach (SPList aList in myWeb.Lists)



                                Debug.WriteLine("list Title (Display Name): " + aList);

                                Debug.WriteLine("list Title (Display Name): " + aList.Title);

                                Debug.WriteLine("list Root Folder Name: " + aList.RootFolder.Name);



2.2 Retrieving a list by its names programmatically in C#

And now, how to retrieve a SharePoint list using Root Folder Name or Display Name:
Notice that:
Document Libraries URL finishes by "/Website/DocLibRootFolderName"
Other Lists URL finishes by "/Website/Lists/OtherListsRootFolderName"

1 - Document Library

Assume we need to instantiate a SPList object corresponding to a Document Library with,
Root Folder Name: mycustomdoclib1
Display Name: Invoices
the following code sample will illustrate that:

  • Root Folder Name:

                            SPWeb myWeb = SPContext.Current.Web;

                            //SPList myList = myWeb.GetList("sites/my-collaboration-portal/docs/mycustomdoclib1");

                            SPList myList = myWeb.GetList(SPUrlUtility.CombineUrl(myWeb.ServerRelativeUrl, "mycustomdoclib1"));

  • Display Name:

                            SPList myList = myWeb.Lists["Invoices"];

2 - Standard Lists

Assume  we need to instantiate a SPList object corresponding to a list that is not a document library with,
Root Folder Name: mycustomlist1
Display Name: Clients
the following code sample will illustrate that:

  • Root Folder Name:

                            SPWeb myWeb = SPContext.Current.Web;

                            //SPList myList = myWeb.GetList("sites/my-collaboration-portal/docs/Lists/ mycustomlist1 ");

                            SPList myList = myWeb.GetList(SPUrlUtility.CombineUrl(myWeb.ServerRelativeUrl, "/Lists/ mycustomlist1 ")); 

  • Display Name:

                            SPList myList = myWeb.Lists["Clients"];

3. Warnings:

3.1 Special characters

When you set your list display name, you will generally do it using the Web Site user language. If this language is not English, you will sometimes have to use special characters like:
É, è , ù, ê, Ø, ñ, ô, …

SharePoint generally use Unicode escape sequence for these characters. Assume your list display name in French is:
"ma première doclib",

you will have to use that string to retrieve it:

                            SPList myList = myWeb.Lists["ma premi\u00e8re doclib"];

If you are looking for any Unicode escape sequence, you can download a mapping table here.

If you have too many fields with special characters to manipulate, think to use Visual Studio Advanced Save Options and save your .aspx Page file in "UTF-8 with signature" or "Unicode" format, doing that will allow you to write your fields name using your language special characters. You can also modify your Web Application web.config to obtain the same result.

About this topic you can read this post:

Unicode in Visual Studio .Net


To avoid using special characters in your requests:
Use an English name for the list when you create it, and rename your list using Web Site user language.
Use the list Internal Name with SPWeb.GetList method to retrieve a list using server code (VB .net, C#...).

3.2 File Not Found exception

There is a lack in SharePoint when you are trying to find objects, because the methods you are using for that will throw an exception if the object does not exist instead of returning null. That forces you to manage certain parts of your code by handling exception that is not a good coding practice.

                            SPList listVariable;



                                listVariable = myWeb.Lists["ListIWant"];


                            catch (Exception e) { }

There is at least two ways of avoiding exception handling when trying to retrieve a list:

1 - Loop-through-the-lists

                            SPList listVariable;

                            foreach (SPList tempList in myWeb.Lists)


                                if (tempList.Title == "ListIWant")


                                    listVariable = tempList;




It is not so fool as it seems to be since someone found that loop was always faster than the previously described methods.

Fast access items in an SPListCollection

2 - Use-LINQ

There is a LINQ request posted by Adam Buenz that allows you to look for a list without throwing an exception if it does not exists.
By the way the Linq request actually is doing a loop.

        public static bool InspectForList(string listName)


            var results = SPContext.Current.Web.Lists.Cast<SPList>().Where(item => Equals(string.Compare(item.Title, listName, true), 0));

            return results.Count() > 0;


What Are The Biggest SharePoint API Mistakes?

For ending, a last advice,
You should always use the root folder name of a list to look for it, since this name will never change.




No comments: