lsp-extensions-specifications.md

title	description	date
VS Extensions to LSP Reference	A reference for extensions to LSP	2021-08-16

Visual Studio extensions to the Language Server Protocol

This document describes the Visual Studio specific extensions to the Language Server Protocol. These extensions can be used by servers to provide additional functionalities when communicating with a Visual Studio instance.

These extensions are composed of:

1. Classes which extend base classes from the LSP specification allowing to provide additional information to Visual Studio. For example VSDiagnostic extends Diagnostic adding support for tooltips, sorting, etc.
2. Additional methods like GetProjectContexts. These are listed in VSMethods.
3. Additional capabilities that a language server can provide to the Visual Studio client. These are defined in VSServerCapabilities and can be communicated to the client in the InitializeResult.capabilities field of the initialize request.
4. Additional values for enumerations described in the LSP protocol. For example VSDiagnosticTags extends DiagnosticTag.

A .NET implementation of these extensions can be found on NuGet. Add a reference to these packages into the language server csproj file (and, if necessary, into the Visual Studio extension csproj file) using the latest package version available on NuGet:

  <ItemGroup>
    <PackageReference Include="Microsoft.VisualStudio.LanguageServer.Protocol" Version="17.2.8" />
    <PackageReference Include="Microsoft.VisualStudio.LanguageServer.Protocol.Extensions" Version="17.2.8" />
  </ItemGroup>

When using this package in a language server, configure the JsonSerializer using VSExtensionUtilities.AddVSExtensionConverters in order to allow extensions classes to be correctly deserialized. For example, this allows the JsonSerializer to correctly deserialize the CodeAction.Diagnostics entries of a codeAction/resolve request into VSDiagnostic objects even if CodeAction.Diagnostics is defined as an array of Diagnostic objects.

New methods

GetProjectContexts

GetProjectContexts requests are sent from the client to the server to retrieve a list of the project contexts associated with a text document. An example of project contexts are multiple target frameworks in SDK style .NET projects.

The labels of all project contexts are presented to the user in the navigation bar at the top of the document. When the user changes the project context in the navigation bar, the active project context is changed.

The client includes the active project context in requests to the server by filling in the VSTextDocumentIdentifier._vs_projectContext property.

Server Capability

• property path (optional): _vs_projectContextProvider
• property type: boolean

Request

• method: textDocument/_vs_getProjectContexts
• params: VSGetProjectContextsParams

Response

• result: VSProjectContextList

Extensions specification

VSDiagnostic

VSDiagnostic extends Diagnostic providing additional properties used by Visual Studio.

export interface VSDiagnostic extends Diagnostic {

    /**
     * Gets or sets the project and context (e.g. Win32, MacOS, etc.) in which the diagnostic was generated.
    **/
    _vs_projects? : VSDiagnosticProjectInformation[],

    /**
     * Gets or sets an expanded description of the diagnostic.
    **/
    _vs_expandedMessage? : string,

    /**
     * Gets or sets a message shown when the user hovers over an error. If null, then Diagnostic.message
     * is used (use VSDiagnosticTags.SuppressEditorToolTip to prevent a tool tip from being shown).
    **/
    _vs_toolTip? : string,

    /**
     * Gets or sets a non-human-readable identier allowing consolidation of multiple equivalent diagnostics
     * (e.g. the same syntax error from builds targeting different platforms).
    **/
    _vs_identifier? : string,

    /**
     * Gets or sets a string describing the diagnostic types (e.g. Security, Performance, Style, etc.).
    **/
    _vs_diagnosticType? : string,

    /**
     * Gets or sets a rank associated with this diagnostic, used for the default sort.
     * VSDiagnosticRank.Default will be used if no rank is specified.
    **/
    _vs_diagnosticRank? : VSDiagnosticRank,

    /**
     * Gets or sets an ID used to associate this diagnostic with a corresponding line in the output window.
    **/
    _vs_outputId? : integer,
}

VSDiagnosticProjectInformation

VSDiagnosticProjectInformation represents the project and context in which the VSDiagnostic is generated.

export interface VSDiagnosticProjectInformation {

    /**
     * Gets or sets a human-readable identifier for the project in which the diagnostic was generated.
    **/
    _vs_projectName? : string,

    /**
     * Gets or sets a human-readable identifier for the build context (e.g. Win32 or MacOS)
     * in which the diagnostic was generated.
    **/
    _vs_context? : string,

    /**
     * Gets or sets the unique identifier for the project in which the diagnostic was generated.
    **/
    _vs_projectIdentifier? : string,
}

VSDiagnosticRank

VSDiagnosticRank represents the rank of a VSDiagnostic object.

export enum VSDiagnosticRank {

    /**
     * Highest priority.
    **/
    Highest = 100,

    /**
     * High priority.
    **/
    High = 200,

    /**
     * Default priority.
    **/
    Default = 300,

    /**
     * Low priority.
    **/
    Low = 400,

    /**
     * Lowest priority.
    **/
    Lowest = 500,
}

VSDiagnosticTags

Additional DiagnosticTag values that are specific to Visual Studio.

export namespace VSDiagnosticTags {

    /**
     * A Diagnostic entry generated by the build.
    **/
    export const BuildError : DiagnosticTag = -1;

    /**
     * A Diagnostic entry generated by Intellisense.
    **/
    export const IntellisenseError : DiagnosticTag = -2;

