Microsoft.VisualStudio.LiveShare 1.0.6

VS Live Share Extension API

Enables other VS extensions to access Live Share capabilities.

PRELIMINARY DOCUMENTATION - APIs are still in development and subject to change.

API Overview

To extend Live Share, declare and export collaboration service factories for components that will be activated by Live Share during collaboration sessions. Typically, there is a host component that provides methods and events to corresponding guest component(s) via RPC (remote procedure calls). The Scope property on the ExportCollaborationService attribute indicates which kind of sessions (host or guest) a collaboration service will be activated for; the Role property indicates how the collaboration service uses RPC, if at all.

Host collaboration service

To provide an RPC service from the host side, first define an RPC interface that declares the methods and events that will be provided to remote guests. For details, see the RPC interfaces section below.

public interface IExampleService { ... }

Then create a factory with RemoteService role capable of creating objects that implement that interface. The ExportCollaborationService attribute uses MEF to export the factory in a way that it can be discovered and activated by Live Share.

[ExportCollaborationService(
    typeof(IExampleService),
    Name = "example",
    Scope = SessionScope.Host,
    Role = ServiceRole.RemoteService
)]
public class ExampleHostFactory : ICollaborationServiceFactory
{
    public Task<ICollaborationService> CreateServiceAsync(
        CollaborationSession collaborationSession, CancellationToken cancellationToken)
    {
        return Task.FromResult<ICollaborationService>(new ExampleHostService(collaborationSession));
    }
}

public class ExampleHostService : IExampleService, ICollaborationService
{
    ...

The ExportCollaborationService.Name property is requred for remote services; it is the name of the RPC service that the guest uses when requesting a proxy for the service.

Guest collaboration service

To consume a host's RPC service on the guest side, create a factory with RemoteClient role that returns an object that acts as a client for the remote service.

[ExportCollaborationService(
    typeof(ExampleGuestService),
    Scope = SessionScope.Guest,
    Role = ServiceRole.RemoteClient
)]
public class Factory : ICollaborationServiceFactory
{
    public Task<ICollaborationService> CreateServiceAsync(
        CollaborationSession collaborationSession, CancellationToken cancellationToken)
    {
        return Task.FromResult<ICollaborationService>(new ExampleGuestService(collaborationSession));
    }
}

public class ExampleGuestService : ICollaborationService
{
    public async Task ExampleRemoteCall()
    {
        var exampleServiceProxy = await this.collaborationSession.
            GetRemoteServiceAsync<IExampleService>("example", CancellationToken.None);
        
        exampleServiceProxy.DataChanged += (sender, e) => ...

        await exampleServiceProxy.SetDataAsync(...);
    }
}

The guest collaboration service first obtains a proxy to the remote service provided by the host, via collaborationSession.GetRemoteServiceAsync(). (The specified name must match the name the host service was exported with.) After that it can use the proxy to invoke remote methods on add remote event-handlers.

Messaging (RPC)

Messaging is built around the concept of named RPC services that can be shared by a host. Guests can then use proxies to invoke requests on the services and send/receive notifications to/from the services. When requesting a proxy, the service name can be optionally prefixed with an extension ID (separated by a dot) to reference a service provided by another extension. A name with no prefix (the most typical usage) refers to a service provided by the same extension (remoted across the session).

Attempts to call methods while the service is not available result in RemoteServiceProxyExceptions. Any unhandled exceptions thrown from remote methods get propagated back to the caller and rethrown as RemoteServiceResponseExceptions, including the remote stack trace.

RPC interfaces

Four kinds of members are supported on RPC interfaces:

1. Async task methods: These methods return Task or Task<T> and may be used to await a result or exception. An exception thrown by the remote service will be propagated back and re-thrown to the caller. These methods must have a CancellationToken as their last parameter, that can be used to remotely cancel the execution.
2. Async task methods with progress: Similar to above, but these also methods include an IProgress<T> parameter before the CancellationToken. The progress events will be automatically sent back over RPC until the method returns.
3. Async void methods: These methods return void and are implicitly async, with semantics similar to local async void methods: the execution runs asynchronously and it is not possible to await any result or exception.
4. Events: Ordinary C# events can work remotely.

All method parameters, method return values, and event arguments must be JSON-serializable. Use [DataContract] and [DataMember] attributes on custom types to enable and control their serialization.

Following is an example RPC service that has several methods and an event, using custom data contract and event args types:

public interface IExampleService
{
    Task<ExampleData> GetDataAsync(string parameter, CancellationToken cancellation);
    Task SetDataAsync(string parameter, ExampleData data, CancellationToken cancellation);
    event EventHandler<ExampleDataChangedEventArgs> DataChanged;
    void RunAndForget(string parameter);
    Task<ExampleData> RunWithProgressAsync(
        string parameter, IProgress<int> progress, CancellationToken cancellation);
}

[DataContract]
public class ExampleData
{
    [DataMember]
    public string Value { get; set;}
}

[DataContract]
public class ExampleDataChangedEventArgs : EventArgs
{
    [DataMember]
    public ExampleData Data { get; set; }
}

Path conversion and file access

Guests get a scoped, virtualized view of the host's shared files. To enable consistent communication between host and guests, the protocol uses a vsls: URI scheme, with a path relative to the shared root(s). VS extensions can use these CollaborationSession methods to convert between these virtual URIs and local file paths.

• ConvertLocalPathToSharedUri() - Converts a local file path to a vsls: URI.
• ConvertSharedUriToLocalPath() - Converts a vsls: URI to a local file path.
• DownloadFileAsync() - Downloads a file given a vsls: URI, if not alread downloaded. Returns a local path to the downloaded file. If the file is being co-edited then the file contents do not include unsaved changes, but saving the changes will update the downloaded file.

More Information

• VS Live Share Documentation: https://aka.ms/vsls-docs
• VS Live Share Site: https://aka.ms/vsls
• VS Live Share FAQ: https://aka.ms/vsls-faq
• Report a Problem: https://aka.ms/vsls-problem
• Contact Us: https://aka.ms/vsls-support
• License: https://aka.ms/vsls-license