Core Components

The list repository feature of the SharePoint Application block contains two helper classes:
  • ListRepositoryMapper<T>. This class transfers data between SharePoint ListItem objects and strongly-typed business entity objects that you implement. The type parameter T is instantiated with the business entity type.
  • CAMLQueryBuilder. This class provides methods that create a query using the CAML syntax.

The ListRepositoryMapper<T> Class

This ListRepositoryMapper<T> class transfers data between SharePoint ListItem objects and strongly-typed business entity objects that you implement. The type parameter T is instantiated with the business entity type. It exposes three methods named AddMapping, CreateEntity and FillSPListItemFromEntity.

There are two sequential phases of operation for instances of the ListRepositoryMapper<T> class. The first is a mapping setup phase and the second is a data transfer phase.

Figure XX
Operational Phases of ListRepositoryMapper<T> instances

During the mapping setup phase, the AddMapping method is invoked one or more times to create associations between SharePoint list item field IDs and public properties of a strongly-typed business entity class. After all of the mappings have been made, the CreateEntity method and FillSPListItemFromEntity method can be invoked as many times as needed and in any order. These methods transfer data to and from SharePoint list items.

Internally, the ListRepositoryMapper<T> class stores its field map in an instance variable that uses the .NET Framework list type. The FieldToEntityPropertyMapping class is used to encode each pair of field IDs and property names.

The AddMapping method takes a list field ID and an entity property name as arguments. The list field ID is a GUID that identifies a field of a SharePoint list. The property name is a string that matches the name of a public property of the business entity class that was used to instantiate the generic ListRepositoryMapper<T> class.

Note: The field types in the SharePoint list must be compatible with the .NET Framework types of the public properties of the business entity. The .NET Framework string and int types are commonly used.

During the data transfer phase, the CreateEntity method takes a SharePoint list item as its argument and returns an instance of the business entity class that was used to instantiate the generic ListRepositoryMapper<T> class. The method iterates through each of the field mappings that were previously established by the AddMapping method and copies SharePoint list item field values into the public properties of a new instance of the business entity class.

The FillSPListItemFromEntity method takes a SharePoint list item and a business entity object as its arguments. The method iterates through each of the field mappings previously established by the AddMapping method and copies public property values from the business entity into the SharePoint list item.

Note: Copying the fields does not have an immediate effect in SharePoint. The SharePoint object model requires that you also invoke the list item's Update method.

The CAMLQueryBuilder Class

The CAMLQueryBuilder class uses a pattern that is similar to the .NET Framework's StringBuilder class. A new instance of a CAMLQueryBuilder class corresponds to an empty CAML query. You then call methods that incrementally add clauses to the query. Finally, you call a Build method to extract a query that you can provide to SharePoint's GetItems method.

The methods that add clauses to the query are:
  • AddEqual. This method inserts a clause that tests whether a given list item field matches a chosen value.
  • AddNotEqual. This method inserts a clause that tests whether a given list item field does not equal the value given as an argument.
  • FilterByContentType. This method adds a clause to the query to select only list item records of a given content type.
  • AddFilter. This method allows you to add a custom CAML clause to the query.
The AddEqual method inserts a clause that tests whether a given list item field matches a chosen value. There are eight overloaded methods for AddEqual. These are shown in the following code.
C#
public void AddEqual(string name, string value)
public void AddEqual(string name, int value)
public void AddEqual(string name, DateTime value)
public void AddEqual(string name, object value, string camlType) 
public void AddEqual(Guid fieldId, string value)
public void AddEqual(Guid fieldID, int value)
public void AddEqual(Guid fieldId, DateTime value)
public void AddEqual(Guid fieldId, object value, string camlType)

You can identify the list item field to be queried using either its name or its field GUID. The value to be searched for can be of any of the following .NET Framework types: string, int, DateTime or object. If you use the object type, you also need to provide a string argument to give the type name that will be passed to CAML.

The AddNotEqual method inserts a clause that tests whether a given list item field does not equal the value given as an argument. There are four overloaded methods for AddNotEqual. These are shown in the following code.
C#
public void AddNotEqual(string name, string value)
public void AddNotEqual(string name, int value)
public void AddNotEqual(string name, DateTime value)
public void AddNotEqual(string name, object value, string camlType) 

The list item field to be queried is identified by name. The value to be excluded by the execution of the query can be of any of the following .NET Framework types: string, int, DateTime or object. If you use the object type, you also need to provide a string argument to give the type name that will be passed to CAML.

The FilterByContentType method adds a clause to the query to select only list item records of a given content type. The name of the content type is the method's argument.

The AddFilter method allows you to add a custom CAML clause to the query. You must package the CAML string using an instance of the CAMLFilter helper class.



To give feedback.
Copyright (c) 2007 by Microsoft Corporation. All rights reserved.

Last edited Jun 16, 2009 at 7:18 PM by ckeyser, version 2

Comments

No comments yet.