Using the SharePoint 2010 Client Object Model - Part 4
In the first three parts of this series we’ve gone through quite a bit of code that shows how to retrieve data from lists. In this post, we’re going to show how to actually create a list and manage fields.
In the client object model you’ll see a familiar naming pattern of “someobjectCreationInformation” used to create new items. Creating a new list is no different – we’re going to use something called the ListCreationInformation class. I’m going to start out creating an instance of the class that will define my new list:
//create a new listcreationinfo object
ListCreationInformation lc = new ListCreationInformation();
lc.Title = ListTitleTxt.Text;
lc.Description = ListDescTxt.Text;
lc.TemplateType = lt.ListTemplateTypeKind;
So what is this property called TemplateType? The ListTemplate class has a property called ListTemplateTypeKind that can be used for this purpose. For my sample application I had previously retrieved a list of ListTemplates using code like this:
//get the connection
ClientContext ctx = new ClientContext("https://foo");
//get the list
ListTemplateCollection ltc = ctx.Web.ListTemplates;
//select the items
ctx.Load(ltc);
//execute the query
ctx.ExecuteQuery();
//enumerate the results
foreach (ListTemplate lt in ltc)
{
//store it somewhere
}
You obviously can’t follow the code literally here because the lt variable would no longer be in scope in the sample above. However I wrote it up this way to try and illustrate the concepts more clearly. So getting back to our ListCreationInformation class, we’ve set the Title, Description and TemplateType properties. All we need to do now is add it to the collection of lists in the web and execute the query to process our code. Here’s how we do that:
//create the list
List newList = ctx.Web.Lists.Add(lc);
//send the request
ctx.ExecuteQuery();
That’s it – our list has been created. So what if we want to do the opposite – delete our list? It’s pretty simple really. We just get our list and use another common method pattern for deleting items with the client object model: DeleteObject. Here’s an example of that:
//get the connection
ClientContext ctx = new ClientContext("https://foo");
//get the list
List theList = ctx.Web.Lists.GetByTitle("My List Title");
theList.DeleteObject();
//execute the query
ctx.ExecuteQuery();
Okay, so we can create and delete lists. The next step is to be able to enumerate, add and delete fields in that list. Let’s take a look at that. Enumerating fields follows what should be a familiar pattern at this point. We get our parent object – the list – and then load the contents of a collection – the fields. We execute our query and then we can enumerate all of the items in the collection. Here’s a sample:
//get the connection
ClientContext ctx = new ClientContext("https://foo");
//get the fields
FieldCollection flds = ctx.Web.Lists.GetByTitle("My List Title").Fields;
//select the items
ctx.Load(flds);
//execute the query
ctx.ExecuteQuery();
//enumerate the results
foreach (Field fld in flds)
{
//do something with each field
}
Okay, this is hopefully feeling fairly comfortable at this point. So how do you think we add a new field? Well…it’s a little different of course. The easiest way to do that is just to create the Xml definition of a field and add it that way. The FieldCollection class has an AddFieldAsXml method designed just for this purpose. So as you might imagine, we have to get a reference to the FieldCollection for a list, and then call the AddFieldAsXml method. That looks something like this:
//get the connection
ClientContext ctx = new ClientContext("https://foo");
//get the list
List theList = ctx.Web.Lists.GetByTitle("My List Title");
//add the field
Field fld = theList.Fields.AddFieldAsXml("some xml", true,
AddFieldOptions.DefaultValue);
So what does that field xml look like? Fortunately it is pretty much what you already know from SharePoint 2007. In fact, you can get the complete schema today for creating a field definition in Xml at https://msdn.microsoft.com/en-us/library/ms437580.aspx. Here’s a simple example of the Xml I used when putting this demo together:
<Field Name='YouLuvClientOM' DisplayName='DoYouLuvtheClientOM' Type='Number' Hidden='False' Description='This is a field I created in the client OM' />
Yep, that’s not too bad at all. Now keep in mind I still haven’t added my field. There’s one other thing I wanted to show you. Different types of fields have different options associated with them. For example, for a Number field you can set the minimum and maximum value, a Currency field has a currency locale, etc. You can work with these type-specific properties by coercing your Field instance into type-specific field instance. In the example above I created a field of type Number. If I want to set the minimum and maximum properties for the field then I need to coerce it into a class of type FieldNumber. Here’s how we do that:
FieldNumber fldNumber = ctx.CastTo<FieldNumber>(fld);
fldNumber.MaximumValue = 100;
fldNumber.MinimumValue = 35;
fldNumber.Update();
Now that I’ve got my field all configured, I only have to phone home to the server to complete the exercise:
//execute the query to create the field
ctx.ExecuteQuery();
Okay, last step for this posting – let’s delete a field. Fortunately it’s very easy and follows a similar pattern to deleting a list:
//get the connection
ClientContext ctx = new ClientContext("https://foo");
//get the list
List theList = ctx.Web.Lists.GetByTitle("My List Title");
//get the field
fld = theList.Fields.GetByTitle("MyFieldInternalName");
//delete the field
fld.DeleteObject();
//execute the query
ctx.ExecuteQuery();
And there we go – our field is deleted, again using the familiar pattern of someClass.DeleteObject(). Hopefully by now you are seeing that the client object model is a whole lot more powerful and easy to use than the web services that were included in SharePoint 2007. No complex Xml to work with, no proxies to deal with, just the warm safe comfortable feeling of tooling around your garden variety object model.
Coming Next…
We’re not done yet. In the next post in this series I’ll walk you through working with security in the client object model.