Sunday, January 24, 2010

Client OM (Microsoft.SharePoint.Client) Samples for SharePoint 2010

SharePoint 2010 introduces a new client side object model for retrieving data from SharePoint. The client OM is included in Microsoft.SharePoint.Client.dll and Microsoft.SharePoint.Client.Runtime.dll. Library reference for client OM is at

Client OM is counterpart to the Server OM with notable differences
  • Client OM works on both on SharePoint server and client
  • Client OM does not fetch data implicitly
  • Client OM is supported for .NET as well as for ECMA (javascript etc)
The essence of the Client OM lies in ClientContext class ( Microsoft.SharePoint.Client.ClientContext ). This class allows you to get connected with the SharePoint server and then fetch data as required.

In this blog, I will covering few samples on how to use the Client OM.


First you will need to reference Microsoft.SharePoint.Client.dll and Microsoft.SharePoint.Client.Runtime.dll and then use Microsoft.SharePoint.Client namespace.

using Microsoft.SharePoint.Client;

To connect to the SharePoint server, you will need SharePoint URL and create a ClientContext object.

ClientContext context = new ClientContext("http://sharepoint");

At this moment the client context for SharePoint is defined but no connection has been made. Now lets initialize the Web object (equivalent to SPWeb in Server OM).

Web web = context.Web;

To connect/fetch data from the SharePoint, ExecuteQuery needs to be call on ClientContext object.

Console.WriteLine("Web '{0}' [Id:{1}]",web.Title, web.Id);

If you run the above code, it will throw PropertyOrFieldNotInitializedException exception with following message

The property or field has not been initialized. It has not been requested or the request has not been executed. It may need to be explicitly requested.

The code throws exception because client OM does NOT fetch data implicitly. So, we will modify the code to fetch the data the data explicitly. Since we are only interested in Id and the Title of the Web, the code will explicitly request those data. Retreive method in the Web class to tell the client OM which data needs to be fetched. The complete code will look like

ClientContext context = new ClientContext("http://sharepoint");
Web web = context.Web;

Console.WriteLine("Web '{0}' [Id:{1}]",web.Title, web.Id);

The above code will print the title and the id for the Web.

ClientObject class is the base class for all Client OM object. ClientObject exposes the following important methods that code will use again and again.

IsPropertyAvailable(string propertyName) - Returns a flag that indicates whether the specified property has been retrieved or set, or has not been retrieved or set.
Retreive() - Retreives all properties associated with the object
Retreive(params string[] propertyNames) - Retreives the specified properties associated with the object

All classes deriving from ClientObject class has a property names class ( for example, Web class has WebPropertyNames class ) which tells what properties can be fetched for the object.

Sample 1: Get all lists in web

The following sample will get all the lists in a web. For the list, the code will fetch the list id, list title and the type of the list.

public void GetAllList()
    ClientContext context = new ClientContext("http://sharepoint");
    ClientObjectPrototype allListsPrototype = context.Web.Lists.RetrieveItems();

    foreach (SPClient.List list in context.Web.Lists)
        Console.WriteLine("List : {0}, Id: {1}, BaseType : {2}", list.Title, list.Id, list.BaseType);


Sample 2: Get list details
In this sample, given a list the code gets the details for the list. The details include the Fields and Views of the list.

