MOSS MVP

I've moved my blog to http://blog.falchionconsulting.com!. Please update your links. This blog is no longer in use--you can find all posts and comments at my new blog; I will no longer be posting to this site and comments have been disabled.

Tuesday, July 8, 2008

Creating a List via STSADM

I'm working on a project which involves scripting, via batch files, an intranet portal.  We wanted to script the creation of the various division and department sites along with several lists that would be needed in each site.  Eventually these site will be turned into custom site definitions using Features and Feature Stapling to provision the lists and various files but we needed something to enable us to quickly mock up a site taxonomy and present that to stakeholders.  I had lots of commands to accomplish many of the required tasks but I didn't have anything to create lists and do some basic configurations of those lists.  The first command I needed is detailed here and is called gl-addlist.  I'll discuss some of the other commands I created in follow-up posts.

Fortunately, creating a list via code is super simple - there's  single Add method you call via the SPListCollection object which you can get from the SPWeb's List property.  So turning this into a new STSADM command is as simple as getting the parameters needed and passing them into the Add method:

   1: public class AddList : SPOperation
   2: {
   3:      /// <summary>
   4:     /// Initializes a new instance of the <see cref="AddList"/> class.
   5:     /// </summary>
   6:     public AddList()
   7:     {
   8:         SPParamCollection parameters = new SPParamCollection();
   9:         parameters.Add(new SPParam("url", "url", true, null, new SPUrlValidator(), "Please specify the web url to add the list to."));
  10:         parameters.Add(new SPParam("urlname", "name", true, null, new SPNonEmptyValidator()));
  11:         parameters.Add(new SPParam("title", "title", true, null, new SPNonEmptyValidator()));
  12:         parameters.Add(new SPParam("featureid", "fid", true, null, new SPGuidValidator()));
  13:         parameters.Add(new SPParam("templatetype", "type", true, null, new SPIntRangeValidator(0, int.MaxValue)));
  14:         parameters.Add(new SPParam("description", "desc", false, null, new SPNonEmptyValidator()));
  15:         parameters.Add(new SPParam("doctemplatetype", "doc", false, null, new SPIntRangeValidator(0, int.MaxValue)));
  16:  
  17:         StringBuilder sb = new StringBuilder();
  18:         sb.Append("\r\n\r\nAdds a list to a web.\r\n\r\nParameters:");
  19:         sb.Append("\r\n\t-url <web url to add the list to>");
  20:         sb.Append("\r\n\t-urlname <the name that will appear in the URL>");
  21:         sb.Append("\r\n\t-title <list title>");
  22:         sb.Append("\r\n\t-featureid <the feature ID to which the list definition belongs>");
  23:         sb.Append("\r\n\t-templatetype <an integer corresponding to the list definition type>");
  24:         sb.Append("\r\n\t[-description <list description>]");
  25:         sb.Append("\r\n\t[-doctemplatetype <the ID for the document template type>]");
  26:         Init(parameters, sb.ToString());
  27:     }
  28:  
  29:    
  30:     #region ISPStsadmCommand Members
  31:  
  32:     /// <summary>
  33:     /// Gets the help message.
  34:     /// </summary>
  35:     /// <param name="command">The command.</param>
  36:     /// <returns></returns>
  37:     public override string GetHelpMessage(string command)
  38:     {
  39:         return HelpMessage;
  40:     }
  41:  
  42:     /// <summary>
  43:     /// Runs the specified command.
  44:     /// </summary>
  45:     /// <param name="command">The command.</param>
  46:     /// <param name="keyValues">The key values.</param>
  47:     /// <param name="output">The output.</param>
  48:     /// <returns></returns>
  49:     public override int Execute(string command, StringDictionary keyValues, out string output)
  50:     {
  51:         output = string.Empty;
  52:  
  53:         try
  54:         {
  55:             string url = Params["url"].Value;
  56:  
  57:             using (SPSite site = new SPSite(url))
  58:             using (SPWeb web = site.OpenWeb())
  59:             {
  60:                 AddListHelper(web.Lists, Params["urlname"].Value, Params["title"].Value, Params["description"].Value,
  61:                               new Guid(Params["featureid"].Value),
  62:                               int.Parse(Params["templatetype"].Value),
  63:                               Params["doctemplatetype"].Value);
  64:             }
  65:         }
  66:         catch (Exception ex)
  67:         {
  68:             Console.WriteLine("An error occured executing the command: {0}\r\n{1}", ex.Message, ex.StackTrace);
  69:             return (int)ErrorCodes.GeneralError;
  70:         }
  71:         return OUTPUT_SUCCESS;
  72:     }
  73:  
  74:     #endregion
  75:  
  76:  
  77:     /// <summary>
  78:     /// Adds a list to the specified list collection.
  79:     /// </summary>
  80:     /// <param name="lists">The lists collection to add the list to.</param>
  81:     /// <param name="urlName">Name of the list to use in the URL.</param>
  82:     /// <param name="title">The title of the list.</param>
  83:     /// <param name="description">The description.</param>
  84:     /// <param name="featureId">The feature id that the list template is associated with.</param>
  85:     /// <param name="templateType">Type of the template.</param>
  86:     /// <param name="docTemplateType">Type of the doc template.</param>
  87:     /// <returns></returns>
  88:     internal static SPList AddListHelper(
  89:         SPListCollection lists, 
  90:         string urlName, 
  91:         string title, 
  92:         string description, 
  93:         Guid featureId, 
  94:         int templateType, 
  95:         string docTemplateType)
  96:     {
  97:         if (docTemplateType == "")
  98:             docTemplateType = null;
  99:  
 100:         Guid guid = lists.Add(title, description, urlName, featureId.ToString("D"), templateType, docTemplateType);
 101:         return lists[guid];
 102:     }
 103:  
 104: }

