Service Object Model
Applies to: SharePoint Foundation 2010
Microsoft SharePoint Foundation 2010 offers a highly structured, server-side object model that you can use to access objects that represent the various aspects of a SharePoint 2010 site. From higher-level objects, you can drill down through the object hierarchy to obtain the objects that contain the members you need to use in your code.
The following diagram shows the relationships among the major classes when you implement the Service Application Framework of SharePoint 2010. Solid arrows point from a parent class to the kind of child class that is held in a parent object's collection property. The dotted arrow indicates that the SPServiceInstance class represents a running process (an instance) of the farm-wide service represented by the SPService class.
Figure 1. Class relationships in the Service Application Framework
.gif "Class relations in Service Application Framework")
SPFarm Object
The SPFarm object represents a server farm. SPFarm is the top-level of the configuration store hierarchy. A server farm is a load-balanced cluster of physical servers. Load-balancing software (or load-balancing hardware) directs an incoming network connection from a client computer to the computer in the farm that is least busy at the time. Thus, the workload of servicing client connections is distributed over many servers, processors, hard disks, and other peripherals.
A physical server is represented by the SPServer object. In addition to the members it inherits from SPFarm, SPServer has an Address property that holds the IP address of the server and a Role property that identifies the server's role in the farm. The ServiceInstances property holds references to all the instances of Windows services and Web services that are running on the server.
SPServer Object
An SPServer object is created when a server is joined to a SharePoint server farm; SPServer.Local is the configuration object. You can see a list of the servers in the farm in Central Administration. SPServer inherits from the SPPersistedObject object. Objects that instantiate SPPersistedObject persist in the SharePoint 2010 configuration database.
A physical server in a SharePoint 2010 farm is represented by the SPServer object. It has an Address property that holds the IP address of the server and a Role property that identifies the server's role in the farm. The ServiceInstances property holds references to all the instances of Windows services and Web services that are running on the server.
Service Objects
Service objects, also known as back-end system objects, provide the shared service to the client front-end objects. These objects include the following:
SPService
The SPService class represents a service that is available or installed in a server farm.
Every SPService object has an Instances property that holds all the instances of the service that are running on various servers in the farm. Only one instance of each service runs on any one server, but some services have multiple instances, each running on a different server. Each instance is represented by an object of a class derived from SPServiceInstance.
SPServiceInstance
The SPServiceInstance class represents an instance of a service on a server in the farm. Service instances provide scalability and fault tolerance. A service instance is independent from but identical in functionality to all other server instances of the same type. An SPServiceInstance object is created when a service is installed on a server in the farm. To be usable, a service instance requires a running service application. Each computer running the service has its own service instance, which can be started and stopped. If one service instance of a given service is running, the service is fully functional.The service instance provides the host process for the service application. A developer can start or stop service instances programmatically, or a farm administrator can start or stop service instances through Central Administration in the Manage Services on Server section in System Settings.
Use Provision() to start (provision) the service instance. In Windows PowerShell, use get-SPServiceInstance to determine the collection of services that are installed on the server.
SPServiceApplication
A service instance hosts a service application. Without a service instance, the service application is not usable. The service application contains the application-specific data and settings and provides the service interface that contains the administrator settings. A service application can control user data.
Each service application is isolated from all other service applications. For example, the finance search service application is isolated from the human resources search service application, even though both are hosted in the same server farm.
Using SPServiceApplication, it is usually a farm administrator who creates a service application. The farm administrator can create an SPServiceApplication object by using any of the following:
Farm Configuration Wizard
Evaluation mode installation (stand-alone installation)
Central Administration in the New Service Application page
Windows PowerShell
An SPServiceApplicationCollection is the collection of service applications for a service, and is used in Central Administration in the Manage Service Applications.
SPIisWebServiceApplication
The SPIisWebServiceApplication class implements the ISharedServiceApplication interface and enables a service application to be published (advertised) via the topology service.
Client (Front-End) Objects
A client application communicates with the back-end service. Clients are applications that initiate communication. Services are applications that wait for clients to communicate with them and respond to that communication. The client service objects include the following:
SPServiceProxy
A service proxy represents a service client that is installed in a server farm.
An SPServiceProxy object is the parent of the SPServiceApplicationProxy object. It is the equivalent of an SPService object on the server side, which is the parent of an SPServiceApplication. These parent objects can also be considered as class factories for the child objects.
SPServiceApplicationProxy
The SPServiceApplicationProxy object represents a connection to a service application, and provides the public (front-end) interface to a service application. SPServiceApplicationProxy supports connections to remote farms, and enables client code to consume remote service applications. Service applications cannot be installed locally and therefore cannot be called directly from the client.
An SPServiceApplicationProxy is automatically created with a service application. At a minimum, service proxies forward calls to the remote service application. The SPServiceApplicationProxy can also be a location to implement additional logic about the connection to the service application.
Farm administrators can explicitly create an SPServiceApplicationProxy in the Service Federation section in Central Administration.