public void GetListDetails(string listName)
    ClientContext context = new ClientContext("http://sharepoint");
    List list = context.Web.Lists.GetByTitle(listName);            

    // get fields name and their types
    ClientObjectPrototype allFieldsPrototype = list.Fields.RetrieveItems();
    allFieldsPrototype.Retrieve( FieldPropertyNames.Id,

    // get view title
    ClientObjectPrototype allViewsPrototype = list.Views.RetrieveItems();


    foreach (Field field in list.Fields)
        Console.WriteLine("Field '{0}', Type : {1}", field.Title, field.FieldTypeKind);

    ViewCollection views = list.Views;
    foreach (View view in views)
        Console.WriteLine("View '{0}', Id : {1}", view.Title, view.Id);


Sample 3: Get list items
The following code gets the list items in the given list.

public void GetListItems(string listName)
    // build the CAML query to get ALL items
    CamlQuery query = new CamlQuery();
    query.ViewXml = "";

    ClientContext context = new ClientContext("http://sharepoint");
    List list = context.Web.Lists.GetByTitle(listName);
    ListItemCollection items = list.GetItems(query);

    foreach (ListItem item in items)
        // assumes that the list has a field with name 'Title'
        Console.WriteLine("Item : {0}, Id : {1}", item.FieldValues["Title"], item.Id);

Sample 4: Add item to a list
The following code adds a list item in the given list.

public void AddItemToList(string listName)
    ClientContext context = new ClientContext("http://sharepoint");

    List list = context.Web.Lists.GetByTitle(listName);
    ListItemCreationInformation lic = new ListItemCreationInformation();
    ListItem item = list.AddItem(lic);

    //add the item information
    item["Title"] = "Adding a new Item";

    // List has a field name Checkbox which is a checkbox type field
    item["Checkbox"] = true;  



    Console.WriteLine("Id : {0}", item.Id);


Client OM is very useful however it takes time to understand how to use the API and get the best out of it. Enjoy !!

Friday, January 22, 2010

Reading BDC model properties in .NET Assembly Connector


BDC in SharePoint 2010 support connectors for "Web Service", "Wcf Service", "Database", ".NET Assembly" and "Custom". ( BDC in MOSS 2007 has support for "Web Service" and "Database" only ).

.NET Assembly Connector basically allows to host a virtual LobSystem. The concept for .NET assembly connector is very similar to my suggestions of hosting .NET assembly in MOSS 2007 - BDC : Beyond Web-Service and Database.  Since .NET assembly is natively supported in SharePoint 2010, it has way more capabilities than my suggested approach. The following article ( explains how to create a .NET Assembly Connector in BDC.

This blog explains how you can use BDC model properties within your .NET assembly code.

IContextProperty Interface

To use the BDC model in the .NET assembly, lets first take a look at the IContextProperty interface [r1]. IContextProperty interface is defined in Microsoft.BusinessData.SystemSpecific namespace ( in Microsoft.BusinessData.dll )

namespace Microsoft.BusinessData.SystemSpecific
    public interface IContextProperty
        IExecutionContext ExecutionContext { get; set; }
        ILobSystemInstance LobSystemInstance { get; set; }
        IMethodInstance MethodInstance { get; set; }
Figure 1: IContextProperty interface

.NET assembly connector in BDC uses IContextProperty interface to communicate the context in which BDC is executing the method in the class. If your class implements IContextProperty interface, BDC will initialize the three properties of the interface. Here is an example how you can write your class to implement the interface.

using Microsoft.BusinessData.SystemSpecific;

namespace MyNamespace
    public class MyClass : IContextProperty
        private IExecutionContext context;
        private ILobSystemInstance lobSystemInstance;
        private IMethodInstance methodInstance;

        #region Implementing IContextProperty interface

        public IExecutionContext ExecutionContext 
            get { return this.context; } 
            set { this.context = value; }

        public ILobSystemInstance LobSystemInstance
            get { return this.lobSystemInstance; } 
            set { this.lobSystemInstance = value; }

        public IMethodInstance MethodInstance
            get { return this.methodInstance; } 
            set { this.methodInstance= value; }

Figure 2: IContextProperty implementation

At this time "MyClass" class is ready to get the context from BDC.

Defining properties in BDC Model

Depending on what kind of information you need in the .NET code, you can define your property at appropriate element in the BDC model. For example, if your class needs to connect to different server for different region, LobSystemInstance would be a good place to define your property. In the case method needs to know which Locale is preferred by the user, it can look into the properties of Method or MethodInstance.

In this example, the class connects to a different database server based on which region the code is getting executed.

private string GetDbConnectionString(string region)
    string dbConnectionStringFormat = "Data Source={0};Initial Catalog=myDataBase;Integrated Security=SSPI;";
    // default DB Server
    string regionDbServer = "northamericaDBServer"; 

    if (region == "emea")
        regionDbServer = "emeaDbServer";
    else if (region == "asia")
        regionDbServer = "asiaDbServer";

    return string.Format(dbConnectionStringFormat, region);
Figure 3: Customize connection string

The above code relies on the region information to format DB connection string. Unfortunately, when the code gets executed in SharePoint, the method has no idea where it is being executed and would default to using north america db server.

To solve this issue, you can define a property in the BDC model which tells the code which DB server to use. Lets say the property name is "Region" and is defined within the LobSystemInstance.

  <LobSystemInstance Name="NorthAmerica">
      <Property Name="Region" Type="System.String">northamerica</Property>
  <LobSystemInstance Name="Default">
      <Property Name="Region" Type="System.String">northamerica</Property>
  <LobSystemInstance Name="EMEA">
      <Property Name="Region" Type="System.String">emea</Property>
  <LobSystemInstance Name="Asia">
      <Property Name="Region" Type="System.String">asia</Property>
Figure 4: BDC model properties

In this example, different LobSystemInstances are used for each region, where the "Region" property is defined in LobSystemInstance. This is particularly useful when the user creates an external list. The user can choose the appropriate LobSystemInstance depending on its region.

Reading properties in the method

So now that the properties are defined in the model, its time to read the property in the code. The class "MyClass" exposes a method ReadAllItems for Finder stereotype. In this method, LobSystemInstance property returns the LobSystemInstance (BDC context).  LobSystemInstance.GetProperties() method returns all the properties defined for the LobSystemInstance.

public MyItems ReadAllItems()
   // get the LobSystemInstance properties via context from BDC
   INamedPropertyDictionary properties = this.LobSystemInstance.GetProperties();

   string region = null;

   // search for "Region" property in model
   if (properties.ContainsKey("Region"))
        region = properties["Region"] as string;

   //get the db connection string
   string dbConnectionString = GetDbConnectionString(region);

   //do normal db processing
   //return the items for method

Figure 5: Use the BDC model property

Once we have all the properties, the code checks if the "Region" property has been defined or not and reads the "Region" property accordingly. Once the Region property is read, it is used to create the DB connection string and the DB query is executed against that particular DB server.


BDC model is the right place to define custom properties. These properties should be used in .NET assembly connector code to customize solutions.


r1: IContextProperty interface:

Monday, January 18, 2010

Business Connectivity Services (BCS) - Profile Pages

Profile Page

A profile page in BCS (Business Connectivity Services) allows to display all the information for an external content (entity instance). For example, a profile page can display all the fields in a record for a specific customer. It can also display all the orders associated with the customer.

NOTE: A profile page is different from user profile. User profile is a SharePoint feature where as profile page is specific to BDC (Business Data Connectivity).

Profile page has a unique url, as each entity (External Content Type) has its own profile page. Profile page in SharePoint 2010 is not created automatically anymore (it was created automatically in MOSS 2007).

If the profile page is not enabled for the entity, clicking on the entity instance will load the view items page.

Figure 1: View item for External Content Type

Figure 2: View Item Page

To create a profile page for an entity, you will need to configure where the profile page will be hosted. To configure, click on the configure button in the BDC administration page/ribbon (figure 3).

Figure 3: Configure profile page button

This loads a wizard where you can enter the host location for the profile page. Profile page can only be hosted on SharePoint sites.

Figure 4: Profile page host

At this time, you can enable your entity to have a profile page. To do so, click on the External content type and click "Create/Upgrade Profile Page".

Figure 5: Create/Upgrade Profile Page

Figure 6: Profile page confirmation

Once the profile page has been created you will notice there is an default action associated with the external content type (figure 7).

Figure 7: Default action

Unfortunately, external list does not allow to go the profile page from the list (hopefully it gets fixed in RTM). To view the profile page load the default action URL in browser and set the ContactID.

Profile page is particularly useful to view entity associations. Figure 8 shows a Contact profile page, where sales order from the contact is displayed along with the contact information.

Figure 8: Contact and its sales order


Adding associations -
Associations Support in SPD -

Sunday, January 3, 2010

Secure Store Service - Installation (Farm mode)

This blog shows how Secure Store Service can be installed in farm mode. Please refer to blog for information on how to install Secure Store Service in standalone mode.

Figure 1, figure 7, figure 9 and figure 12 mentioned in this blog are the figures from "Secure Store Service -  Installation" blog.

Server Farm Installation
To install SharePoint in server farm mode, first prerequisites installer needs to be run. After the prerequisite installer has installed all the prerequisites components, start the SharePoint installation (figure 1). Enter the product key in the next screen and then agree to license terms. On the next screen, click the “Server Farm” button (figure 7). This will start SharePoint installation in server farm mode. Setup will present a screen to do a “Complete” install or standalone install. Select “Complete - Install all components” checkbox (figure 21).

Figure 21 : Selection Server Type

Click “Install Now” button. Setup will show installation progress and after the installation is complete, setup will give an option to run the configuration wizard (figure 9). Choose to run the configuration wizard.

When the configuration wizard continues, it will warn about services being stopped (figure 12).

In the server farm mode, the wizard gives an option to create a new server farm or join an existing server farm (figure 22).

Figure 22: Connect to existing or new farm

Choose to create a new server farm by selecting “Create a new server farm” checkbox. Click 'Next' button to continue. Installing SharePoint in farm mode requires a database server where SharePoint stores its configuration and content. In standalone mode, SharePoint installs the database automatically.

Figure 23: Database Settings

In the database settings screen (figure 23), enter the database server, name and the credentials for the domain user which has database creation rights. Click 'Next'. This will bring up the farm passphrase screen (figure 24). To create or join a farm, SharePoint administrator needs a passphrase. Choose a passphrase and store the passphrase in a safe location, as SharePoint does not store the passphrase.

Figure 24: SharePoint Passphrase

Passphrase must meet complexity requirement. If the complexity requirement is not met, wizard will display an error (figure 25) and will let to enter a new passphrase.

Figure 25: Passphrase Complexity Requirement

Once the passphrase has been entered, installation configuration will allow choosing a port on which central administration will be hosted as well as will allow configuring security settings (figure 26).

Figure 26: Central Admin Port and Security Settings

Click 'Next' to continue. Configuration wizard will display the summary of the settings and let you to change any setting if required.

Figure 27: Configuration Summary

At this time, clicking ‘Next’ will start installation in farm mode. After SharePoint has been installed, the wizard will again display the summary. Click 'Finish' in the installation summary.

When SharePoint is installed in farm mode, the wizard will not automatically configure SharePoint, instead it will launch the browser to configure SharePoint (figure 28).

Figure 28: Initial Farm Configuration Wizard

Select “Walk me through the settings using this wizard.” checkbox and click ‘Next’ (figure 28). In the next screen, SharePoint will need an account on which the shared services will run (figure 29). Choose an account which is different than the farm admin account. In the same screen (figure 30), SharePoint will give an option to select the services that will run on the server. Make sure “Secure Store Service” is selected (figure 31).

Figure 29: Service Account

Figure 30: Services

After making sure Secure Store Service is checked, click ‘Next’. The configuration wizard will install and start the services that were selected.

Configuration wizard will also ask to create a site collection. At this time Secure Store Service is already installed on the server. You may choose to create a site collection.

Figure 31: Secure Store Service

In the above figure, Secure Store Service has been installed and started by the configuration wizard.