The help for the command is shown below:

C:\>stsadm -help gl-addlist

stsadm -o gl-addlist


Adds a list to a web.

Parameters:
        -url <web url to add the list to>
        -urlname <the name that will appear in the URL>
        -title <list title>
        -featureid <the feature ID to which the list definition belongs>
        -templatetype <an integer corresponding to the list definition type>
        [-description <list description>]
        [-doctemplatetype <the ID for the document template type>]

The following table summarizes the command and its various parameters:

Command Name Availability Build Date
gl-addlist WSS v3, MOSS 2007 8/6/2008

Parameter Name Short Form Required Description Example Usage
url   Yes The URL of the web to add the list to. -url http://portal/
urlname name Yes The text that will appear in the URL for the list.  So if the web URL is http://portal and you want the list to be reached via http://portal/Lists/ListName/AllItems.aspx you would pass in "Lists/ListName" as the value. -urlname Lists/ListName

-name Lists/ListName
title   Yes The title of the list. -title "A New List"
featureid fid Yes The ID of the Feature that the list is defined in.  You can find this information in the 12/Template/Features/... folders.  For example, the Announcements list is defined in 12/Template/Features/AnnouncementsList. -featureid "00BFEA71-D1CE-42de-9C63-A44004CE0104"

-fid "00BFEA71-D1CE-42de-9C63-A44004CE0104"
templatetype type Yes The template type ID of the list.  Like the Feature ID this information can be obtained from the 12/Template/Features/... folder.  For example, the Announcements list template type ID is 104 and can be found in 12/Template/Features/AnnouncementsList/ListTemplates/Announcements.xml -templatetype 104

-type 104
description desc No A brief description of the list. -description "This is a new list."

-desc "This is a new list."
doctemplatetype doc No A string containing the integer ID for the document template type.  This value corresponds to the Type attribute value specified for a document template in the Onet.xml file of the specified site template.  The following list shows the default possible values: 100 - None, 101 - Word document, 102 - SharePoint Designer Web page, 103 - Excel spreadsheet, 104 - PowerPoint presentation, 105 - Basic page, 106 - Web Part page, 130 - Data connection, 1000 - Blank form.  This parameter only applies to document libraries. -doctemplatetype 100

-doc 100

The following is an example of how to create an announcements list intended specifically for new promotions:

stsadm -o gl-addlist -url http://portal -urlname Lists/Promotions -title Promotions -featureid "00BFEA71-D1CE-42de-9C63-A44004CE0104" -templatetype 104 -description "This list contains all announcements related to employee promotions."

19 comments:

Greg.O said...

Cool, thanks for sharing

Greg

j8KM1QAPyPxIPx09vz4HoSarGQRl04E- said...

Perhaps you could include an option to add a link to the sidebar, as is in the GUI.

Gary Lapointe said...

I thought about that but as I've already got commands to add navigation nodes I decided not to (that and I didn't really have the time to deal with it - maybe I'll look into it at some point).

Mauro Masucci said...

How would you get the ID of a content type which was generated through the UI rather than programmatically?

Gary Lapointe said...

