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.

Monday, July 6, 2009

Setting List Properties using STSADM

Recently I had a reader of my blog send me a modified version of my gl-addlist command in which he added some additional properties to set a couple of the SPList properties (specifically the versioning settings).  In thinking about this I decided that it might be helpful to have a command specifically for setting most of the SPList properties rather than try to incorporate them into a more general command like the gl-addlist command so I decided to create a new command that I called gl-setlistproperties.

Now ideally you would just use PowerShell to set list properties and you can do so pretty easily using my custom CmdLet: Get-SPList.  Here’s an example of how you could do this using my CmdLet:

$list = Get-SPList http://portal/documents
$list.EnableVersioning = $true
$list.EnableMinorVersions = $true
$list.EnableModeration = $true
$list.Update()

For a full list of the properties that you can set see the SPList documentation in the SDK. But if you’re not a PowerShell guy and prefer batch files then you can use my gl-setlistproperties command instead. The code, as you can imagine, is really simple:

   1: using System;
   2: using System.Collections.Specialized;
   3: using System.Text;
   4: using Lapointe.SharePoint.STSADM.Commands.OperationHelpers;
   5: using Lapointe.SharePoint.STSADM.Commands.SPValidators;
   6: using Microsoft.SharePoint;
   7:  
   8: namespace Lapointe.SharePoint.STSADM.Commands.Lists
   9: {
  10:     public class SetListProperties : SPOperation
  11:     {
  12:         internal enum VersionSettings {None, Major, MajorMinor}
  13:         /// <summary>
  14:         /// Initializes a new instance of the <see cref="SetListProperties"/> class.
  15:         /// </summary>
  16:         public SetListProperties()
  17:         {
  18:             SPParamCollection parameters = new SPParamCollection();
  19:             parameters.Add(new SPParam("url", "url", true, null, new SPUrlValidator(), "Please specify URL to the list."));
  20:             SPEnumValidator versionValidator = new SPEnumValidator(typeof(VersionSettings));
  21:             parameters.Add(new SPParam("versioning", "version", false, null, versionValidator, "Please specify the version settings."));
  22:             SPEnumValidator draftVisibilityValidator = new SPEnumValidator(typeof(DraftVisibilityType));
  23:             parameters.Add(new SPParam("draftvisibility", "dvv", false, null, draftVisibilityValidator));
  24:             parameters.Add(new SPParam("majorversionlimit", "mvl", false, "0", new SPIntRangeValidator(0, 50000)));
  25:             parameters.Add(new SPParam("majorwithminorversionlimit", "mmvl", false, "0", new SPIntRangeValidator(0, 50000)));
  26:             parameters.Add(new SPParam("forcecheckout", "fc", false, null, new SPTrueFalseValidator()));
  27:             parameters.Add(new SPParam("enablemoderation", "mod", false, null, new SPTrueFalseValidator()));
  28:             parameters.Add(new SPParam("enablecontenttypes", "ect", false, null, new SPTrueFalseValidator()));
  29:             parameters.Add(new SPParam("enablefoldercreation", "efc", false, null, new SPTrueFalseValidator()));
  30:             parameters.Add(new SPParam("allowdeletion", "del", false, null, new SPTrueFalseValidator()));
  31:             parameters.Add(new SPParam("alloweveryoneviewitems", "aevi", false, null, new SPTrueFalseValidator()));
  32:             parameters.Add(new SPParam("enablesyndication", "syn", false, null, new SPTrueFalseValidator()));
  33:             parameters.Add(new SPParam("hidden", "hidden", false, null, new SPTrueFalseValidator()));
  34:             parameters.Add(new SPParam("onquicklaunch", "oql", false, null, new SPTrueFalseValidator()));
  35:             SPEnumValidator itemOpenValidator = new SPEnumValidator(typeof(DefaultItemOpen));
  36:             parameters.Add(new SPParam("defaultitemopen", "open", false, null, itemOpenValidator));
  37:             parameters.Add(new SPParam("ordered", "ordered", false, null, new SPTrueFalseValidator()));
  38:             parameters.Add(new SPParam("title", "title", false, null, new SPNullOrNonEmptyValidator()));
  39:             parameters.Add(new SPParam("description", "desc", false, null, new SPNullOrNonEmptyValidator()));
  40:             parameters.Add(new SPParam("nocrawl", "nocrawl", false, null, new SPTrueFalseValidator()));
  41:             parameters.Add(new SPParam("enableattachments", "att", false, null, new SPTrueFalseValidator()));
  42:  
  43:             StringBuilder sb = new StringBuilder();
  44:             sb.Append("\r\n\r\nSets various properties of a list.\r\n\r\nParameters:");
  45:             sb.Append("\r\n\t-url <URL to the list to update>");
  46:             sb.Append("\r\n\t[-title <title of the list>]");
  47:             sb.Append("\r\n\t[-description <title of the list>]");
  48:             sb.AppendFormat("\r\n\t[-versioning <{0}>", versionValidator.DisplayValue);
  49:             sb.AppendFormat("\r\n\t[-draftvisibility <{0}>", draftVisibilityValidator.DisplayValue);
  50:             sb.Append("\r\n\t[-majorversionlimit <0 - 50000>]");
  51:             sb.Append("\r\n\t[-majorwithminorversionlimit <0 - 50000>]");
  52:             sb.Append("\r\n\t[-forcecheckout <true | false>]");
  53:             sb.Append("\r\n\t[-enablemoderation <true | false>]");
  54:             sb.Append("\r\n\t[-enablecontenttypes <true | false>]");
  55:             sb.Append("\r\n\t[-enablefoldercreation <true | false>]");
  56:             sb.Append("\r\n\t[-allowdeletion <true | false>]");
  57:             sb.Append("\r\n\t[-alloweveryoneviewitems <true | false>]");
  58:             sb.Append("\r\n\t[-enablesyndication <true | false>]");
  59:             sb.Append("\r\n\t[-hidden <true | false>]");
  60:             sb.Append("\r\n\t[-onquicklaunch <true | false>]");
  61:             sb.AppendFormat("\r\n\t[-defaultitemopen <{0}>", itemOpenValidator.DisplayValue);
  62:             sb.Append("\r\n\t[-ordered <true | false>]");
  63:             sb.Append("\r\n\t[-nocrawl <true | false>]");
  64:             sb.Append("\r\n\t[-enableattachments <true | false>]");
  65:             Init(parameters, sb.ToString());
  66:         }
  67:  
  68:        
  69:         #region ISPStsadmCommand Members
  70:  
  71:         /// <summary>
  72:         /// Gets the help message.
  73:         /// </summary>
  74:         /// <param name="command">The command.</param>
  75:         /// <returns></returns>
  76:         public override string GetHelpMessage(string command)
  77:         {
  78:             return HelpMessage;
  79:         }
  80:  
  81:         /// <summary>
  82:         /// Runs the specified command.
  83:         /// </summary>
  84:         /// <param name="command">The command.</param>
  85:         /// <param name="keyValues">The key values.</param>
  86:         /// <param name="output">The output.</param>
  87:         /// <returns></returns>
  88:         public override int Execute(string command, StringDictionary keyValues, out string output)
  89:         {
  90:             output = string.Empty;
  91:             Verbose = true;
  92:  
  93:             string url = Params["url"].Value.TrimEnd('/');
  94:  
  95:             using (SPSite site = new SPSite(url))
  96:             using (SPWeb web = site.OpenWeb())
  97:             {
  98:                 SPList list = Utilities.GetListFromViewUrl(web, url);
  99:  
 100:                 if (list == null)
 101:                     throw new SPException("List was not found.");
 102:  
 103:  
 104:                 if (Params["versioning"].UserTypedIn)
 105:                 {
 106:                     VersionSettings versioning =
 107:                         (VersionSettings) Enum.Parse(typeof (VersionSettings), Params["versioning"].Value, true);
 108:                     SetVersioning(list, versioning);
 109:                 }
 110:  
 111:  
 112:                 SetProperties(list,
 113:                     GetValue(list.Title, "title"),
 114:                     GetValue(list.Title, "description"),
 115:                     GetValue(list.ContentTypesEnabled, "enablecontenttypes"),
 116:                     GetValue(list.DraftVersionVisibility, "draftvisibility"),
 117:                     GetValue(list.MajorVersionLimit, "majorversionlimit"),
 118:                     GetValue(list.MajorWithMinorVersionsLimit, "majorwithminorversionlimit"),
 119:                     GetValue(list.ForceCheckout, "forcecheckout"),
 120:                     GetValue(list.EnableModeration, "enablemoderation"),
 121:                     GetValue(list.EnableFolderCreation, "enablefoldercreation"),
 122:                     GetValue(list.AllowDeletion, "allowdeletion"),
 123:                     GetValue(list.AllowEveryoneViewItems, "alloweveryoneviewitems"),
 124:                     GetValue(list.EnableSyndication, "enablesyndication"),
 125:                     GetValue(list.DefaultItemOpen, "defaultitemopen"),
 126:                     GetValue(list.Hidden, "hidden"),
 127:                     GetValue(list.OnQuickLaunch, "onquicklaunch"),
 128:                     GetValue(list.Ordered, "ordered"),
 129:                     GetValue(list.NoCrawl, "nocrawl"),
 130:                     GetValue(list.EnableAttachments, "enableattachments"));
 131:  
 132:                 list.Update();
 133:             }
 134:  
 135:             return OUTPUT_SUCCESS;
 136:         }
 137:  
 138:         #endregion
 139:  
 140:         /// <summary>
 141:         /// Gets the value.
 142:         /// </summary>
 143:         /// <typeparam name="T"></typeparam>
 144:         /// <param name="defaultValue">The default value.</param>
 145:         /// <param name="paramName">Name of the param.</param>
 146:         /// <returns></returns>
 147:         private T GetValue<T>(T defaultValue, string paramName)
 148:         {
 149:             if (!Params[paramName].UserTypedIn)
 150:                 return defaultValue;
 151:  
 152:             string val = Params[paramName].Value;
 153:             if (typeof(T).IsEnum)
 154:                 return (T) Enum.Parse(typeof (T), val, true);
 155:  
 156:             return (T)Convert.ChangeType(val, typeof (T));
 157:  
 158:         }
 159:  
 160:         /// <summary>
 161:         /// Sets the properties.
 162:         /// </summary>
 163:         /// <param name="list">The list.</param>
 164:         /// <param name="title">The title.</param>
 165:         /// <param name="description">The description.</param>
 166:         /// <param name="contentTypesEnabled">if set to <c>true</c> [content types enabled].</param>
 167:         /// <param name="draftVisibility">The draft visibility.</param>
 168:         /// <param name="majorVersionLimit">The major version limit.</param>
 169:         /// <param name="majorWithMinorVersionLimit">The major with minor version limit.</param>
 170:         /// <param name="forceCheckout">if set to <c>true</c> [force checkout].</param>
 171:         /// <param name="enableModeration">if set to <c>true</c> [enable moderation].</param>
 172:         /// <param name="enableFolderCreation">if set to <c>true</c> [enable folder creation].</param>
 173:         /// <param name="allowDeletion">if set to <c>true</c> [allow deletion].</param>
 174:         /// <param name="allowEveryoneViewItems">if set to <c>true</c> [allow everyone view items].</param>
 175:         /// <param name="enableSyndication">if set to <c>true</c> [enable syndication].</param>
 176:         /// <param name="itemOpen">The item open.</param>
 177:         /// <param name="hidden">if set to <c>true</c> [hidden].</param>
 178:         /// <param name="onQuickLaunch">if set to <c>true</c> [on quick launch].</param>
 179:         /// <param name="ordered">if set to <c>true</c> [ordered].</param>
 180:         /// <param name="noCrawl">if set to <c>true</c> [no crawl].</param>
 181:         /// <param name="enableAttachments">if set to <c>true</c> [enable attachments].</param>
 182:         private void SetProperties(SPList list,
 183:             string title,
 184:             string description,
 185:             bool contentTypesEnabled,
 186:             DraftVisibilityType draftVisibility,
 187:             int majorVersionLimit,
 188:             int majorWithMinorVersionLimit,
 189:             bool forceCheckout,
 190:             bool enableModeration,
 191:             bool enableFolderCreation,
 192:             bool allowDeletion,
 193:             bool allowEveryoneViewItems,
 194:             bool enableSyndication,
 195:             DefaultItemOpen itemOpen,
 196:             bool hidden,
 197:             bool onQuickLaunch,
 198:             bool ordered,
 199:             bool noCrawl,
 200:             bool enableAttachments)
 201:         {
 202:             list.Title = title;
 203:             list.Description = description;
 204:  
 205:             if (list.AllowContentTypes || !contentTypesEnabled)
 206:                 list.ContentTypesEnabled = contentTypesEnabled;
 207:  
 208:             list.DraftVersionVisibility = draftVisibility;
 209:  
 210:             if (enableModeration && list.BaseTemplate == SPListTemplateType.PictureLibrary)
 211:                 Log("WARNING: Cannot set moderation on a picture library.");
 212:             else
 213:                 list.EnableModeration = enableModeration;
 214:  
 215:             if (list.EnableVersioning)
 216:                 list.MajorVersionLimit = majorVersionLimit;
 217:  
 218:             if (list.EnableMinorVersions && list.EnableModeration)
 219:                 list.MajorWithMinorVersionsLimit = majorWithMinorVersionLimit;
 220:  
 221:  
 222:             if (list.BaseTemplate == SPListTemplateType.DocumentLibrary)
 223:                 list.ForceCheckout = forceCheckout;
 224:             else if (forceCheckout)
 225:                 Log("WARNING: Force checkout can only be set on document libraries.");
 226:  
 227:             list.EnableFolderCreation = enableFolderCreation;
 228:             list.AllowDeletion = allowDeletion;
 229:             list.AllowEveryoneViewItems = allowEveryoneViewItems;
 230:             list.EnableSyndication = enableSyndication;
 231:             list.DefaultItemOpen = itemOpen;
 232:             list.Hidden = hidden;
 233:             list.OnQuickLaunch = onQuickLaunch;
 234:             list.NoCrawl = noCrawl;
 235:             
 236:             if (list.BaseTemplate == SPListTemplateType.GenericList)
 237:                 list.Ordered = ordered;
 238:             else if (ordered)
 239:                 Log("WARNING: The Ordered property can only be set for generic lists.");
 240:  
 241:             if (!enableAttachments)
 242:                 list.EnableAttachments = false;
 243:             else
 244:             {
 245:                 if (!(list.BaseType == SPBaseType.DocumentLibrary || list.BaseType == SPBaseType.Survey))
 246:                     list.EnableVersioning = true;
 247:                 else
 248:                     Log("WARNING: Attachments are only allowed on document libraries and surveys.");
 249:             }
 250:  
 251:  
 252:         }
 253:  
 254:         /// <summary>
 255:         /// Sets the versioning.
 256:         /// </summary>
 257:         /// <param name="list">The list.</param>
 258:         /// <param name="versioning">The versioning.</param>
 259:         private void SetVersioning(SPList list, VersionSettings versioning)
 260:         {
 261:             switch (versioning)
 262:             {
 263:                 case VersionSettings.None:
 264:                     list.EnableVersioning = false;
 265:                     list.EnableMinorVersions = false;
 266:                     break;
 267:                 case VersionSettings.Major:
 268:                     list.EnableVersioning = true;
 269:                     list.EnableMinorVersions = false;
 270:                     break;
 271:                 case VersionSettings.MajorMinor:
 272:                     list.EnableVersioning = true;
 273:                     list.EnableMinorVersions = true;
 274:                     break;
 275:             }
 276:         }
 277:     }
 278: }

