Last Update: 9/26/2016

Core Client SDK

This API is in private preview and subject to change.

The client SDK provides useful functions for web-based extensions.

Methods

init()

Initiates the handshake with the host window.

Syntax

 void VSS.init(options)

Parameters

require()

Ensures that the AMD loader from the host is configured and fetches a script (AMD) module (and its dependencies) . If no callback is supplied, this will still perform an asynchronous fetch of the module (unlike AMD require which returns synchronously). This method has no return value.

Usage:

VSS.require(["VSS/Controls", "VSS/Controls/Grids"], function(Controls, Grids) { ... });

Syntax

 void VSS.require(modules, callback)

Parameters

  • modules: string[] or string. A single module path (string) or array of paths (string[])
  • callback: Function. Optional. Method called once the modules have been loaded.

ready()

Register a callback that gets called once the initial setup/handshake has completed. If the initial setup is already completed, the callback is invoked at the end of the current call stack.

Syntax

 void VSS.ready(callback)

Parameters

  • callback: (): void.

notifyLoadSucceeded()

Notifies the host that the extension successfully loaded (stop showing the loading indicator)

Syntax

 void VSS.notifyLoadSucceeded()

notifyLoadFailed()

Notifies the host that the extension failed to load

Syntax

 void VSS.notifyLoadFailed(e)

Parameters

  • e: any.

getWebContext()

Get the web context from the parent host

Syntax

 WebContext VSS.getWebContext()

Returns

getConfiguration()

Get the configuration data passed in the initial handshake from the parent frame

Syntax

 any VSS.getConfiguration()

Returns

  • any

getExtensionContext()

Get the context about the extension that owns the content that is being hosted

Syntax

 IExtensionContext VSS.getExtensionContext()

Returns

getContribution()

Gets the information about the contribution that first caused this extension to load.

Syntax

 Contribution VSS.getContribution()

Returns

getService<T>()

Get a contributed service from the parent host.

Syntax

 IPromise<T> VSS.getService(contributionId, context)

Parameters

  • contributionId: string.
  • context: Object. Optional.

Returns

getServiceContribution()

Get the contribution with the given contribution id. The returned contribution has a method to get a registered object within that contribution.

Syntax

 IPromise<IServiceContribution> VSS.getServiceContribution(contributionId)

Parameters

  • contributionId: string. ID of the contribution to get

Returns

getServiceContributions()

Get contributions that target a given contribution id. The returned contributions have a method to get a registered object within that contribution.

Syntax

 IPromise<IServiceContribution[]> VSS.getServiceContributions(targetContributionId)

Parameters

  • targetContributionId: string. Contributions that target the contribution with this ID will be returned

Returns

register()

Register an object (instance or factory method) that this extension exposes to the host frame.

Syntax

 void VSS.register(instanceId, instance)

Parameters

  • instanceId: string. unique ID of the registered object
  • instance: Object or <unknown_object_signature_kind>. Either: (1) an object instance, or (2) a function that takes optional context data and returns an object instance.

getRegisteredObject()

Get an instance of an object registered with the given id

Syntax

 Object VSS.getRegisteredObject(instanceId, contextData)

Parameters

  • instanceId: string. unique ID of the registered object
  • contextData: Object. Optional. Optional context data to pass to the contructor of an object factory method

Returns

  • Object

getAccessToken()

Fetch an access token which will allow calls to be made to other VSTS services

Syntax

 IPromise<ISessionToken> VSS.getAccessToken()

Returns

getAppToken()

Fetch an token which can be used to identify the current user

Syntax

 IPromise<ISessionToken> VSS.getAppToken()

Returns

resize()

Requests the parent window to resize the container for this extension based on the current extension size.

Syntax

 void VSS.resize()