LINQ to SharePoint

Today, a new alpha of LINQ to SharePoint will be released to web: please welcome build 0.2.2. It's considered to be an interim release in between the 0.2 and 0.3 milestone. Remember from earlier posts that the goal in the 0.3 milestone is to provide update support through the entity model. The road ahead to reach that goal is still fairly long, but huge steps have been taken since the 0.2 release to support this. Although most of the work in the 0.2.2 interim release is focusing on stability and enablers for future release highlights, there are quite a bit features that will certainly interest you:

• Refactoring of the core model
  • SharePointDataSource<T> is now obsolete, SharePointDataContext and SharePointDataList<T> are the public classes that replace the SharePointDataSource<T>.
    • SharePointDataContext is the heart of the framework, responsible to keep track of lists, entity updates, connecting to the underlying providers, etc.
    • SharePointDataList<T> can be compared to a Table<T> in LINQ to SQL, but it refers to a SharePoint list instead, where T stands for the entity class.
  • The entity model has been changed, SharePointListEntity no longer exists.
    • Entities are regular classes but decorated with a ListAttribute and FieldAttributes on the properties.
    • The deprecation of the SharePointListEntity base class means we don't have a Dictionary<string, object> based storage of fields anymore. Field values are just kept in properties and their backing private class members.
    • To support updates, entities will typically implement INotifyPropertyChang[ing|ed].
    • The entity generator, SPML and SpMetal (see further) take care of generating the "ideal" entity type for a given SharePoint list.
  • Provider-based model to carry out SharePoint communication such as querying and updating. We'll provide a web services and object model implementation out of the box. Right, no other SharePoint communication mechanisms exist today (AFAIK), but this model allows us to separate concerns inside the core engine.
  • Close correspondence to the LINQ to SQL model: if you learn LINQ to SQL, it shouldn't be too difficult to get up to speed with LINQ to SharePoint because of similar principles and constructs (e.g. data contexts, deferred loading, entity refs and sets, ...)
• Improved query parser
  • The query parser (QueryParser) was split from the execution part (CamlQuery).
  • Lots of bugs were fixed, thanks to a more complete code coverage by unit tests.
  • Remodeled support for URL fields.
  • Parser can now report parse errors instead of throwing exceptions, depending on the run mode.
• Tool support enhancements
  • The enhanced debugger visualizer runs the parser in error checking mode and indicates errors in a written query.
  • SpMetal is now a pure front-end to an entity generator that also hosted in Visual Studio 2008 as a "single file generator".
    • Entities are mapped using SPML, the "SharePoint Mapping Language". Today it's still minimalistic, but the mapping (XML-based) language will get more complete in subsequent releases.
  • There's an MSI setup for the library together with the tool support. This is required to wire up all the necessary registry settings for VS IDE integration.

Tool support

Let's take a closer look at the tool support side of the 0.2.2 story. First of all, we have a setup available to install the LINQ to SharePoint binaries. Important: you should install the Windows SharePoint Services SDK prior to installing LINQ to SharePoint. The setup can take a while since it needs to reconfigure Visual Studio 2008 Orcas Beta 1 for tools integration:

Once you've done the setup, a new "item template" should appear in Visual Studio. Create a new application project and go to Add, New Item:

You'll see LINQ to SharePoint in this dialog right now:

This allows you to create a SPML mapping file with support of a wizard. Give it a useful name, such as Northwind.spml (on my demo machine I've copied the Products, Categories and Suppliers tables from SQL Server's Northwind sample database to SharePoint lists) and click Add. Now the wizard appears:

Click Next to continue:

Now specify the URL to the server and the method to log on. Click Test connection to validate the connection info, which will make the Next button available if everything's okay. So, click Next:

This dialog is where the real work happens: check the lists of your choice at the left-hand side. If you select a list at the left, the right-hand side will show all of the fields. In the current release, the right portion doesn't affect entity creation yet. In a subsequent release you'll have more control over the entity creation process than just selecting lists. Click Next:

And click finish to create the SPML file:

This file is turned into a C# of VB file automatically, as you can see in Solution Explorer. Feel free to browse through the generated code file to see the entity declaration:

This is it for what the export of entities is concerned. Now it's time to write some queries. Start by creating an object of type NorthwindSharePointDataContext, which is the "root" of the LINQ to SharePoint library. From this custom data context (that inherits from SharePointDataContext), you can start to write queries as shown below. Notice the IntelliSense that's available during the whole query writing process (click to enlarge):

Finally we can execute the code:

Or you could write a more complex query:

Tip: Convince yourself this is consistent with the results of the Northwind database's "Ten Most Expensive Products" sproc. This would be a great LINQ to SQL exercise as well.

On to the debugger visualizer. Set a breakpoint on the first Console.WriteLine statement and run under the debugger:

Now click the magnifier glass that appears on the res variable. This will bring up the visualizer:

In here you can see your query as well as the corresponding CAML. This can be used to spot bugs in the query, i.e. constructs not supported by CAML. This is shown in the screenshot below:

Hover of the red text to get more information about the problem. If you continue the execution of the program, a runtime exception will be raised when the query has to be executed, in our case at iteration time:

The error message corresponds to the first error you saw in the debugger visualizer (in this case there was only one).

Trivia - what has happened to 0.2.1?

Due to various modifications to the entity model, tools were getting out of sync with the query parser and execution engine back-end. Because of this we decided not to publish the 0.2.1 release. In 0.2.2 we're back in sync and the desired quality level of the various components is getting close to the ultimate goal.

 

What's coming after 0.2.2?

• Another interim release, likely 0.2.3 and planned for mid August, will cover:
  • List attachments
  • Additions to SPML and SpMetal improvements (generate SPML, consume SPML) + improvements for the entity wizard
  • Grouping support (under investigation)
  • Support for User fields (under investigation)
• The 0.3 alpha release:
  • Almost-complete entity model
  • Update support
  • Support for Views (under investigation)

Depending on the Orcas beta, RC, RTM schedule, we might decide to postpone releases in order to get in sync with the latest Orcas build. Other features on the wish list are enhanced tool support, compiled queries, etc but time will tell how things evolve.