Mauro - you could get the ID a couple of different ways - one would be to edit the content type via the browser and look in the address bar (I believe the content type ID is passed as a query string arg but I'm not in front of an environment to confirm). Another way would be to use my gl-exportcontenttypes command - I use this command to turn content types that I create via the UI into Features.

Anonymous said...

I have to add a new document library to almost 2000 sub sites.


This command is the closest thing I can find to do this.


If I use a value {-urlname "DocLib01/Forms"} it works and creates the document library .

However, the web address for the document library looks like this{...DocLib01/Forms/Forms/AllItems.aspx }. And I do not want the word "Forms" in it twice.


If I use a value {-urlname "DocLib01"} I get the error message:


{An error occured executing the command: The specified name is already in use.
A list, survey, discussion board, or document library cannot have the same name as another list, survey, discussion board, or document library in this Web site. Use your browser's Back button, and type a new name.
at Microsoft.SharePoint.Library.SPRequest.CreateList(String bstrWebUrl, String bstrTitle, String bstrDescription, String bstrListUrl, String bstrFeatureId, Int32 lTemplateID, String bstrDocTemplateType, ListQuickLaunchOptions qlOpt)
at Microsoft.SharePoint.SPListCollection.CreateList(String strTitle, String strDescription, String strListUrl, String strFeatureId, Int32 templateID, String strDocTemplateType, QuickLaunchOptions qlOpt)
at Microsoft.SharePoint.SPListCollection.Add(String strTitle, String strDescription, String strUrl, String strFeatureId, Int32 templateType, String docTemplateType, QuickLaunchOptions quickLaunchOptions)
at Microsoft.SharePoint.SPListCollection.Add(String strTitle, String strDescription, String strUrl, String strFeatureId, Int32 templateType, String docTemplateType)
at Lapointe.SharePoint.STSADM.Commands.Lists.AddList.AddListHelper(SPListCollection lists, String urlName, String title, String description, Guid featureId, Int32 templateType, String docTemplateType)
at Lapointe.SharePoint.STSADM.Commands.Lists.AddList.AddListHelper(String url, String urlName, String title, String desc, Guid featureId, Int32 templateType, String docTemplateType)
at Lapointe.SharePoint.STSADM.Commands.Lists.AddList.Execute(String command, StringDictionary keyValues, String& output)}.


Do you have another stsadm command that will create a document library? If not, can you suggest how to maybe use this command to get what I want?

Thanks

Gary Lapointe said...

Are you sure that the library definitely doesn't already exist? I'm simply passing the value straight into the SPListCollection's Add method (via the SPWeb.Lists property). Also, for what you are doing you might be better using PowerShell (you get much better flow constructs using PowerShell and the OM directly.

Bas said...

Hello Gary,

I added an extra parameter to your gl-addlist command. With this parameter you can enable (major and/or) minor versioning on the list. If you're interested to include this functionality in your build, let me know. I can mail you the AddList.cs

With kind regards,
Bastiaan

Gary Lapointe said...

That would be great, thanks!

Anonymous said...

Hi Gary. It might be nice is this command featured the "-onquicklaunch" parameter from the gl-setlistproperties command. It would remove the need to call both - and also bypass the issue of gl-setlistproperties overwriting the list description if the -description parameter has not been supplied. Thanks.

Halvor said...

Hi,

First of all - Great blog!

I was just wondering if it's possable to do deploy a CustomTemplate using this?

When I create one manualy it seems like Im also posting a CustomTemplate=TemplateName.stp when I create the new libary - can I get that into this feature somehow?

Thanks,
Halvor

Anonymous said...

Hello, I'm trying to add a discussion list to an internal site in server1 using the stsadm extension installed in server2 by running
stsadm -o gl-addlist -url http://server1/sites/sp2sp/Lists/Discussions/AllItems.aspx -urlname sites/sp2sp/Lists/Discussions -title Discussions -featureid "00BFEA71-6A49-43FA-B535-D15C05500108" -templatetype 108

I get an error saying the web application http://server1/sites/sp2sp/Lists/Discussions/AllItems.aspx could not be found, but that is what I want to create.... Am I missing somehting??

Thank you!

Gary Lapointe said...

The URL is for the web not the list. Please see the examples provided in the blog post.

Anonymous said...

Thanks Gary! I fixed that part, but still get an error that the web application was not found.

I type the URL on the browser and it works. This are the two alternatives I tried

stsadm -o gl-addlist -url http://testserver:222/sites/sp2sp/ -urlname Lists/Discussions -title Discussions -featureid "00BFEA71-6A49-43FA-B535-D15C05500108" -templatetype 108 -description "Discussion list."

stsadm -o gl-addlist -url http://testserver:222 -urlname sites/sp2sp/Lists/Discussions -title Discussions -featureid "00BFEA71-6A49-43FA-B535-D15C05500108" -templatetype 108 -description "Discussion list."

Gary Lapointe said...

Make sure you're using an account with appropriate rights. Also make sure that you are using the default AAM URL.

Anonymous said...

yes. the under web application list, the application is listed as
http://testserver:222.

The server I'm running the command from, I'm logged with the farm administration account (the same account has permissions on the database)

Do I need a different permission or the problem is because I'm running from a different server? (testserver 2)

Thanks

Anonymous said...

yes. the under web application list, the application is listed as
http://testserver:222.

The server I'm running the command from, I'm logged with the farm administration account (the same account has permissions on the database)

Do I need a different permission or the problem is because I'm running from a different server? (testserver 2)

Thanks

Anonymous said...

Hi! Gary, thanks for sharing.
Just a question
It's possible to create a list ussing a customm list template??
How can i get the param's doctemplatetype and templatetype to apply a custom list???
Thanks a lot.

Gary Lapointe said...

The templatetype parameter is just an integer so yes, you should be able to use this to create a list based off of a custom list template.