Inserting Sharepoint List Item using SPMetal Classes

Microsoft has introduced a very useful tool, in the form of SPMetal, for performing CRUD (Create Read Update Delete) operations on sharepoint lists. This article shows how to insert a new item into a list. The below screen shot has an example with its explanation as given below.

Insert item using SPMetal

Sample source code

If you have not yet generated the Data Context and entity classes, follow the below link and generate your entity model –

Using SPMetal With Paramenters

  1. Instantiate an object of the data Context class by passing the site Url as a parameter.
    • DemoDataContext demoDataContext = new DemoDataContext(spWeb.Url);
  2. Create a generic object of EntityList having the List Entity as its source.
    • EntityList<CitiesObject> cities = demoDataContext.GetList<CitiesObject>(“Cities”);
    • The EntityList class can be found in  Microsoft.Sharepoint.Linq namespace.
    • In this example I have taken a list named Cities which has three custom columns namely CityName, State and Country apart from the out-of-the-box columns.
    • The entity corresponding to Cities is CitiesObject, which is passed to the generic method.
    • The GetList method of the DataContext object returns a reference to the List to which we are adding an Item.
  3. Create and instantiate an object of List type which is passed as source to the EntityList class above.
    • CitiesObject city = new CitiesObject() { Title=”New City”, CityName=”Pune”,Country=”India”,State=”Maharashtra”};
    • In my case I have created an object of type CitiesObject and have assigned value to its properties.
  4. Add the list item to list.
    • cities.InsertOnSubmit(city);
    • The above method InsertOnSubmit adds the list item to list. But these changes remain in memory.
    • If we have a collection of List Items, we can add the whole collection at on go, using a Method called InsertAllOnSubmit(IEnumerable<T>)
  5. Persist the changes
    • demoDataContext.SubmitChanges();
    • The SubmitChanges method is where the changes made above are actually persisted in the content Database.

Using SPMetal with parameters

SPMetal is a very useful tool in Sharepoint 2010, introduced by Microsoft for creating  Entity Data Model of the underlying Sharepoint lists. Though it is still at a very nascent stage, it can still be very productive as far as sharepoint customization in .Net is concerned.

Well you might get many articles telling you how to generate the entity classes  using SPMetal .

Hence I would concentrate more on the configuration part of SPMetal. The default command for generating entities is as follows:

SPMetal /web:http://<ServerName>/<SiteName> /code:<EntityClassName>.cs 

In the above command, we have passed two arguments. The first one tells us the site for which we are generating the entities, the second one specifies the filename in which the entity classes are to be generated. The file thus generated will have entity classes for all the lists in the site. In fact it will have classes for all the content types too. i.e by default it will have classes inheriting from “item” and “Folder” content type. The entity classes in turn would have all the fields in the lists.

There would hardly be a case where you need all the entities and fields. Hence SPMetal gives you a functionality where in which you can limit the number of entities generated, the content types for which entity is generated and the fields that are to be included.

This can be achieved by passing a third argument to the above command. This argument refers an XML file which hosts configuration for the lists and fields which are required.

SPMetal /web:http://<ServerName>/<SiteName> /code:<EntityClassName>.cs /parameters: ParamElements.xml 

The above command has an argument named parameters meaning the parameters based on which the entities would be generated. The content of the xml file could be configured as given below:


Parameters XML to be passed as an argument to the SPMetal command

As can be seen in the above xml, it starts with an element named Web. Apart from the reference to the SPMetal command we have an attribute named class. This is an optional value where you can assign a value to the Data context class which is generated through this attribute. Along with class you can also specify the AccessModifier for the Data Context class.

Inside the web element is the List element. The Name attribute specifies the List of which an entity has to be created. Below the List element, is the ExcludeOtherLists element. By using this element we are telling SPMetal that it only needs to consider lists which are mentioned in the List element.

Within the List element is the element for ContentType where we have mentioned the name as Item. Below the ContentType Tag is the ExcludeContentType element which has name attribute set to Folder. This element tells the SPMetal command to exclude the Folder Content Type.

Similarly, inside the ContentType element, we have explicitly mentioned the columns which are required in the form of class properties of the list entity. We have explicitly asked SPMetal to ignore all the columns which are not mentioned in the columns element. The Name attribute in the column element refers the name of the field as it is used in CAML query. The Member attribute specifies the name we want to keep for this column in the entity class. We can have similar  names for the entity classes generated by having a Member attribute at the list level.

The post is based on my understanding of SPMetal until now. Will update it as and when new things arise.