    /**
     * A Diagnostic entry that could be generated from both builds
     * and Intellisense.
     * 
     * Diagnostic entries tagged with VSDiagnosticTags.PotentialDuplicate will be hidden
     * in the error list if the error list is displaying build and intellisense
     * errors.
    **/
    export const PotentialDuplicate : DiagnosticTag = -3;

    /**
     * A Diagnostic entry is never displayed in the error list.
    **/
    export const HiddenInErrorList : DiagnosticTag = -4;

    /**
     * The Diagnostic entry is always displayed in the error list.
    **/
    export const VisibleInErrorList : DiagnosticTag = -5;

    /**
     * The Diagnostic entry is never displayed in the editor.
    **/
    export const HiddenInEditor : DiagnosticTag = -6;

    /**
     * No tooltip is shown for the Diagnostic entry in the editor.
    **/
    export const SuppressEditorToolTip : DiagnosticTag = -7;

    /**
     * The Diagnostic entry is represented in the Editor as an Edit
     * and Continue error.
    **/
    export const EditAndContinueError : DiagnosticTag = -8;
}

VSGetProjectContextsParams

VSGetProjectContextsParams represents the parameter that is sent with the 'textDocument/_vs_getProjectContexts' request.

export interface VSGetProjectContextsParams {

    /**
     * Gets or sets the document for which project contexts are queried.
    **/
    _vs_textDocument : TextDocumentItem,
}

VSImageId

VSImageId represents the unique identifier for a Visual Studio image asset. The identified is composed by a VSImageId._vs_guid and an integer. A list of valid image ids can be retrieved from the KnownMonikers class from the Visual Studio SDK.

export interface VSImageId {

    /**
     * Gets or sets the VSImageId._vs_guid component of the unique identifier.
    **/
    _vs_guid : Guid,

    /**
     * Gets or sets the integer component of the unique identifier.
    **/
    _vs_id : integer,
}

VSLocation

VSLocation extends Location providing additional properties used by Visual Studio.

export interface VSLocation extends Location {

    /**
     * Gets or sets the project name to be displayed to user.
    **/
    _vs_projectName? : string,

    /**
     * Gets or sets the text value for the display path.
     * In case the actual path on disk would be confusing for users, this should be a friendly display name.
     * This doesn't have to correspond to a real file path, but must be parsable by the System.IO.Path.GetFileName(System.String) method.
    **/
    _vs_displayPath? : string,
}

VSMethods

VSMethods contains the string values for all Language Server Protocol Visual Studio specific methods.

export namespace VSMethods {

    /**
     * Method name for 'textDocument/_vs_getProjectContexts'.
     * The 'textDocument/_vs_getProjectContexts' request is sent from the client to the server to query
     * the list of project context associated with a document.
     * This method has a parameter of type VSGetProjectContextsParams and a return value of type
     * VSProjectContextList.
     * In order to enable the client to send the 'textDocument/_vs_getProjectContexts' requests, the server must
     * set the VSServerCapabilities._vs_projectContextProvider property.
    **/
    export const GetProjectContextsName : string = 'textDocument/_vs_getProjectContexts';
}

VSProjectContext

VSProjectContext represents a project context.

export interface VSProjectContext {

    /**
     * Gets or sets the label for the project context.
    **/
    _vs_label : string,

    /**
     * Gets or sets the unique identifier of the project context.
    **/
    _vs_id : string,

    /**
     * Gets or sets the context kind of the project context which is used to determine its associated icon.
    **/
    _vs_kind : VSProjectKind,
}

VSProjectContextList

VSProjectContextList represents the response to the 'textDocument/_vs_getProjectContexts' request.

export interface VSProjectContextList {

    /**
     * Gets or sets the document contexts associated with a text document.
    **/
    _vs_projectContexts : VSProjectContext[],

    /**
     * Gets or sets the index of the default entry of the VSProjectContext array.
    **/
    _vs_defaultIndex : integer,
}

VSProjectKind

VSProjectKind represents the various kinds of contexts.

export enum VSProjectKind {

    /**
     * C++ project.
    **/
    CPlusPlus = 1,

    /**
     * C# project.
    **/
    CSharp = 2,

    /**
     * Visual Basic project.
    **/
    VisualBasic = 3,
}

VSServerCapabilities

VSServerCapabilities extends ServerCapabilities allowing to provide additional capabilities supported by Visual Studio.

export interface VSServerCapabilities extends ServerCapabilities {

    /**
     * Gets or sets a value indicating whether the server supports the
     * 'textDocument/_vs_getProjectContexts' request.
    **/
    _vs_projectContextProvider? : boolean,
}

VSSymbolInformation

VSSymbolInformation extends SymbolInformation providing additional properties used by Visual Studio.

export interface VSSymbolInformation extends SymbolInformation {

    /**
     * Gets or sets the icon associated with the symbol. If specified, this icon is used instead of SymbolKind.
    **/
    _vs_icon? : VSImageId,

    /**
     * Gets or sets the description of the symbol.
    **/
    _vs_description? : string,

    /**
     * Gets or sets the hint text for the symbol.
    **/
    _vs_hintText? : string,
}

VSTextDocumentIdentifier

VSTextDocumentIdentifier extends TextDocumentIdentifier providing additional properties used by Visual Studio.

export interface VSTextDocumentIdentifier extends TextDocumentIdentifier {

    /**
     * Gets or sets the project context of the text document.
    **/
    _vs_projectContext? : VSProjectContext,
}