Quick & Dirty Guide to OSM

Introduction

Object-SharePoint mapper is similar to any other O/RM tool. If you used before things like Hibernate, nHibernate, LinqToSql or Entity Framework, you don't need any explanations and can skip to next paragraph. Basically it transparently and automatically moves data from SharePoint list's items to regular .NET classes and back. It frees developer from manual use of "weakly-typed" SharePoint API or repeated creation of wrapper classes just to access data. Additionally OSM have some querying capabilities, thus freeing developers from manually writing CAML queries.

Mapping

Let's assume we have SharePoint list of people with their first and last name (as text column), age (as number column) and genre (as choice column). I hope you create columns in SharePoint using features, because we will need columns IDs, if you don't, just use SharePoint Manager to get them.

Now in your Visual Studio project you have to just reference OSM assembly and write only this little piece of code to map regular .NET class to SharePoint list item:

using Whut.ObjectSharePointMapper;

public enum Genre
{
    Male,
    Female
}

[List("/Lists/People")]
public class Person
{
    [Id]
    public int Id { get; private set; }

    [Field("7a992e4d-0f7d-478a-b542-f204955a1c7d")]
    public string FirstName { get; set; }

    [Field("a36bdcee-a4a1-49fa-8075-9d449366f199")]
    public string LastName { get; set; }

    [Field("7de58d6d-e0ed-4a09-8507-9fe2311b9eb2")]
    public double Age {get; set; }

    [Field("8eacf25f-1591-420d-92b0-ec9049b93645")]
    public Genre Genre {get; set; }
}


Possible attributes:
  • ListAttribute - this required attribute on class definition sets site relative URL to SharePoint list. For example if you created list named Persons using SharePoint UI in site collection http://localhost/mySiteCollection/myWeb or http://localhost/, it will be /Lists/Persons.
  • IdAttribute - this required attribute on class property of type int is used to store list item IDs.
  • FieldAttribute - you can use this attribute to map SharePoint list columns to properties of your class. Argument is ID (GUID) of column in used list, written as string. When you map text column, type of property must be string, number column - double, choice and content type column - custom enum, date and time column - DateTime, lookup column - Lookup (from Whut.ObjectSharePointMapper), lookup columnwith multiple values allowed - MultiLookup (also from OSM), person or group column - User (also from OSM).
  • DescriptionAttribute (from System.ComponentModel) - you can put this attribute on enum fields if mapped choice column value (displayed in SharePoint UI) is different than value of this enum. Also, consider using in your enums one "unset/unknown/none" value with null Description, to map empty value in choice column (without it OSM will throw exception). Example:
public enum Genre
{
    [Description(null)]
    Unset,
    Male,
    [Description("Woman")]
    Female
}

Adding new list items

// Put it as static field somewhere, don't create it each time needed.
// Constructor argument is assembly that contains mapped classes
ISessionFactory factory = new Whut.ObjectSharePointMapper.Internals.SessionFactory(System.Reflection.Assembly.GetExecutingAssembly());

SPWeb web = // get reference to SPWeb in any way
ISession session = factory.CreateSession(web);
Person person = new Person();
person.FirstName = "Ralf";
person.LastName = "Donowan";
person.Age = 24;
person.Genre = Genre.Male;
session.Insert(person);

Updating list items

SPWeb web = // get reference to SPWeb in any way
ISession session = factory.CreateSession(web);
Person person = session.Find<Person>(1);
person.Age++;
session.Update(person);

Querying

SPWeb web = // get reference to SPWeb in any way
ISession session = factory.CreateSession(web);
IQuery<Person> adultJohnsQuery = session.CreateQuery<Person>();
adultJohnsQuery.AddCondition(p => p.Age, ConditionType.GreaterOrEqual, 21);
adultJohnsQuery.AddCondition(p => p.FirstName, ConditionType.Equal, "John");
IEnumerable<Person> adultJohns = adultJohnsQuery.GetResults();

Additional info

If you want to know all possibilities and features of OSM, check in sources: ISession, ISharePointSession, ISessionFactory, IQuery, Lookup, MultiLookup, User and IdAttribute, FieldAttribute and ListAttribute.

ISession implements simple caching.

This project is in use in one moderately big SharePoint application for more than half a year, so it's quite tested, but I of course can't give you any guaranties.

Inspiration and a lot of implementation ideas borrowed from Davy Brion and his series Build Your Own DAL.

Last edited Apr 7, 2010 at 12:54 PM by whut, version 15

Comments

No comments yet.