ServiceKey class

Package:

@microsoft/sp-core-library

The ServiceKey is a lookup key that is used when calling ServiceScope.consume() to fetch a dependency.

Remarks

Every service key also provides a default implementation of the dependency, which will be automatically created in the root scope if the dependency is not found. Providing a default implementation ensures that new dependencies can be safely introduced without inadvertently breaking components that are loaded by an older host that does not provide the new dependency.

Constructors

(constructor)(id, name, defaultCreator)

Constructs a new instance of the ServiceKey class

Properties

defaultCreator	A callback function that constructs the default instance of this service.
id	A unique identifier for this service key.
name	The name of the service.

Methods

create(name, serviceClass)	Constructs a new ServiceKey whose default implementation will be a new instance of a TypeScript class that accepts the standard constructor parameter.
createCustom(name, defaultCreator)	Constructs a new ServiceKey whose default implementation will be obtained by invoking the specified callback.

Constructor Details

(constructor)(id, name, defaultCreator)

Constructs a new instance of the ServiceKey class

protected constructor(id: string, name: string, defaultCreator: ServiceCreator<T>);

Parameters

id

string

name

string

defaultCreator

ServiceCreator<T>

Property Details

defaultCreator

A callback function that constructs the default instance of this service.

readonly defaultCreator: ServiceCreator<T>;

Property Value

ServiceCreator<T>

id

A unique identifier for this service key.

readonly id: string;

Property Value

string

Remarks

This identifier is an automatically generated string that will be unique for the lifetime of the page. Callers should not make assumptions about the formatting of this string. It is currently based on a global counter, but this may change in the future.

The ServiceScope uses this identifier internally as a dictionary key for finding services. The ServiceKey is meant to be unique, even if multiple instances of the same library are loaded on the same page, even if the same name was passed to ServiceKey.create(). This is because each call to ServiceKey.create() could potentially provide a different defaultCreator implementation, whereas one of the design goals of ServiceScope is that the order in which libraries are loaded should never affect the resulting tree of scopes.

name

The name of the service.

readonly name: string;

Property Value

string

Remarks

This name is used for logging and diagnostic purposes only. To make it unique, the recommended convention is the package name, followed by a period, followed by the class or interface name.

The system does not assume that this string is unique. Instead, the ServiceKey.id is used wherever a lookup key is needed.

Method Details

create(name, serviceClass)

Constructs a new ServiceKey whose default implementation will be a new instance of a TypeScript class that accepts the standard constructor parameter.

static create<TKey>(name: string, serviceClass: {
        new (serviceScope: ServiceScope): TKey;
    }): ServiceKey<TKey>;

Parameters

name

string

A name such as "my-package.IMyService" which should be unique across packages.

serviceClass

{ new (serviceScope: ServiceScope): TKey; }

the TypeScript class that implements the service.

Returns

ServiceKey<TKey>

the newly created ServiceKey

Remarks

If you want to specify custom constructor parameters, use ServiceKey.createCustom() instead.

createCustom(name, defaultCreator)

Constructs a new ServiceKey whose default implementation will be obtained by invoking the specified callback.

static createCustom<TKey>(name: string, defaultCreator: ServiceCreator<TKey>): ServiceKey<TKey>;

Parameters

name

string

A name such as "my-package.IMyService" which should be unique across packages.

defaultCreator

ServiceCreator<TKey>

a callback that returns an object that implements the T interface

Returns

ServiceKey<TKey>

the newly created service key