Registering a Service

Applies to: SharePoint Foundation 2010

SharePoint 2010 provides a platform for unified installation and administration of services in a server farm. Integrating a service with SharePoint 2010 ensures that the service can be managed by using an interface that is consistent with other services in the farm. SharePoint Foundation 2010 provides a high-performance runtime API that can be used to discover services and route service requests based on the server farm topology. In addition, SharePoint Foundation 2010 provides a complete framework for hosting Web services in Internet Information Services (IIS), including deploying the Web service on multiple computers in the server farm, load-balancing requests from front-end Web servers, and providing a property store for service settings.

About Configuration Database Objects

Services must be registered in the SharePoint configuration database so that they can be discovered and managed. All objects stored in the SharePoint configuration database are Microsoft .NET Framework objects that derive their classes from Microsoft.SharePoint.Administration.SPPersistedObject. Each SPPersistedObject object has the following requirements:

• A unique System.Runtime.InteropServices.GuidAttribute value, which is used to identify your type in the configuration database.

• A public default constructor, intended for internal use only by the configuration database object serializer.

The following example shows the public default constructor.

using System.Runtime.InteropServices;

[Guid("213A8448-2B39-4B37-A39C-1B444600000")]
public class MyObject : SPPersistedObject
{
        /// <summary>
        /// For internal use only.
        /// </summary>
        public MyObject()
        {
        }
}

Imports System.Runtime.InteropServices

<Guid("213A8448-2B39-4B37-A39C-1B444600000")>
Public Class MyObject
    Inherits SPPersistedObject
    ''' <summary>
    ''' For internal use only.
    ''' </summary>
    Public Sub New()
    End Sub
End Class

Note

For brevity, the GUID and default public constructor are not shown in the remaining example code in this topic.

Registering a Service with SharePoint Foundation

The following example shows how to register a service that can be started and stopped on multiple servers in a SharePoint 2010 server farm. You do not need to implement the service on the SharePoint platform. For example, the SharePoint service classes can be used to make an external line-of-business (LOB) service visible in the Central Administration site.

Step 1: Create the Service Class

Derive a class from SPService.This class is used to register the service in the SharePoint 2010 server farm and can optionally contain settings that apply to every instance of the service in the farm.

public sealed class MyService : SPService
{
    public MyService(
        SPFarm farm)
        : base(String.Empty, farm)
    {
    }
}

Public NotInheritable Class MyService
    Inherits SPService
    Public Sub New(ByVal farm As SPFarm)
        MyBase.New(String.Empty, farm)
    End Sub
End Class

Step 2: Create the Service Instance Class

Derive a class from SPServiceInstance. This class is used to register the computers where the service is installed in the server farm. It also provides the management hooks that a farm administrator must have to start and stop the service from the Central Administration site.

Override the Provision and Unprovision methods to execute code to start and stop the service on the local computer. The Service Application Framework calls the methods on the appropriate server.

public sealed class MyServiceInstance : SPServiceInstance
{
    public MyServiceInstance(
        SPServer server,
        SPService service)
        : base(String.Empty, server, service)
    {
    }

    public override Provision()
    {
        // Start the service on the local computer.
    }

    public override Unprovision()
    {
        // Stop the service on the local computer.
    }
}

Public NotInheritable Class MyServiceInstance
    Inherits SPServiceInstance
    Public Sub New(ByVal server As SPServer, ByVal service As SPService)
        MyBase.New(String.Empty, server, service)
    End Sub

    Public Overrides Sub Provision()
        ' Start the service on the local computer.
    End Sub

    Public Overrides Sub Unprovision()
        ' Stop the service on the local computer.
    End Sub
End Class

In the example, the name of the service instance is String.Empty, which is appropriate for the default service instance. Named (nondefault) service instances are appropriate when the service supports multiple physical instances on a single computer. Each instance, except the default instance, has a name and can be independently started and stopped. In this case, an additional constructor is required, as shown in the following example.

internal MyServiceInstance(
    string name,
    SPServer server,
    SPService service)
    : base(name, server, service)
{
}

Friend Sub New(ByVal name As String, ByVal server As SPServer, ByVal service As SPService)
    MyBase.New(name, server, service)
End Sub

Step 3: Install the Service

Create a SharePoint Foundation Feature that will install the service and service instance objects in the configuration database during the post-setup configuration phase. For more information, see Packaging and Deployment in SharePoint Foundation.

See Also

Concepts

Provisioning Service Applications

Other Resources

Packaging and Deployment in SharePoint Foundation