Getting a Service Locator Instance

The SharePoint Service Locator makes a single IServiceLocator implementation available to all callers within the farm or the site collection, depending on your execution context. Regardless of whether you want to register a service or consume a service, your first step is to get a reference to a service locator instance. The SharePointServiceLocator class provides various static methods that you can use to retrieve a service locator instance. All of these methods return an implementation of IServiceLocator—the only difference is the scope of the type mappings that are loaded into the service locator instance.

If you are running in a context where an SPContext object is available, then the GetCurrent() static method will automatically load the type mappings defined at the site collection scope and the farm scope, and return a service locator that includes these mappings. If a type mapping for a particular interface is defined at both the site collection scope and the farm scope, then the site collection mapping will take precedence. If an SPContext object is not available—in a timer job, for example—then the GetCurrent() method will return a service locator that loads farm-only type mappings. A second overload, GetCurrent(SPSite), will load type mappings from the specified site collection and merge them with the farm-scoped type mappings. This method overload is useful when an SPContext object is not available but you want to use type mappings defined in a particular site collection.

A third method, GetCurrentFarmLocator(),will return a service locator instance that contains only farm-scoped type mappings. You can use this method if you do not want to use any site collection-scoped type mappings. An instance of the farm-level service locator is shared by all application components throughout the farm, whereas an instance of a site collection-level service locator is shared by all components within a site collection.

The following code shows you how you can get a reference to the current service locator instance.

IServiceLocator serviceLocator = SharePointServiceLocator.GetCurrent();

If an SPContext object is unavailable, but you want to load the type mappings defined for a particular site collection, you can provide an SPSite argument to the GetCurrent method:

IServiceLocator locator = 
   SharePointServiceLocator.GetCurrent(properties.Web.Site);

Note

The SharePoint Service Locator depends upon the Application Setting Manager component to load type mappings from configuration. Type mappings are stored in configuration settings at the site collection level and at the farm level. In order to retrieve these settings, the SPFarm.Local property must return a valid SPFarm instance. This is only possible when your code runs on a server that can access the SharePoint object model, such as a Web Front End (WFE) server. If a SharePoint context is available (SPContext), then the service locator will also load the site collection-scoped configuration data.

The service locator instances for the site collection level and the farm level are cached. The site collection-level service locator instances are periodically refreshed to pick up any new type mappings. You can configure this interval by using the SetSiteCacheInterval method in the IServiceLocatorConfig interface. By default, the site collection-level service locator instances are refreshed every 60 seconds. At this point, the configuration settings are checked for changes by comparing timestamps with the cached values. If the configuration settings have changed, the service locator instance is reloaded with the new settings.

In unit testing scenarios you should create a new service locator instance rather than using the current instance, as the current instance requires a SharePoint context in order to get a reference to the local SPFarm object. For more information, see Creating a New Service Locator Instance.