Windows SharePoint Services 3.0 provides a user interface (UI) for creating document libraries. However, there might be cases in which you want to create a document library from a list item—using list items to drive the creation of a file plan, maintaining metadata about a library, or allowing users with limited site permissions to create specific types of libraries. Creating libraries based upon list items adds structure and business process to the document storage because it lets you run code during library creation. It also lets you use Windows SharePoint Services to automatically provide the user interface for entering the required input (filling out the list item metadata) and create the storage container (the library).
In this Microsoft Office Visual How To, you create a document library when a new item is added to a list, set the list to appear in Quick Launch, and turn on document versioning.
The list that is used in this example contains fields for Title and Description. You add an ItemAdded event handler that contains code to create the document library to an item event receiver class and register it on the list.
The first step is to obtain the values from the current list item that are used to create the document library. The values for the Title and Description fields are contained in the AfterProperties hash table. These values are used in creating the document library.
The next step is to create the document library. To do this, you get an SPWeb object for the Web in which we want to create the library, the current Web in the example. Then you create the document library by adding it to the list collection of the Web using the Add method of the Lists collection, passing in the title and description values that are obtained from the list item, and an enumeration value for the document library list template.
The Add method returns the GUID of the newly created document library. The GUID is then used to retrieve the new library as an SPList object so it can be modified. To display the library in the Quick Launch and turn on versioning, set the OnQuickLaunch property and the EnableVersioning property to true. After all updates are complete, call the Update method of the list object to commit the changes.
public override void ItemAdded(SPItemEventProperties properties)
// Get properties from the item to use on the
// document library.
string listTitle = properties.AfterProperties["Title"].ToString();
using (SPWeb web = properties.OpenWeb())
// Add the document library.
Guid newListID = web.Lists.Add(listTitle,
// Set additional properties on the new document library.
SPList newList = web.Lists[newListID];
newList.OnQuickLaunch = true;
newList.EnableVersioning = true;
catch (Exception exception)
// Handle the exception.
Users who do not have the required permissions cannot create document libraries by using this example. However, if you want to create libraries, you can modify the example so that the code that is used to create and modify the library is run under elevated privileges.
The code to create the library is contained within the ItemAdded event handler. There are several advantages to using the asynchronous event handler over the synchronous ItemAdding event handler. Because the item is created in the list before the library-creation code executes, all information about the item is available—such as all the metadata or the folder that contains the item—which may not readily be available in the ItemAdding event handler. This information may be useful in creating the library. Also, if a problem occurs and the list item is not created, the library is not created.
Conversely, sometimes the synchronous event handler might be preferable—for example, if you had to update metadata on the list item after the library is successfully created, such as a link to the library. The link would always be visible to the user if the code is executed in the synchronous event, but it may not be immediately visible if the code is executed in the asynchronous event handler.
In this example, the DisableEventFiring method is called to stop the raising of events that may occur from the code executing. This is generally a best practice when you are working with event handlers. It is very useful if you are updating the list item from within the event handler. After the code has executed, you must turn on event firing by calling the EnableEventFiring method. The code is wrapped in a try-catch-finally block to handle any exceptions. If any exceptions occur, the firing is turned back on as the EnableEventFiring method is called in the finally block.