Building Customer Service Applications

Building Customer Service Applications

The purpose of this sample code is to provide the reader with an insight into how SharePoint 2010 Service Applications can be used to create truly distributed scalable architecture. The sample code acts as a framework for developers who want to start creating SharePoint Service Applications without worrying about the underlying plumbing required to create such applications.

The sample code demonstrates how service application can be used to create a service orientated application (SOA) within the realm of SharePoint 2010’s infrastructure. The sample provides a framework which can be used to create such applications without writing an extensive amount of boiler plate code.

The example code provided, allows system administrators to capture auditing events from a particular site collection. The custom timer job is responsible for writing the audit events from the site collections to the provisioned database.

A consumer (Web Part) is used to retrieve information from the provisioned database via the Service Application Proxies.

Step1: Create Visual Studio Solution

In Visual Studio 2010, create a new project using the “Empty SharePoint Project” and call it “ServiceApplication”.

You will be asked for the SharePoint site address for debugging. Since we are deploying this to the central administration site, enter the URL of Central Administration site and check the “Deploy as a farm solution” radio button. Click “Finish” to continue.

Step 2: Create Basic WCF application

We will change the assembly name and default namespace to “ServiceApplication”. Right click the “ServiceApplication” and select “Properties”. Under the “Application” tab, change both the “Assembly name” and “Default namespace” to “ServiceApplication”. Save the settings.

Add a reference to the following assembly:

• System.ServiceModel
• Microsoft.SharePoint
• Microsoft.Office.Server
• Microsoft.SharePoint.ApplicationPages.Administration(C:Program FilesCommon FilesMicrosoft SharedWeb Server Extensions14CONFIGADMINBINMicrosoft.SharePoint.ApplicationPages.Administration.dll)
• Microsoft.SharePoint.Security
• System.Data.DataSetExtentions

Create WCF Contract and Service Host Declaration

We start this by adding a mapped folder to the WebServices folder in {SharePointRoot}. To do this, right click the ServiceApplication > Add > SharePoint Mapped Folder…, then select the “WebServices” folder and click “OK”. A new WebService folder “ServiceApplication” will be added to the project.

Let’s add a contract file that has a single signature “Service”. Right click the Project and add a new item. Select the “WCF Service” project template and give it a name called Service.

Open IService.cs and declare a signature “Service”. Replace all the code with “IService_cs” file code.

Next we will add a service host declaration. Add a text file type in the WebServicesServiceApplication folder and rename it to “ServiceApplication_svc”. Click the link to get the code and paste it to the newly added file.

Note that you need to enter your own public key token.

We will add a configuration file to our WCF service that contains the information such as the behaviour. Right click WebServicesServiceApplication folder again and this time we will add an application configuration file called “web_config”.

Delete Service.cs as we don’t need it. Also delete the app.config added to the base project.

We have successfully completed a simple WCF service that is ready to deploy to a SharePoint farm.

Step 3: Create service application framework

Next we will create a number of classes for the service application. Each of these classes represents a key component for a service application, such as:

• Service
• Service Proxy
• Service Application
• Service Application Proxy
• Service Instance
• Service Factory
• Service DataBase

Service: Next create a new class called “WebService_cs“.

Service Proxy:Next create a new class called “WebServiceProxy_cs”. Note that it has a SupportedServiceApplication decorative and it is referencing the WebServiceApplicationProxy by its Guid.

Service Application : Next create a new class called “WebServiceApplication_cs“. This class will implements IService and contains the actual implementation of our functional methods.

Service Application Proxy: Next create a new class called “WebServiceApplicationProxy_cs“.

Service Instance: Create a new class in the root folder of the project and call it “ServiceInstance_cs”.

Service Factory: Next create a “ServiceFactory_cs” class

Service Database: Next we create a custom database class “WebServiceDatabase_cs” which inherits SPDataBase class.