The help for the command is shown below:

C:\>stsadm -help gl-setlistproperties

stsadm -o gl-setlistproperties


Sets various properties of a list.

Parameters:
        -url <URL to the list to update>
        [-title <title of the list>]
        [-description <title of the list>]
        [-versioning <none | major | majorminor>
        [-draftvisibility <reader | author | approver>
        [-majorversionlimit <0 - 50000>]
        [-majorwithminorversionlimit <0 - 50000>]
        [-forcecheckout <true | false>]
        [-enablemoderation <true | false>]
        [-enablecontenttypes <true | false>]
        [-enablefoldercreation <true | false>]
        [-allowdeletion <true | false>]
        [-alloweveryoneviewitems <true | false>]
        [-enablesyndication <true | false>]
        [-hidden <true | false>]
        [-onquicklaunch <true | false>]
        [-defaultitemopen <preferclient | browser>
        [-ordered <true | false>]
        [-nocrawl <true | false>]
        [-enableattachments <true | false>]

The following table summarizes the command and its various parameters:

Command Name Availability Build Date
gl-setlistproperties WSS 3.0
MOSS 2007
Released: 7/6/2009

Parameter Name Short Form Required Description Example Usage
url   Yes The URL of the list or library to update. -url http://portal/documents
title   No String representing the title of the list.  Corresponds to the SPList.Title property. -title Documents
description desc No String representing the description of the list.  Corresponds to the SPList.Description property. -description "Shared Documents"

-desc "Shared Documents"
versioning version No Sets whether to enable versioning and if minor versions should be created or not (sets the SPList.EnableVersioning and the SPList.EnableMinorVersions properties).  Valid values are “none”, “major”, and “majorminor”. -versioning majorminor

-version majorminor
draftvisibility dvv No Sets a value that determines the type of user who can view minor versions of document drafts within the list.  Corresponds to the SPList.DraftVersionVisibility property.  Valid values are “reader”, “author”, and “approver”. -draftvisibility approver

-dvv approver
majorversionlimit mvl No

Sets the maximum number of major versions allowed for an item in a document library that uses version control with major versions only.  Corresponds to the SPList.MajorVersionLimit property.

-majorversionlimit 3

-mvl 3
majorwithminorversionlimit mmvl No Sets the maximum number of major versions that are allowed for an item in a document library that uses version control with both major and minor versions.  Corresponds to the SPList.MajorWithMinorVersionsLimit property. -majorwithminorversionlimit 3

-mmvl 3
forcecheckout fc No Sets whether forced checkout is enabled for the document library.  Valid values are “true” and “false”.  Corresponds to the SPList.ForceCheckout property. -forcecheckout true

-fc true
enablemoderation mod No Sets whether Content Approval is enabled for the list.  Valid values are “true” and “false”.  Corresponds to the SPList.EnableModeration property. -enablemoderation true

-mod true
enablecontenttypes ect No Sets whether content types are enabled for the list.  Valid values are “true” and “false”.  Corresponds to the SPList.ContentTypesEnabled property. -enablecontenttypes true

-ect true
enablefoldercreation efc No Sets whether folders can be created for the list.  Valid values are “true” and “false”.  Corresponds to the SPList.EnableFolderCreation property. -enablefoldercreation true

-efc true
allowdeletion del No Sets whether the list can be deleted.  Valid values are “true” and “false”.  Corresponds to the SPList.AllowDeletion property. -allowdeletion true

-del true
alloweveryoneviewitems aevi No Sets whether everyone can view documents in the document library or attachments to items in the list.  Valid values are “true” and “false”.  Corresponds to the SPList.AllowEveryoneViewItems property. -alloweveryoneviewitems true

-aevi true
enablesyndication syn No Sets whether RSS syndication is enabled for the list.  Valid values are “true” and “false”.  Corresponds to the SPList.EnableSyndication property. -enablesyndication true

-syn true
hidden   No Sets whether the list is hidden.  Valid values are “true” and “false”.  Corresponds to the SPList.Hidden property. -hidden false
onquicklaunch oql No Sets whether the list appears on the Quick Launch of the home page.  Valid values are “true” and “false”.  Corresponds to the SPList.OnQuickLaunch property. -onquicklaunch true

-oql true
defaultitemopen open No Sets whether to open list items in a client application or in the browser.  Valid values are “preferclient” and “browser”.  Corresponds to the SPList.DefaultItemOpen property. -defaultitemopen preferclient

-open preferclient
ordered   No Sets whether the option to allow users to reorder items in the list is available on the Edit View page for the list.  Valid values are “true” and “false”.  Corresponds to the SPList.Ordered property. -ordered true
nocrawl   No Sets whether crawling is enabled for the list.  Valid values are “true” and “false”.  Corresponds to the SPList.NoCrawl property. -nocrawl false
enableattachments att No Sets whether attachments can be added to items in the list.  Valid values are “true” and “false”.  Corresponds to the SPList.EnableAttachments property. -enableattachments false

-att false

The following is an example of how to set a few properties on a list:

stsadm -o gl-setlistproperties -url http://portal/documents -versioning majorminor -enablemoderation true -draftvisibility approver

Note that I'm not exposing every property on the SPList class but I believe I've hit the more widely used ones.

2 comments:

Bas said...

Hi Gary. Cool that you've created a whole new command for this functionality! Appreciate it.

Christian said...

Hi Gary,

In the gl-setlistproperties command, why does the majorwithminorversionlimit parameter need the Content Approval to be enabled?

if (list.EnableMinorVersions && list.EnableModeration) list.MajorWithMinorVersionsLimit = majorWithMinorVersionLimit;

In the web interface, the content approval doesn't need to be enabled for the "Keep drafts for the following number of major versions" to be used.

Thanks,
Christian