Microsoft.VisualStudio.LiveShare 1.1.57

Enables VS extensions to access Live Share capabilities.

Install-Package Microsoft.VisualStudio.LiveShare -Version 1.1.57
dotnet add package Microsoft.VisualStudio.LiveShare --version 1.1.57
<PackageReference Include="Microsoft.VisualStudio.LiveShare" Version="1.1.57" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Microsoft.VisualStudio.LiveShare --version 1.1.57
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

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&lt;T&gt; 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&lt;T&gt; 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

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&lt;T&gt; 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&lt;T&gt; 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

Showing the top 1 GitHub repositories that depend on Microsoft.VisualStudio.LiveShare:

Repository Stars
microsoft/PTVS
Python Tools for Visual Studio

Version History

Version Downloads Last updated
1.1.57 18,357 7/23/2019
1.0.181 8,475 5/14/2019
1.0.6 2,435 3/27/2019
0.3.1074 27,446 1/7/2019
0.3.959 1,115 11/13/2018