Once database class has been created next is to create some basic entity classes which interact with the database to update and retrieve data. First we will create a folder to the “Entities” folder and this is the folder where the database entity classes will deploy. To do this, right click the ServiceApplication > Add > New Folder…, then rename that folder to “Entities” folder. Now add a class “ListEntries_cs“.

Another Entity Class “AuditEntries_cs”

Few helper classes are required to implement the logic. To add new classes creat a new folder at root project with name “Helpers”. Add two classes “Common_cs” and “Database_cs”.

Now in order to create a custom database we require custom script file which contains SQL command to create and configure database. Create a mapped folder “SQL” it must be mapped to ..14TEMPLATESQL. Create a new folder called “Service Application”. Now create a sql script with name “ServiceApplication_sql”.

Next is to create a timer job in order to get the initial data. Create a new folder called “Timer” and add a new class called “GatherEvents_cs”

Next we need to define the client configuration file. Map a another folder “WebClients” which directly resides under 14 hive. Create a new project folder and add a new application configuration file and renamed it to “client_config”.

And we have completed our custom service application implementation. But we are not there yet. We will need to create administration pages for service creation and management. And we also need to register the service application to the farm so that we can create an instance of it. More to come next:

We will need to create two administration pages for our service application. One will be used for service application instance creation, and the other one for managing existing application instance. As a reference we will use the pages for Excel Service, which can be located in the ADMIN folder (C:Program FilesCommon FilesMicrosoft SharedWeb Server Extensions14TEMPLATEADMIN).

First we will create a mapped folder to the ADMIN folder and this is the folder where the administration pages will deploy. To do this, right click the ServiceApplication > Add > SharePoint Mapped Folder…, then expand the “TEMPLATE” node and select the “ADMIN” folder. A new ADMIN folder “ServiceApplication” will be added to the project.

We will first create the service creation page. Right click the newly created “ServiceApplication” folder under “ADMIN” and add a new item. Select the “Application Page” template and give the page a name “Create_aspx”.

I am using Visual Studio 2010 Beta 2 and notice a funny thing. VS2010 will create the Create.aspx in “Layouts/ServiceAplication”. If you have this problem, just drag the aspx file to ADMINServiceApplication, as this is the location where we referencing in out Service Application implementation (Service.cs).

Replace the code behind file with “Create_aspx_aspx_cs”

Now Create new aspx page with name “CustomizeAuditSettings_aspx” and place following code in it:

Now next we have to create a new aspx page “AuditSettings_aspx”.

Replace the code behind file with “AuditSettings_aspx_cs”

The project structure will looks like :

Step 4: Creating consumer webpart for the application

Create a new sharepoint project named “ServiceApplicationConsumer”. Add a new visual webpart to the project.

The ascx file should looks like “VisualWebPart1UserControl_ascx”

Code behind for the webpart should contains code as given in “VisualWebPart1UserControl_ascx_cs” file.

This finishes the implementation part of the service application. This is very basic service application which just retrives sharepoint webapplication list and save them to the database.

Step 5: Deployment

Install the solution/s on a SharePoint server:

• ServiceApplication.wsp  – Farm Feature (Various Service Application Components)
• ServiceApplicationConsumer.wsp – Site Feature (Web Part Consumer)

Navigate to Central Admin (CA) –> System Settings –> Manage Farm Solutions.

Start the newly create instance by navigating to CA –> System Settings –> Manage Services on Server

Navigate to CA –> Manage Service Applications and create a new instance of the sample Service Application ‘Service Application’

Enter the relevant information required to create the Service Application

This will create a new instance of the Service Application

Clicking on the newly create Service Application will open the following, the page enables system administrators to configure which events from which site collection are written into the newly provisioned database

Clicking on the URL (highlighted above) will open the following dialog which can be used to configure the audit settings for that particular site collection

Ensure that the Service Application Gather timer instance is running, after generating events within the site collection. Run the timer instance, this will persist the event data within the provisioned database

Navigate to a Site collection that you have configured to capture the audit logs from. Edit the page and add the ‘Service Application Consumer’ web part to the page. Save the page.

The audit logs are displayed in the following grid format

Service Instance: