Updated more docs for github pages
This commit is contained in:
Leslie Richardson
Родитель
809d8161e1
Коммит
942a389e9e
|
|
@ -1,3 +1,9 @@
|
|||
---
|
||||
title: VS Extensions to LSP Reference
|
||||
description: A reference for extensions to LSP
|
||||
date: 2021-8-16
|
||||
---
|
||||
|
||||
# Visual Studio extensions to the Language Server Protocol
|
||||
|
||||
This document describes the Visual Studio specific extensions to the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/specifications/specification-current/). These extensions can be used by servers to provide additional functionalities when communicating with a Visual Studio instance.
|
||||
|
|
@ -6,7 +12,7 @@ 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`](#vsdiagnostic) extends [`Diagnostic`](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#diagnostic) adding support for tooltips, sorting, etc.
|
||||
1. Additional methods like [GetProjectContexts](#getprojectcontexts). These are listed in [`VSMethods`](#vsmethods).
|
||||
1. Additional capabilities that a language server can provide to the Visual Studio client. These are defined in [`VSServerCapabilities`](#vsservercapabilities) and can be communicated to the client in the [`InitializeResult.capabilities`](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#initializeResult) field of the [`initialize`](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#initialize) request.
|
||||
1. Additional values for enumerations described in the LSP protocol. For example [`VSDiagnosticTag`](#vsdiagnostictag) extends [`DiagnosticTag`](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#diagnosticTag).
|
||||
1. Additional values for enumerations described in the LSP protocol. For example [`VSDiagnosticTags`](#vsdiagnostictags) extends [`DiagnosticTag`](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#diagnosticTag).
|
||||
|
||||
A .NET implementation of these extensions can be found on [NuGet](https://www.nuget.org/packages/Microsoft.VisualStudio.LanguageServer.Protocol.Extensions).
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,173 @@
|
|||
I"á <h1 id="rule-based-activation-constraints">Rule based activation constraints</h1>
|
||||
|
||||
<p>One of the common concepts in Visual Studio Extensibility SDK is use of context based activation rules in code attributes. An example of these would <code class="language-plaintext highlighter-rouge">CommandVisibleWhen</code> attribute declaring when a command is made visible.</p>
|
||||
|
||||
<p>Our goal is to provide a common way to create such contexts, the current method is based on existing <a href="https://docs.microsoft.com/en-us/visualstudio/extensibility/how-to-use-rule-based-ui-context-for-visual-studio-extensions">Rule-based UI contexts</a> with a different set of context terms.</p>
|
||||
|
||||
<h2 id="constraint-attribute-arguments">Constraint attribute arguments</h2>
|
||||
|
||||
<p>Each constraint attribute will contain at least 3 required arguments that defines the expression:</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<p>Expression string: A boolean expression using <code class="language-plaintext highlighter-rouge">and</code>, <code class="language-plaintext highlighter-rouge">or</code>, <code class="language-plaintext highlighter-rouge">not</code> operations and term names that are defined in later arguments. Each term must be a single word (without spaces) and expression can utilize parantheses for grouping and <code class="language-plaintext highlighter-rouge">&</code>, <code class="language-plaintext highlighter-rouge">|</code>, <code class="language-plaintext highlighter-rouge">!</code> operators for <code class="language-plaintext highlighter-rouge">and</code>, <code class="language-plaintext highlighter-rouge">or</code>, <code class="language-plaintext highlighter-rouge">not</code> operations.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Term names: An array that contains the name of the terms used in the expression above.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Term definitions: An array that defines the each term in the order terms are defined in the names array above.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h2 id="example-definition">Example definition</h2>
|
||||
|
||||
<p>In the example below, the code attributes defines when a command is in enabled state.</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<p>The expression indicates that command is enabled when both <code class="language-plaintext highlighter-rouge">SolutionLoaded</code> and <code class="language-plaintext highlighter-rouge">IsValidFile</code> terms are true.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><code class="language-plaintext highlighter-rouge">SolutionLoaded</code> term is defined as <code class="language-plaintext highlighter-rouge">SolutionState:Exists</code> which indicates, the term evaluates to <code class="language-plaintext highlighter-rouge">true</code> when a solution exists in the IDE.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><code class="language-plaintext highlighter-rouge">IsValidFile</code> term is true when selected file in Solution Explorer is a jpeg or text file as defined by the file extension.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<div class="language-csharp highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">[</span><span class="nf">CommandEnabledWhen</span><span class="p">(</span>
|
||||
<span class="s">"SolutionLoaded & IsValidFile"</span><span class="p">,</span>
|
||||
<span class="k">new</span> <span class="kt">string</span><span class="p">[]</span> <span class="p">{</span>
|
||||
<span class="s">"SolutionLoaded"</span><span class="p">,</span>
|
||||
<span class="s">"IsValidFile"</span> <span class="p">},</span>
|
||||
<span class="k">new</span> <span class="kt">string</span><span class="p">[]</span> <span class="p">{</span>
|
||||
<span class="s">"SolutionState:Exists"</span><span class="p">,</span>
|
||||
<span class="s">"ClientContext:Shell.ActiveSelectionFileName=(.jpg|.jpeg|.txt)$"</span> <span class="p">})]</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="available-terms">Available terms</h2>
|
||||
|
||||
<p>Following is the list of terms currently supported by expression engine.</p>
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Term</td>
|
||||
<td>Description</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>SolutionHasProjectBuildProperty:<property>=<regex></td>
|
||||
<td>The term is true when solution has a loaded project with the specified build property and property value matches to regex filter provided.</td>
|
||||
<td>Â </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SolutionHasProjectCapability:<expression></td>
|
||||
<td>True whenever solution has a project with capabilities matching the provided subexpression. An expression can be something like VB</td>
|
||||
<td>CSharp.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SolutionHasProjectFlavor:<guid></td>
|
||||
<td>True whenever a solution has project that is flavored (aggregated) and has a flavor matching the given project type GUID.</td>
|
||||
<td>Â </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SolutionState:<state></td>
|
||||
<td>True when solution state matches to provided value, see <a href="#solution-states">solution states</a> for list of values.</td>
|
||||
<td>Â </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>ProjectAddedItem:<pattern></td>
|
||||
<td>The term is true when a file matching the “patternâ€<C3A2> is added to a project in the soluion that is opened.</td>
|
||||
<td>Â </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>ClientContext:<key>=<pattern></td>
|
||||
<td>True when the provided client context key matches to regular expression. See <a href="#client-contexts">client contexts</a> for more details.</td>
|
||||
<td>Â </td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h2 id="solution-states">Solution states</h2>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>State</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>NoSolution</td>
|
||||
<td>No solution loaded.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Exists</td>
|
||||
<td>A solution is opened but may be in loaded or loading state.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>FullyLoaded</td>
|
||||
<td>A solution is opened and fully loaded.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Empty</td>
|
||||
<td>Solution contains no projects but may contain solution items.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SingleProject</td>
|
||||
<td>Solution contains a single project.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>MultipleProject</td>
|
||||
<td>Solution contains multiple projects.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Building</td>
|
||||
<td>Solution is building.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h2 id="client-contexts">Client contexts</h2>
|
||||
<p>Activation rules can also utilize the <a href="ExtensionAnatomy.md#client-context">client context</a> contents as parts of its expression.</p>
|
||||
|
||||
<p>Currently, the client context is limited to a small set of values in IDE state:</p>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Context key</th>
|
||||
<th>Definition</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Shell.ActiveSelectionUri</td>
|
||||
<td>Full URI for the selected item in solution explorer.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Shell.ActiveSelectionPath</td>
|
||||
<td>Full path for the selected item in solution explorer.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Shell.ActiveSelectionFileName</td>
|
||||
<td>File name of the selected item in solution explorer.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Shell.ActiveEditorContentType</td>
|
||||
<td>Content type of the active editor view.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Shell.ActiveEditorFileName</td>
|
||||
<td>File name for the document that belongs to active editor view.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
:ET
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
I"á<h1 id="announcements">Announcements</h1>
|
||||
<p>Use this page to stay up-to-date on all upcoming extensibility announcements and critical SDK/API updates.</p>
|
||||
|
||||
<h2 id="august-16-2021">August 16, 2021</h2>
|
||||
<ul>
|
||||
<li></li>
|
||||
</ul>
|
||||
:ET
|
||||
|
|
@ -0,0 +1,375 @@
|
|||
I"Vk<h1 id="visual-studio-extensions-to-the-language-server-protocol">Visual Studio extensions to the Language Server Protocol</h1>
|
||||
|
||||
<p>This document describes the Visual Studio specific extensions to the <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-current/">Language Server Protocol</a>. These extensions can be used by servers to provide additional functionalities when communicating with a Visual Studio instance.</p>
|
||||
|
||||
<p>These extensions are composed of:</p>
|
||||
<ol>
|
||||
<li>Classes which extend base classes from the LSP specification allowing to provide additional information to Visual Studio. For example <a href="#vsdiagnostic"><code class="language-plaintext highlighter-rouge">VSDiagnostic</code></a> extends <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-current/#diagnostic"><code class="language-plaintext highlighter-rouge">Diagnostic</code></a> adding support for tooltips, sorting, etc.</li>
|
||||
<li>Additional methods like <a href="#getprojectcontexts">GetProjectContexts</a>. These are listed in <a href="#vsmethods"><code class="language-plaintext highlighter-rouge">VSMethods</code></a>.</li>
|
||||
<li>Additional capabilities that a language server can provide to the Visual Studio client. These are defined in <a href="#vsservercapabilities"><code class="language-plaintext highlighter-rouge">VSServerCapabilities</code></a> and can be communicated to the client in the <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#initializeResult"><code class="language-plaintext highlighter-rouge">InitializeResult.capabilities</code></a> field of the <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#initialize"><code class="language-plaintext highlighter-rouge">initialize</code></a> request.</li>
|
||||
<li>Additional values for enumerations described in the LSP protocol. For example <a href="#vsdiagnostictags"><code class="language-plaintext highlighter-rouge">VSDiagnosticTags</code></a> extends <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-current/#diagnosticTag"><code class="language-plaintext highlighter-rouge">DiagnosticTag</code></a>.</li>
|
||||
</ol>
|
||||
|
||||
<p>A .NET implementation of these extensions can be found on <a href="https://www.nuget.org/packages/Microsoft.VisualStudio.LanguageServer.Protocol.Extensions">NuGet</a>.</p>
|
||||
|
||||
<p>When using this package in a language server, configure the <code class="language-plaintext highlighter-rouge">JsonSerializer</code> using <code class="language-plaintext highlighter-rouge">VSExtensionUtilities.AddVSExtensionConverters</code> in order to allow extensions classes to be correctly deserialized. For example, this allows the <code class="language-plaintext highlighter-rouge">JsonSerializer</code> to correctly deserialize the <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#codeAction"><code class="language-plaintext highlighter-rouge">CodeAction.Diagnostics</code></a> entries of a <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#codeAction_resolve"><code class="language-plaintext highlighter-rouge">codeAction/resolve</code></a> request into <a href="#vsdiagnostic"><code class="language-plaintext highlighter-rouge">VSDiagnostic</code></a> objects even if <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#codeAction"><code class="language-plaintext highlighter-rouge">CodeAction.Diagnostics</code></a> is defined as an array of <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-current/#diagnostic"><code class="language-plaintext highlighter-rouge">Diagnostic</code></a> objects.</p>
|
||||
|
||||
<h1 id="new-methods">New methods</h1>
|
||||
|
||||
<h2 id="getprojectcontexts">GetProjectContexts</h2>
|
||||
|
||||
<p><em>GetProjectContexts</em> 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 <a href="https://docs.microsoft.com/en-us/dotnet/standard/frameworks#how-to-specify-a-target-framework">multiple target frameworks</a> in SDK style .NET projects.</p>
|
||||
|
||||
<p>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.</p>
|
||||
|
||||
<p>The client includes the active project context in requests to the server by filling in the <a href="#vstextdocumentidentifier"><code class="language-plaintext highlighter-rouge">VSTextDocumentIdentifier._vs_projectContext</code></a> property.</p>
|
||||
|
||||
<p><em>Server Capability</em></p>
|
||||
|
||||
<ul>
|
||||
<li>property path (optional): <a href="#vsservercapabilities"><code class="language-plaintext highlighter-rouge">_vs_projectContextProvider</code></a></li>
|
||||
<li>property type: <code class="language-plaintext highlighter-rouge">boolean</code></li>
|
||||
</ul>
|
||||
|
||||
<p><em>Request</em></p>
|
||||
|
||||
<ul>
|
||||
<li>method: <code class="language-plaintext highlighter-rouge">textDocument/_vs_getProjectContexts</code></li>
|
||||
<li>params: <a href="#vsgetprojectcontextsparams"><code class="language-plaintext highlighter-rouge">VSGetProjectContextsParams</code></a></li>
|
||||
</ul>
|
||||
|
||||
<p><em>Response</em></p>
|
||||
|
||||
<ul>
|
||||
<li>result: <a href="#vsprojectcontextlist"><code class="language-plaintext highlighter-rouge">VSProjectContextList</code></a></li>
|
||||
</ul>
|
||||
|
||||
<h1 id="extensions-specification">Extensions specification</h1>
|
||||
|
||||
<h2 id="vsdiagnostic">VSDiagnostic</h2>
|
||||
|
||||
<p><a href="#vsdiagnostic"><code class="language-plaintext highlighter-rouge">VSDiagnostic</code></a> extends <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-current/"><code class="language-plaintext highlighter-rouge">Diagnostic</code></a> providing additional properties used by Visual Studio.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">interface</span> <span class="nx">VSDiagnostic</span> <span class="kd">extends</span> <span class="nx">Diagnostic</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the project and context (e.g. Win32, MacOS, etc.) in which the diagnostic was generated.
|
||||
**/</span>
|
||||
<span class="nl">_vs_projects</span><span class="p">?</span> <span class="p">:</span> <span class="nx">VSDiagnosticProjectInformation</span><span class="p">[],</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets an expanded description of the diagnostic.
|
||||
**/</span>
|
||||
<span class="nx">_vs_expandedMessage</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* 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).
|
||||
**/</span>
|
||||
<span class="nx">_vs_toolTip</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* 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).
|
||||
**/</span>
|
||||
<span class="nx">_vs_identifier</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets a string describing the diagnostic types (e.g. Security, Performance, Style, etc.).
|
||||
**/</span>
|
||||
<span class="nx">_vs_diagnosticType</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets a rank associated with this diagnostic, used for the default sort.
|
||||
* VSDiagnosticRank.Default will be used if no rank is specified.
|
||||
**/</span>
|
||||
<span class="nx">_vs_diagnosticRank</span><span class="p">?</span> <span class="p">:</span> <span class="nx">VSDiagnosticRank</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets an ID used to associate this diagnostic with a corresponding line in the output window.
|
||||
**/</span>
|
||||
<span class="nx">_vs_outputId</span><span class="p">?</span> <span class="p">:</span> <span class="nx">integer</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vsdiagnosticprojectinformation">VSDiagnosticProjectInformation</h2>
|
||||
|
||||
<p><a href="#vsdiagnosticprojectinformation"><code class="language-plaintext highlighter-rouge">VSDiagnosticProjectInformation</code></a> represents the project and context in which the <a href="#vsdiagnostic"><code class="language-plaintext highlighter-rouge">VSDiagnostic</code></a> is generated.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">interface</span> <span class="nx">VSDiagnosticProjectInformation</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets a human-readable identifier for the project in which the diagnostic was generated.
|
||||
**/</span>
|
||||
<span class="nl">_vs_projectName</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets a human-readable identifier for the build context (e.g. Win32 or MacOS)
|
||||
* in which the diagnostic was generated.
|
||||
**/</span>
|
||||
<span class="nx">_vs_context</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the unique identifier for the project in which the diagnostic was generated.
|
||||
**/</span>
|
||||
<span class="nx">_vs_projectIdentifier</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vsdiagnosticrank">VSDiagnosticRank</h2>
|
||||
|
||||
<p><a href="#vsdiagnosticrank"><code class="language-plaintext highlighter-rouge">VSDiagnosticRank</code></a> represents the rank of a <a href="#vsdiagnostic"><code class="language-plaintext highlighter-rouge">VSDiagnostic</code></a> object.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">enum</span> <span class="nx">VSDiagnosticRank</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Highest priority.
|
||||
**/</span>
|
||||
<span class="nx">Highest</span> <span class="o">=</span> <span class="mi">100</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* High priority.
|
||||
**/</span>
|
||||
<span class="nx">High</span> <span class="o">=</span> <span class="mi">200</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Default priority.
|
||||
**/</span>
|
||||
<span class="nx">Default</span> <span class="o">=</span> <span class="mi">300</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Low priority.
|
||||
**/</span>
|
||||
<span class="nx">Low</span> <span class="o">=</span> <span class="mi">400</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Lowest priority.
|
||||
**/</span>
|
||||
<span class="nx">Lowest</span> <span class="o">=</span> <span class="mi">500</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vsdiagnostictags">VSDiagnosticTags</h2>
|
||||
|
||||
<p>Additional <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-current/"><code class="language-plaintext highlighter-rouge">DiagnosticTag</code></a> values that are specific to Visual Studio.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="k">namespace</span> <span class="nx">VSDiagnosticTags</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* A Diagnostic entry generated by the build.
|
||||
**/</span>
|
||||
<span class="k">export</span> <span class="kd">const</span> <span class="nx">BuildError</span> <span class="p">:</span> <span class="nx">DiagnosticTag</span> <span class="o">=</span> <span class="o">-</span><span class="mi">1</span><span class="p">;</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* A Diagnostic entry generated by Intellisense.
|
||||
**/</span>
|
||||
<span class="k">export</span> <span class="kd">const</span> <span class="nx">IntellisenseError</span> <span class="p">:</span> <span class="nx">DiagnosticTag</span> <span class="o">=</span> <span class="o">-</span><span class="mi">2</span><span class="p">;</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* 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.
|
||||
**/</span>
|
||||
<span class="k">export</span> <span class="kd">const</span> <span class="nx">PotentialDuplicate</span> <span class="p">:</span> <span class="nx">DiagnosticTag</span> <span class="o">=</span> <span class="o">-</span><span class="mi">3</span><span class="p">;</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* A Diagnostic entry is never displayed in the error list.
|
||||
**/</span>
|
||||
<span class="k">export</span> <span class="kd">const</span> <span class="nx">HiddenInErrorList</span> <span class="p">:</span> <span class="nx">DiagnosticTag</span> <span class="o">=</span> <span class="o">-</span><span class="mi">4</span><span class="p">;</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* The Diagnostic entry is always displayed in the error list.
|
||||
**/</span>
|
||||
<span class="k">export</span> <span class="kd">const</span> <span class="nx">VisibleInErrorList</span> <span class="p">:</span> <span class="nx">DiagnosticTag</span> <span class="o">=</span> <span class="o">-</span><span class="mi">5</span><span class="p">;</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* The Diagnostic entry is never displayed in the editor.
|
||||
**/</span>
|
||||
<span class="k">export</span> <span class="kd">const</span> <span class="nx">HiddenInEditor</span> <span class="p">:</span> <span class="nx">DiagnosticTag</span> <span class="o">=</span> <span class="o">-</span><span class="mi">6</span><span class="p">;</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* No tooltip is shown for the Diagnostic entry in the editor.
|
||||
**/</span>
|
||||
<span class="k">export</span> <span class="kd">const</span> <span class="nx">SuppressEditorToolTip</span> <span class="p">:</span> <span class="nx">DiagnosticTag</span> <span class="o">=</span> <span class="o">-</span><span class="mi">7</span><span class="p">;</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* The Diagnostic entry is represented in the Editor as an Edit
|
||||
* and Continue error.
|
||||
**/</span>
|
||||
<span class="k">export</span> <span class="kd">const</span> <span class="nx">EditAndContinueError</span> <span class="p">:</span> <span class="nx">DiagnosticTag</span> <span class="o">=</span> <span class="o">-</span><span class="mi">8</span><span class="p">;</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vsgetprojectcontextsparams">VSGetProjectContextsParams</h2>
|
||||
|
||||
<p><a href="#vsgetprojectcontextsparams"><code class="language-plaintext highlighter-rouge">VSGetProjectContextsParams</code></a> represents the parameter that is sent with the ‘textDocument/_vs_getProjectContexts’ request.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">interface</span> <span class="nx">VSGetProjectContextsParams</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the document for which project contexts are queried.
|
||||
**/</span>
|
||||
<span class="nl">_vs_textDocument</span> <span class="p">:</span> <span class="nx">TextDocumentItem</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vsimageid">VSImageId</h2>
|
||||
|
||||
<p><a href="#vsimageid"><code class="language-plaintext highlighter-rouge">VSImageId</code></a> represents the unique identifier for a Visual Studio image asset. The identified is composed by a <a href="#vsimageid"><code class="language-plaintext highlighter-rouge">VSImageId._vs_guid</code></a> and an integer. A list of valid image ids can be retrieved from the <a href="https://docs.microsoft.com/en-us/dotnet/api/microsoft.visualstudio.imaging.knownmonikers">KnownMonikers class</a> from the Visual Studio SDK.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">interface</span> <span class="nx">VSImageId</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the VSImageId._vs_guid component of the unique identifier.
|
||||
**/</span>
|
||||
<span class="nl">_vs_guid</span> <span class="p">:</span> <span class="nx">Guid</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the integer component of the unique identifier.
|
||||
**/</span>
|
||||
<span class="nx">_vs_id</span> <span class="p">:</span> <span class="nx">integer</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vslocation">VSLocation</h2>
|
||||
|
||||
<p><a href="#vslocation"><code class="language-plaintext highlighter-rouge">VSLocation</code></a> extends <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-current/"><code class="language-plaintext highlighter-rouge">Location</code></a> providing additional properties used by Visual Studio.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">interface</span> <span class="nx">VSLocation</span> <span class="kd">extends</span> <span class="nx">Location</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the project name to be displayed to user.
|
||||
**/</span>
|
||||
<span class="nl">_vs_projectName</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* 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.
|
||||
**/</span>
|
||||
<span class="nx">_vs_displayPath</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vsmethods">VSMethods</h2>
|
||||
|
||||
<p><a href="#vsmethods"><code class="language-plaintext highlighter-rouge">VSMethods</code></a> contains the string values for all Language Server Protocol Visual Studio specific methods.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="k">namespace</span> <span class="nx">VSMethods</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* 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.
|
||||
**/</span>
|
||||
<span class="k">export</span> <span class="kd">const</span> <span class="nx">GetProjectContextsName</span> <span class="p">:</span> <span class="kr">string</span> <span class="o">=</span> <span class="dl">'</span><span class="s1">textDocument/_vs_getProjectContexts</span><span class="dl">'</span><span class="p">;</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vsprojectcontext">VSProjectContext</h2>
|
||||
|
||||
<p><a href="#vsprojectcontext"><code class="language-plaintext highlighter-rouge">VSProjectContext</code></a> represents a project context.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">interface</span> <span class="nx">VSProjectContext</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the label for the project context.
|
||||
**/</span>
|
||||
<span class="nl">_vs_label</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the unique identifier of the project context.
|
||||
**/</span>
|
||||
<span class="nx">_vs_id</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the context kind of the project context which is used to determine its associated icon.
|
||||
**/</span>
|
||||
<span class="nx">_vs_kind</span> <span class="p">:</span> <span class="nx">VSProjectKind</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vsprojectcontextlist">VSProjectContextList</h2>
|
||||
|
||||
<p><a href="#vsprojectcontextlist"><code class="language-plaintext highlighter-rouge">VSProjectContextList</code></a> represents the response to the ‘textDocument/_vs_getProjectContexts’ request.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">interface</span> <span class="nx">VSProjectContextList</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the document contexts associated with a text document.
|
||||
**/</span>
|
||||
<span class="nl">_vs_projectContexts</span> <span class="p">:</span> <span class="nx">VSProjectContext</span><span class="p">[],</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the index of the default entry of the VSProjectContext array.
|
||||
**/</span>
|
||||
<span class="nx">_vs_defaultIndex</span> <span class="p">:</span> <span class="nx">integer</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vsprojectkind">VSProjectKind</h2>
|
||||
|
||||
<p><a href="#vsprojectkind"><code class="language-plaintext highlighter-rouge">VSProjectKind</code></a> represents the various kinds of contexts.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">enum</span> <span class="nx">VSProjectKind</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* C++ project.
|
||||
**/</span>
|
||||
<span class="nx">CPlusPlus</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* C# project.
|
||||
**/</span>
|
||||
<span class="nx">CSharp</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Visual Basic project.
|
||||
**/</span>
|
||||
<span class="nx">VisualBasic</span> <span class="o">=</span> <span class="mi">3</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vsservercapabilities">VSServerCapabilities</h2>
|
||||
|
||||
<p><a href="#vsservercapabilities"><code class="language-plaintext highlighter-rouge">VSServerCapabilities</code></a> extends <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-current/"><code class="language-plaintext highlighter-rouge">ServerCapabilities</code></a> allowing to provide additional capabilities supported by Visual Studio.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">interface</span> <span class="nx">VSServerCapabilities</span> <span class="kd">extends</span> <span class="nx">ServerCapabilities</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets a value indicating whether the server supports the
|
||||
* 'textDocument/_vs_getProjectContexts' request.
|
||||
**/</span>
|
||||
<span class="nl">_vs_projectContextProvider</span><span class="p">?</span> <span class="p">:</span> <span class="nx">boolean</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vssymbolinformation">VSSymbolInformation</h2>
|
||||
|
||||
<p><a href="#vssymbolinformation"><code class="language-plaintext highlighter-rouge">VSSymbolInformation</code></a> extends <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-current/"><code class="language-plaintext highlighter-rouge">SymbolInformation</code></a> providing additional properties used by Visual Studio.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">interface</span> <span class="nx">VSSymbolInformation</span> <span class="kd">extends</span> <span class="nx">SymbolInformation</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the icon associated with the symbol. If specified, this icon is used instead of SymbolKind.
|
||||
**/</span>
|
||||
<span class="nl">_vs_icon</span><span class="p">?</span> <span class="p">:</span> <span class="nx">VSImageId</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the description of the symbol.
|
||||
**/</span>
|
||||
<span class="nx">_vs_description</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the hint text for the symbol.
|
||||
**/</span>
|
||||
<span class="nx">_vs_hintText</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vstextdocumentidentifier">VSTextDocumentIdentifier</h2>
|
||||
|
||||
<p><a href="#vstextdocumentidentifier"><code class="language-plaintext highlighter-rouge">VSTextDocumentIdentifier</code></a> extends <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-current/"><code class="language-plaintext highlighter-rouge">TextDocumentIdentifier</code></a> providing additional properties used by Visual Studio.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">interface</span> <span class="nx">VSTextDocumentIdentifier</span> <span class="kd">extends</span> <span class="nx">TextDocumentIdentifier</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the project context of the text document.
|
||||
**/</span>
|
||||
<span class="nl">_vs_projectContext</span><span class="p">?</span> <span class="p">:</span> <span class="nx">VSProjectContext</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
:ET
|
||||
|
|
@ -0,0 +1,164 @@
|
|||
I"g <h1 id="rule-based-activation-constraints">Rule based activation constraints</h1>
|
||||
|
||||
<p>One of the common concepts in Visual Studio Extensibility SDK is use of context based activation rules in code attributes. An example of these would <code class="language-plaintext highlighter-rouge">CommandVisibleWhen</code> attribute declaring when a command is made visible.</p>
|
||||
|
||||
<p>Our goal is to provide a common way to create such contexts, the current method is based on existing <a href="https://docs.microsoft.com/en-us/visualstudio/extensibility/how-to-use-rule-based-ui-context-for-visual-studio-extensions">Rule-based UI contexts</a> with a different set of context terms.</p>
|
||||
|
||||
<h2 id="constraint-attribute-arguments">Constraint attribute arguments</h2>
|
||||
|
||||
<p>Each constraint attribute will contain at least 3 required arguments that defines the expression:</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<p>Expression string: A boolean expression using <code class="language-plaintext highlighter-rouge">and</code>, <code class="language-plaintext highlighter-rouge">or</code>, <code class="language-plaintext highlighter-rouge">not</code> operations and term names that are defined in later arguments. Each term must be a single word (without spaces) and expression can utilize parantheses for grouping and <code class="language-plaintext highlighter-rouge">&</code>, <code class="language-plaintext highlighter-rouge">|</code>, <code class="language-plaintext highlighter-rouge">!</code> operators for <code class="language-plaintext highlighter-rouge">and</code>, <code class="language-plaintext highlighter-rouge">or</code>, <code class="language-plaintext highlighter-rouge">not</code> operations.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Term names: An array that contains the name of the terms used in the expression above.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Term definitions: An array that defines the each term in the order terms are defined in the names array above.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h2 id="example-definition">Example definition</h2>
|
||||
|
||||
<p>In the example below, the code attributes defines when a command is in enabled state.</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<p>The expression indicates that command is enabled when both <code class="language-plaintext highlighter-rouge">SolutionLoaded</code> and <code class="language-plaintext highlighter-rouge">IsValidFile</code> terms are true.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><code class="language-plaintext highlighter-rouge">SolutionLoaded</code> term is defined as <code class="language-plaintext highlighter-rouge">SolutionState:Exists</code> which indicates, the term evaluates to <code class="language-plaintext highlighter-rouge">true</code> when a solution exists in the IDE.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><code class="language-plaintext highlighter-rouge">IsValidFile</code> term is true when selected file in Solution Explorer is a jpeg or text file as defined by the file extension.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<div class="language-csharp highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">[</span><span class="nf">CommandEnabledWhen</span><span class="p">(</span>
|
||||
<span class="s">"SolutionLoaded & IsValidFile"</span><span class="p">,</span>
|
||||
<span class="k">new</span> <span class="kt">string</span><span class="p">[]</span> <span class="p">{</span>
|
||||
<span class="s">"SolutionLoaded"</span><span class="p">,</span>
|
||||
<span class="s">"IsValidFile"</span> <span class="p">},</span>
|
||||
<span class="k">new</span> <span class="kt">string</span><span class="p">[]</span> <span class="p">{</span>
|
||||
<span class="s">"SolutionState:Exists"</span><span class="p">,</span>
|
||||
<span class="s">"ClientContext:Shell.ActiveSelectionFileName=(.jpg|.jpeg|.txt)$"</span> <span class="p">})]</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="available-terms">Available terms</h2>
|
||||
|
||||
<p>Following is the list of terms currently supported by expression engine.</p>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Term</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>SolutionHasProjectBuildProperty:<property>=<regex></td>
|
||||
<td>The term is true when solution has a loaded project with the specified build property and property value matches to regex filter provided.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SolutionHasProjectCapability:<expression></td>
|
||||
<td>True whenever solution has a project with capabilities matching the provided sub-expression. An expression can be something like VB or C#.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SolutionHasProjectFlavor:<guid></td>
|
||||
<td>True whenever a solution has project that is flavored (aggregated) and has a flavor matching the given project type GUID.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SolutionState:<state></td>
|
||||
<td>True when solution state matches to provided value, see <a href="#solution-states">solution states</a> for list of values.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>ProjectAddedItem:<pattern></td>
|
||||
<td>The term is true when a file matching the “pattern” is added to a project in the solution that is opened.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>ClientContext:<key>=<pattern></td>
|
||||
<td>True when the provided client context key matches to regular expression. See <a href="#client-contexts">client contexts</a> for more details.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h2 id="solution-states">Solution states</h2>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>State</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>NoSolution</td>
|
||||
<td>No solution loaded.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Exists</td>
|
||||
<td>A solution is opened but may be in loaded or loading state.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>FullyLoaded</td>
|
||||
<td>A solution is opened and fully loaded.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Empty</td>
|
||||
<td>Solution contains no projects but may contain solution items.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SingleProject</td>
|
||||
<td>Solution contains a single project.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>MultipleProject</td>
|
||||
<td>Solution contains multiple projects.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Building</td>
|
||||
<td>Solution is building.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h2 id="client-contexts">Client contexts</h2>
|
||||
<p>Activation rules can also utilize the <a href="ExtensionAnatomy.md#client-context">client context</a> contents as parts of its expression.</p>
|
||||
|
||||
<p>Currently, the client context is limited to a small set of values in IDE state:</p>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Context key</th>
|
||||
<th>Definition</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Shell.ActiveSelectionUri</td>
|
||||
<td>Full URI for the selected item in solution explorer.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Shell.ActiveSelectionPath</td>
|
||||
<td>Full path for the selected item in solution explorer.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Shell.ActiveSelectionFileName</td>
|
||||
<td>File name of the selected item in solution explorer.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Shell.ActiveEditorContentType</td>
|
||||
<td>Content type of the active editor view.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Shell.ActiveEditorFileName</td>
|
||||
<td>File name for the document that belongs to active editor view.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
:ET
|
||||
|
|
@ -0,0 +1,167 @@
|
|||
I"£ <h1 id="rule-based-activation-constraints">Rule based activation constraints</h1>
|
||||
|
||||
<p>One of the common concepts in Visual Studio Extensibility SDK is use of context based activation rules in code attributes. An example of these would <code class="language-plaintext highlighter-rouge">CommandVisibleWhen</code> attribute declaring when a command is made visible.</p>
|
||||
|
||||
<p>Our goal is to provide a common way to create such contexts, the current method is based on existing <a href="https://docs.microsoft.com/en-us/visualstudio/extensibility/how-to-use-rule-based-ui-context-for-visual-studio-extensions">Rule-based UI contexts</a> with a different set of context terms.</p>
|
||||
|
||||
<h2 id="constraint-attribute-arguments">Constraint attribute arguments</h2>
|
||||
|
||||
<p>Each constraint attribute will contain at least 3 required arguments that defines the expression:</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<p>Expression string: A boolean expression using <code class="language-plaintext highlighter-rouge">and</code>, <code class="language-plaintext highlighter-rouge">or</code>, <code class="language-plaintext highlighter-rouge">not</code> operations and term names that are defined in later arguments. Each term must be a single word (without spaces) and expression can utilize parantheses for grouping and <code class="language-plaintext highlighter-rouge">&</code>, <code class="language-plaintext highlighter-rouge">|</code>, <code class="language-plaintext highlighter-rouge">!</code> operators for <code class="language-plaintext highlighter-rouge">and</code>, <code class="language-plaintext highlighter-rouge">or</code>, <code class="language-plaintext highlighter-rouge">not</code> operations.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Term names: An array that contains the name of the terms used in the expression above.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Term definitions: An array that defines the each term in the order terms are defined in the names array above.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h2 id="example-definition">Example definition</h2>
|
||||
|
||||
<p>In the example below, the code attributes defines when a command is in enabled state.</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<p>The expression indicates that command is enabled when both <code class="language-plaintext highlighter-rouge">SolutionLoaded</code> and <code class="language-plaintext highlighter-rouge">IsValidFile</code> terms are true.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><code class="language-plaintext highlighter-rouge">SolutionLoaded</code> term is defined as <code class="language-plaintext highlighter-rouge">SolutionState:Exists</code> which indicates, the term evaluates to <code class="language-plaintext highlighter-rouge">true</code> when a solution exists in the IDE.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><code class="language-plaintext highlighter-rouge">IsValidFile</code> term is true when selected file in Solution Explorer is a jpeg or text file as defined by the file extension.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<div class="language-csharp highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">[</span><span class="nf">CommandEnabledWhen</span><span class="p">(</span>
|
||||
<span class="s">"SolutionLoaded & IsValidFile"</span><span class="p">,</span>
|
||||
<span class="k">new</span> <span class="kt">string</span><span class="p">[]</span> <span class="p">{</span>
|
||||
<span class="s">"SolutionLoaded"</span><span class="p">,</span>
|
||||
<span class="s">"IsValidFile"</span> <span class="p">},</span>
|
||||
<span class="k">new</span> <span class="kt">string</span><span class="p">[]</span> <span class="p">{</span>
|
||||
<span class="s">"SolutionState:Exists"</span><span class="p">,</span>
|
||||
<span class="s">"ClientContext:Shell.ActiveSelectionFileName=(.jpg|.jpeg|.txt)$"</span> <span class="p">})]</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="available-terms">Available terms</h2>
|
||||
|
||||
<p>Following is the list of terms currently supported by expression engine.</p>
|
||||
|
||||
<p>| Term | Description
|
||||
| – | – |</p>
|
||||
|
||||
<table>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>SolutionHasProjectBuildProperty:<property>=<regex></td>
|
||||
<td>The term is true when solution has a loaded project with the specified build property and property value matches to regex filter provided.</td>
|
||||
<td>Â </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SolutionHasProjectCapability:<expression></td>
|
||||
<td>True whenever solution has a project with capabilities matching the provided subexpression. An expression can be something like VB</td>
|
||||
<td>CSharp.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SolutionHasProjectFlavor:<guid></td>
|
||||
<td>True whenever a solution has project that is flavored (aggregated) and has a flavor matching the given project type GUID.</td>
|
||||
<td>Â </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SolutionState:<state></td>
|
||||
<td>True when solution state matches to provided value, see <a href="#solution-states">solution states</a> for list of values.</td>
|
||||
<td>Â </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>ProjectAddedItem:<pattern></td>
|
||||
<td>The term is true when a file matching the “patternâ€<C3A2> is added to a project in the soluion that is opened.</td>
|
||||
<td>Â </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>ClientContext:<key>=<pattern></td>
|
||||
<td>True when the provided client context key matches to regular expression. See <a href="#client-contexts">client contexts</a> for more details.</td>
|
||||
<td>Â </td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h2 id="solution-states">Solution states</h2>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>State</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>NoSolution</td>
|
||||
<td>No solution loaded.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Exists</td>
|
||||
<td>A solution is opened but may be in loaded or loading state.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>FullyLoaded</td>
|
||||
<td>A solution is opened and fully loaded.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Empty</td>
|
||||
<td>Solution contains no projects but may contain solution items.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SingleProject</td>
|
||||
<td>Solution contains a single project.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>MultipleProject</td>
|
||||
<td>Solution contains multiple projects.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Building</td>
|
||||
<td>Solution is building.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h2 id="client-contexts">Client contexts</h2>
|
||||
<p>Activation rules can also utilize the <a href="ExtensionAnatomy.md#client-context">client context</a> contents as parts of its expression.</p>
|
||||
|
||||
<p>Currently, the client context is limited to a small set of values in IDE state:</p>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Context key</th>
|
||||
<th>Definition</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Shell.ActiveSelectionUri</td>
|
||||
<td>Full URI for the selected item in solution explorer.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Shell.ActiveSelectionPath</td>
|
||||
<td>Full path for the selected item in solution explorer.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Shell.ActiveSelectionFileName</td>
|
||||
<td>File name of the selected item in solution explorer.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Shell.ActiveEditorContentType</td>
|
||||
<td>Content type of the active editor view.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Shell.ActiveEditorFileName</td>
|
||||
<td>File name for the document that belongs to active editor view.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
:ET
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
I"
<h1 id="announcements">Announcements</h1>
|
||||
<p>Use this page to stay up-to-date on all upcoming extensibility announcements and critical SDK/API updates.</p>
|
||||
|
||||
<h2 id="august-26-2021">August 26, 2021</h2>
|
||||
<ul>
|
||||
<li>VSExtensibility site/repository goes public!</li>
|
||||
</ul>
|
||||
:ET
|
||||
|
|
@ -0,0 +1,375 @@
|
|||
I"Tk<h1 id="visual-studio-extensions-to-the-language-server-protocol">Visual Studio extensions to the Language Server Protocol</h1>
|
||||
|
||||
<p>This document describes the Visual Studio specific extensions to the <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-current/">Language Server Protocol</a>. These extensions can be used by servers to provide additional functionalities when communicating with a Visual Studio instance.</p>
|
||||
|
||||
<p>These extensions are composed of:</p>
|
||||
<ol>
|
||||
<li>Classes which extend base classes from the LSP specification allowing to provide additional information to Visual Studio. For example <a href="#vsdiagnostic"><code class="language-plaintext highlighter-rouge">VSDiagnostic</code></a> extends <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-current/#diagnostic"><code class="language-plaintext highlighter-rouge">Diagnostic</code></a> adding support for tooltips, sorting, etc.</li>
|
||||
<li>Additional methods like <a href="#getprojectcontexts">GetProjectContexts</a>. These are listed in <a href="#vsmethods"><code class="language-plaintext highlighter-rouge">VSMethods</code></a>.</li>
|
||||
<li>Additional capabilities that a language server can provide to the Visual Studio client. These are defined in <a href="#vsservercapabilities"><code class="language-plaintext highlighter-rouge">VSServerCapabilities</code></a> and can be communicated to the client in the <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#initializeResult"><code class="language-plaintext highlighter-rouge">InitializeResult.capabilities</code></a> field of the <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#initialize"><code class="language-plaintext highlighter-rouge">initialize</code></a> request.</li>
|
||||
<li>Additional values for enumerations described in the LSP protocol. For example <a href="#vsdiagnostictag"><code class="language-plaintext highlighter-rouge">VSDiagnosticTag</code></a> extends <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-current/#diagnosticTag"><code class="language-plaintext highlighter-rouge">DiagnosticTag</code></a>.</li>
|
||||
</ol>
|
||||
|
||||
<p>A .NET implementation of these extensions can be found on <a href="https://www.nuget.org/packages/Microsoft.VisualStudio.LanguageServer.Protocol.Extensions">NuGet</a>.</p>
|
||||
|
||||
<p>When using this package in a language server, configure the <code class="language-plaintext highlighter-rouge">JsonSerializer</code> using <code class="language-plaintext highlighter-rouge">VSExtensionUtilities.AddVSExtensionConverters</code> in order to allow extensions classes to be correctly deserialized. For example, this allows the <code class="language-plaintext highlighter-rouge">JsonSerializer</code> to correctly deserialize the <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#codeAction"><code class="language-plaintext highlighter-rouge">CodeAction.Diagnostics</code></a> entries of a <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#codeAction_resolve"><code class="language-plaintext highlighter-rouge">codeAction/resolve</code></a> request into <a href="#vsdiagnostic"><code class="language-plaintext highlighter-rouge">VSDiagnostic</code></a> objects even if <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#codeAction"><code class="language-plaintext highlighter-rouge">CodeAction.Diagnostics</code></a> is defined as an array of <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-current/#diagnostic"><code class="language-plaintext highlighter-rouge">Diagnostic</code></a> objects.</p>
|
||||
|
||||
<h1 id="new-methods">New methods</h1>
|
||||
|
||||
<h2 id="getprojectcontexts">GetProjectContexts</h2>
|
||||
|
||||
<p><em>GetProjectContexts</em> 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 <a href="https://docs.microsoft.com/en-us/dotnet/standard/frameworks#how-to-specify-a-target-framework">multiple target frameworks</a> in SDK style .NET projects.</p>
|
||||
|
||||
<p>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.</p>
|
||||
|
||||
<p>The client includes the active project context in requests to the server by filling in the <a href="#vstextdocumentidentifier"><code class="language-plaintext highlighter-rouge">VSTextDocumentIdentifier._vs_projectContext</code></a> property.</p>
|
||||
|
||||
<p><em>Server Capability</em></p>
|
||||
|
||||
<ul>
|
||||
<li>property path (optional): <a href="#vsservercapabilities"><code class="language-plaintext highlighter-rouge">_vs_projectContextProvider</code></a></li>
|
||||
<li>property type: <code class="language-plaintext highlighter-rouge">boolean</code></li>
|
||||
</ul>
|
||||
|
||||
<p><em>Request</em></p>
|
||||
|
||||
<ul>
|
||||
<li>method: <code class="language-plaintext highlighter-rouge">textDocument/_vs_getProjectContexts</code></li>
|
||||
<li>params: <a href="#vsgetprojectcontextsparams"><code class="language-plaintext highlighter-rouge">VSGetProjectContextsParams</code></a></li>
|
||||
</ul>
|
||||
|
||||
<p><em>Response</em></p>
|
||||
|
||||
<ul>
|
||||
<li>result: <a href="#vsprojectcontextlist"><code class="language-plaintext highlighter-rouge">VSProjectContextList</code></a></li>
|
||||
</ul>
|
||||
|
||||
<h1 id="extensions-specification">Extensions specification</h1>
|
||||
|
||||
<h2 id="vsdiagnostic">VSDiagnostic</h2>
|
||||
|
||||
<p><a href="#vsdiagnostic"><code class="language-plaintext highlighter-rouge">VSDiagnostic</code></a> extends <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-current/"><code class="language-plaintext highlighter-rouge">Diagnostic</code></a> providing additional properties used by Visual Studio.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">interface</span> <span class="nx">VSDiagnostic</span> <span class="kd">extends</span> <span class="nx">Diagnostic</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the project and context (e.g. Win32, MacOS, etc.) in which the diagnostic was generated.
|
||||
**/</span>
|
||||
<span class="nl">_vs_projects</span><span class="p">?</span> <span class="p">:</span> <span class="nx">VSDiagnosticProjectInformation</span><span class="p">[],</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets an expanded description of the diagnostic.
|
||||
**/</span>
|
||||
<span class="nx">_vs_expandedMessage</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* 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).
|
||||
**/</span>
|
||||
<span class="nx">_vs_toolTip</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* 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).
|
||||
**/</span>
|
||||
<span class="nx">_vs_identifier</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets a string describing the diagnostic types (e.g. Security, Performance, Style, etc.).
|
||||
**/</span>
|
||||
<span class="nx">_vs_diagnosticType</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets a rank associated with this diagnostic, used for the default sort.
|
||||
* VSDiagnosticRank.Default will be used if no rank is specified.
|
||||
**/</span>
|
||||
<span class="nx">_vs_diagnosticRank</span><span class="p">?</span> <span class="p">:</span> <span class="nx">VSDiagnosticRank</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets an ID used to associate this diagnostic with a corresponding line in the output window.
|
||||
**/</span>
|
||||
<span class="nx">_vs_outputId</span><span class="p">?</span> <span class="p">:</span> <span class="nx">integer</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vsdiagnosticprojectinformation">VSDiagnosticProjectInformation</h2>
|
||||
|
||||
<p><a href="#vsdiagnosticprojectinformation"><code class="language-plaintext highlighter-rouge">VSDiagnosticProjectInformation</code></a> represents the project and context in which the <a href="#vsdiagnostic"><code class="language-plaintext highlighter-rouge">VSDiagnostic</code></a> is generated.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">interface</span> <span class="nx">VSDiagnosticProjectInformation</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets a human-readable identifier for the project in which the diagnostic was generated.
|
||||
**/</span>
|
||||
<span class="nl">_vs_projectName</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets a human-readable identifier for the build context (e.g. Win32 or MacOS)
|
||||
* in which the diagnostic was generated.
|
||||
**/</span>
|
||||
<span class="nx">_vs_context</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the unique identifier for the project in which the diagnostic was generated.
|
||||
**/</span>
|
||||
<span class="nx">_vs_projectIdentifier</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vsdiagnosticrank">VSDiagnosticRank</h2>
|
||||
|
||||
<p><a href="#vsdiagnosticrank"><code class="language-plaintext highlighter-rouge">VSDiagnosticRank</code></a> represents the rank of a <a href="#vsdiagnostic"><code class="language-plaintext highlighter-rouge">VSDiagnostic</code></a> object.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">enum</span> <span class="nx">VSDiagnosticRank</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Highest priority.
|
||||
**/</span>
|
||||
<span class="nx">Highest</span> <span class="o">=</span> <span class="mi">100</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* High priority.
|
||||
**/</span>
|
||||
<span class="nx">High</span> <span class="o">=</span> <span class="mi">200</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Default priority.
|
||||
**/</span>
|
||||
<span class="nx">Default</span> <span class="o">=</span> <span class="mi">300</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Low priority.
|
||||
**/</span>
|
||||
<span class="nx">Low</span> <span class="o">=</span> <span class="mi">400</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Lowest priority.
|
||||
**/</span>
|
||||
<span class="nx">Lowest</span> <span class="o">=</span> <span class="mi">500</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vsdiagnostictags">VSDiagnosticTags</h2>
|
||||
|
||||
<p>Additional <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-current/"><code class="language-plaintext highlighter-rouge">DiagnosticTag</code></a> values that are specific to Visual Studio.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="k">namespace</span> <span class="nx">VSDiagnosticTags</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* A Diagnostic entry generated by the build.
|
||||
**/</span>
|
||||
<span class="k">export</span> <span class="kd">const</span> <span class="nx">BuildError</span> <span class="p">:</span> <span class="nx">DiagnosticTag</span> <span class="o">=</span> <span class="o">-</span><span class="mi">1</span><span class="p">;</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* A Diagnostic entry generated by Intellisense.
|
||||
**/</span>
|
||||
<span class="k">export</span> <span class="kd">const</span> <span class="nx">IntellisenseError</span> <span class="p">:</span> <span class="nx">DiagnosticTag</span> <span class="o">=</span> <span class="o">-</span><span class="mi">2</span><span class="p">;</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* 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.
|
||||
**/</span>
|
||||
<span class="k">export</span> <span class="kd">const</span> <span class="nx">PotentialDuplicate</span> <span class="p">:</span> <span class="nx">DiagnosticTag</span> <span class="o">=</span> <span class="o">-</span><span class="mi">3</span><span class="p">;</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* A Diagnostic entry is never displayed in the error list.
|
||||
**/</span>
|
||||
<span class="k">export</span> <span class="kd">const</span> <span class="nx">HiddenInErrorList</span> <span class="p">:</span> <span class="nx">DiagnosticTag</span> <span class="o">=</span> <span class="o">-</span><span class="mi">4</span><span class="p">;</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* The Diagnostic entry is always displayed in the error list.
|
||||
**/</span>
|
||||
<span class="k">export</span> <span class="kd">const</span> <span class="nx">VisibleInErrorList</span> <span class="p">:</span> <span class="nx">DiagnosticTag</span> <span class="o">=</span> <span class="o">-</span><span class="mi">5</span><span class="p">;</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* The Diagnostic entry is never displayed in the editor.
|
||||
**/</span>
|
||||
<span class="k">export</span> <span class="kd">const</span> <span class="nx">HiddenInEditor</span> <span class="p">:</span> <span class="nx">DiagnosticTag</span> <span class="o">=</span> <span class="o">-</span><span class="mi">6</span><span class="p">;</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* No tooltip is shown for the Diagnostic entry in the editor.
|
||||
**/</span>
|
||||
<span class="k">export</span> <span class="kd">const</span> <span class="nx">SuppressEditorToolTip</span> <span class="p">:</span> <span class="nx">DiagnosticTag</span> <span class="o">=</span> <span class="o">-</span><span class="mi">7</span><span class="p">;</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* The Diagnostic entry is represented in the Editor as an Edit
|
||||
* and Continue error.
|
||||
**/</span>
|
||||
<span class="k">export</span> <span class="kd">const</span> <span class="nx">EditAndContinueError</span> <span class="p">:</span> <span class="nx">DiagnosticTag</span> <span class="o">=</span> <span class="o">-</span><span class="mi">8</span><span class="p">;</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vsgetprojectcontextsparams">VSGetProjectContextsParams</h2>
|
||||
|
||||
<p><a href="#vsgetprojectcontextsparams"><code class="language-plaintext highlighter-rouge">VSGetProjectContextsParams</code></a> represents the parameter that is sent with the ‘textDocument/_vs_getProjectContexts’ request.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">interface</span> <span class="nx">VSGetProjectContextsParams</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the document for which project contexts are queried.
|
||||
**/</span>
|
||||
<span class="nl">_vs_textDocument</span> <span class="p">:</span> <span class="nx">TextDocumentItem</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vsimageid">VSImageId</h2>
|
||||
|
||||
<p><a href="#vsimageid"><code class="language-plaintext highlighter-rouge">VSImageId</code></a> represents the unique identifier for a Visual Studio image asset. The identified is composed by a <a href="#vsimageid"><code class="language-plaintext highlighter-rouge">VSImageId._vs_guid</code></a> and an integer. A list of valid image ids can be retrieved from the <a href="https://docs.microsoft.com/en-us/dotnet/api/microsoft.visualstudio.imaging.knownmonikers">KnownMonikers class</a> from the Visual Studio SDK.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">interface</span> <span class="nx">VSImageId</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the VSImageId._vs_guid component of the unique identifier.
|
||||
**/</span>
|
||||
<span class="nl">_vs_guid</span> <span class="p">:</span> <span class="nx">Guid</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the integer component of the unique identifier.
|
||||
**/</span>
|
||||
<span class="nx">_vs_id</span> <span class="p">:</span> <span class="nx">integer</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vslocation">VSLocation</h2>
|
||||
|
||||
<p><a href="#vslocation"><code class="language-plaintext highlighter-rouge">VSLocation</code></a> extends <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-current/"><code class="language-plaintext highlighter-rouge">Location</code></a> providing additional properties used by Visual Studio.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">interface</span> <span class="nx">VSLocation</span> <span class="kd">extends</span> <span class="nx">Location</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the project name to be displayed to user.
|
||||
**/</span>
|
||||
<span class="nl">_vs_projectName</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* 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.
|
||||
**/</span>
|
||||
<span class="nx">_vs_displayPath</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vsmethods">VSMethods</h2>
|
||||
|
||||
<p><a href="#vsmethods"><code class="language-plaintext highlighter-rouge">VSMethods</code></a> contains the string values for all Language Server Protocol Visual Studio specific methods.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="k">namespace</span> <span class="nx">VSMethods</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* 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.
|
||||
**/</span>
|
||||
<span class="k">export</span> <span class="kd">const</span> <span class="nx">GetProjectContextsName</span> <span class="p">:</span> <span class="kr">string</span> <span class="o">=</span> <span class="dl">'</span><span class="s1">textDocument/_vs_getProjectContexts</span><span class="dl">'</span><span class="p">;</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vsprojectcontext">VSProjectContext</h2>
|
||||
|
||||
<p><a href="#vsprojectcontext"><code class="language-plaintext highlighter-rouge">VSProjectContext</code></a> represents a project context.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">interface</span> <span class="nx">VSProjectContext</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the label for the project context.
|
||||
**/</span>
|
||||
<span class="nl">_vs_label</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the unique identifier of the project context.
|
||||
**/</span>
|
||||
<span class="nx">_vs_id</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the context kind of the project context which is used to determine its associated icon.
|
||||
**/</span>
|
||||
<span class="nx">_vs_kind</span> <span class="p">:</span> <span class="nx">VSProjectKind</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vsprojectcontextlist">VSProjectContextList</h2>
|
||||
|
||||
<p><a href="#vsprojectcontextlist"><code class="language-plaintext highlighter-rouge">VSProjectContextList</code></a> represents the response to the ‘textDocument/_vs_getProjectContexts’ request.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">interface</span> <span class="nx">VSProjectContextList</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the document contexts associated with a text document.
|
||||
**/</span>
|
||||
<span class="nl">_vs_projectContexts</span> <span class="p">:</span> <span class="nx">VSProjectContext</span><span class="p">[],</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the index of the default entry of the VSProjectContext array.
|
||||
**/</span>
|
||||
<span class="nx">_vs_defaultIndex</span> <span class="p">:</span> <span class="nx">integer</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vsprojectkind">VSProjectKind</h2>
|
||||
|
||||
<p><a href="#vsprojectkind"><code class="language-plaintext highlighter-rouge">VSProjectKind</code></a> represents the various kinds of contexts.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">enum</span> <span class="nx">VSProjectKind</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* C++ project.
|
||||
**/</span>
|
||||
<span class="nx">CPlusPlus</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* C# project.
|
||||
**/</span>
|
||||
<span class="nx">CSharp</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Visual Basic project.
|
||||
**/</span>
|
||||
<span class="nx">VisualBasic</span> <span class="o">=</span> <span class="mi">3</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vsservercapabilities">VSServerCapabilities</h2>
|
||||
|
||||
<p><a href="#vsservercapabilities"><code class="language-plaintext highlighter-rouge">VSServerCapabilities</code></a> extends <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-current/"><code class="language-plaintext highlighter-rouge">ServerCapabilities</code></a> allowing to provide additional capabilities supported by Visual Studio.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">interface</span> <span class="nx">VSServerCapabilities</span> <span class="kd">extends</span> <span class="nx">ServerCapabilities</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets a value indicating whether the server supports the
|
||||
* 'textDocument/_vs_getProjectContexts' request.
|
||||
**/</span>
|
||||
<span class="nl">_vs_projectContextProvider</span><span class="p">?</span> <span class="p">:</span> <span class="nx">boolean</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vssymbolinformation">VSSymbolInformation</h2>
|
||||
|
||||
<p><a href="#vssymbolinformation"><code class="language-plaintext highlighter-rouge">VSSymbolInformation</code></a> extends <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-current/"><code class="language-plaintext highlighter-rouge">SymbolInformation</code></a> providing additional properties used by Visual Studio.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">interface</span> <span class="nx">VSSymbolInformation</span> <span class="kd">extends</span> <span class="nx">SymbolInformation</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the icon associated with the symbol. If specified, this icon is used instead of SymbolKind.
|
||||
**/</span>
|
||||
<span class="nl">_vs_icon</span><span class="p">?</span> <span class="p">:</span> <span class="nx">VSImageId</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the description of the symbol.
|
||||
**/</span>
|
||||
<span class="nx">_vs_description</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the hint text for the symbol.
|
||||
**/</span>
|
||||
<span class="nx">_vs_hintText</span><span class="p">?</span> <span class="p">:</span> <span class="kr">string</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="vstextdocumentidentifier">VSTextDocumentIdentifier</h2>
|
||||
|
||||
<p><a href="#vstextdocumentidentifier"><code class="language-plaintext highlighter-rouge">VSTextDocumentIdentifier</code></a> extends <a href="https://microsoft.github.io/language-server-protocol/specifications/specification-current/"><code class="language-plaintext highlighter-rouge">TextDocumentIdentifier</code></a> providing additional properties used by Visual Studio.</p>
|
||||
<div class="language-typescript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kr">interface</span> <span class="nx">VSTextDocumentIdentifier</span> <span class="kd">extends</span> <span class="nx">TextDocumentIdentifier</span> <span class="p">{</span>
|
||||
|
||||
<span class="cm">/**
|
||||
* Gets or sets the project context of the text document.
|
||||
**/</span>
|
||||
<span class="nl">_vs_projectContext</span><span class="p">?</span> <span class="p">:</span> <span class="nx">VSProjectContext</span><span class="p">,</span>
|
||||
<span class="p">}</span>
|
||||
</code></pre></div></div>
|
||||
:ET
|
||||
|
|
@ -0,0 +1,171 @@
|
|||
I"ã <h1 id="rule-based-activation-constraints">Rule based activation constraints</h1>
|
||||
|
||||
<p>One of the common concepts in Visual Studio Extensibility SDK is use of context based activation rules in code attributes. An example of these would <code class="language-plaintext highlighter-rouge">CommandVisibleWhen</code> attribute declaring when a command is made visible.</p>
|
||||
|
||||
<p>Our goal is to provide a common way to create such contexts, the current method is based on existing <a href="https://docs.microsoft.com/en-us/visualstudio/extensibility/how-to-use-rule-based-ui-context-for-visual-studio-extensions">Rule-based UI contexts</a> with a different set of context terms.</p>
|
||||
|
||||
<h2 id="constraint-attribute-arguments">Constraint attribute arguments</h2>
|
||||
|
||||
<p>Each constraint attribute will contain at least 3 required arguments that defines the expression:</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<p>Expression string: A boolean expression using <code class="language-plaintext highlighter-rouge">and</code>, <code class="language-plaintext highlighter-rouge">or</code>, <code class="language-plaintext highlighter-rouge">not</code> operations and term names that are defined in later arguments. Each term must be a single word (without spaces) and expression can utilize parantheses for grouping and <code class="language-plaintext highlighter-rouge">&</code>, <code class="language-plaintext highlighter-rouge">|</code>, <code class="language-plaintext highlighter-rouge">!</code> operators for <code class="language-plaintext highlighter-rouge">and</code>, <code class="language-plaintext highlighter-rouge">or</code>, <code class="language-plaintext highlighter-rouge">not</code> operations.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Term names: An array that contains the name of the terms used in the expression above.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Term definitions: An array that defines the each term in the order terms are defined in the names array above.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h2 id="example-definition">Example definition</h2>
|
||||
|
||||
<p>In the example below, the code attributes defines when a command is in enabled state.</p>
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
<p>The expression indicates that command is enabled when both <code class="language-plaintext highlighter-rouge">SolutionLoaded</code> and <code class="language-plaintext highlighter-rouge">IsValidFile</code> terms are true.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><code class="language-plaintext highlighter-rouge">SolutionLoaded</code> term is defined as <code class="language-plaintext highlighter-rouge">SolutionState:Exists</code> which indicates, the term evaluates to <code class="language-plaintext highlighter-rouge">true</code> when a solution exists in the IDE.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><code class="language-plaintext highlighter-rouge">IsValidFile</code> term is true when selected file in Solution Explorer is a jpeg or text file as defined by the file extension.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<div class="language-csharp highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">[</span><span class="nf">CommandEnabledWhen</span><span class="p">(</span>
|
||||
<span class="s">"SolutionLoaded & IsValidFile"</span><span class="p">,</span>
|
||||
<span class="k">new</span> <span class="kt">string</span><span class="p">[]</span> <span class="p">{</span>
|
||||
<span class="s">"SolutionLoaded"</span><span class="p">,</span>
|
||||
<span class="s">"IsValidFile"</span> <span class="p">},</span>
|
||||
<span class="k">new</span> <span class="kt">string</span><span class="p">[]</span> <span class="p">{</span>
|
||||
<span class="s">"SolutionState:Exists"</span><span class="p">,</span>
|
||||
<span class="s">"ClientContext:Shell.ActiveSelectionFileName=(.jpg|.jpeg|.txt)$"</span> <span class="p">})]</span>
|
||||
</code></pre></div></div>
|
||||
|
||||
<h2 id="available-terms">Available terms</h2>
|
||||
|
||||
<p>Following is the list of terms currently supported by expression engine.</p>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Term</th>
|
||||
<th>Description</th>
|
||||
<th>Â </th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>SolutionHasProjectBuildProperty:<property>=<regex></td>
|
||||
<td>The term is true when solution has a loaded project with the specified build property and property value matches to regex filter provided.</td>
|
||||
<td>Â </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SolutionHasProjectCapability:<expression></td>
|
||||
<td>True whenever solution has a project with capabilities matching the provided sub-expression. An expression can be something like VB</td>
|
||||
<td>CSharp.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SolutionHasProjectFlavor:<guid></td>
|
||||
<td>True whenever a solution has project that is flavored (aggregated) and has a flavor matching the given project type GUID.</td>
|
||||
<td>Â </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SolutionState:<state></td>
|
||||
<td>True when solution state matches to provided value, see <a href="#solution-states">solution states</a> for list of values.</td>
|
||||
<td>Â </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>ProjectAddedItem:<pattern></td>
|
||||
<td>The term is true when a file matching the “patternâ€<C3A2> is added to a project in the solution that is opened.</td>
|
||||
<td>Â </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>ClientContext:<key>=<pattern></td>
|
||||
<td>True when the provided client context key matches to regular expression. See <a href="#client-contexts">client contexts</a> for more details.</td>
|
||||
<td>Â </td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h2 id="solution-states">Solution states</h2>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>State</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>NoSolution</td>
|
||||
<td>No solution loaded.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Exists</td>
|
||||
<td>A solution is opened but may be in loaded or loading state.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>FullyLoaded</td>
|
||||
<td>A solution is opened and fully loaded.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Empty</td>
|
||||
<td>Solution contains no projects but may contain solution items.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SingleProject</td>
|
||||
<td>Solution contains a single project.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>MultipleProject</td>
|
||||
<td>Solution contains multiple projects.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Building</td>
|
||||
<td>Solution is building.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h2 id="client-contexts">Client contexts</h2>
|
||||
<p>Activation rules can also utilize the <a href="ExtensionAnatomy.md#client-context">client context</a> contents as parts of its expression.</p>
|
||||
|
||||
<p>Currently, the client context is limited to a small set of values in IDE state:</p>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Context key</th>
|
||||
<th>Definition</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Shell.ActiveSelectionUri</td>
|
||||
<td>Full URI for the selected item in solution explorer.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Shell.ActiveSelectionPath</td>
|
||||
<td>Full path for the selected item in solution explorer.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Shell.ActiveSelectionFileName</td>
|
||||
<td>File name of the selected item in solution explorer.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Shell.ActiveEditorContentType</td>
|
||||
<td>Content type of the active editor view.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Shell.ActiveEditorFileName</td>
|
||||
<td>File name for the document that belongs to active editor view.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
:ET
|
||||
|
|
@ -58,7 +58,7 @@
|
|||
<li><a href="/new-extensibility-model/inside-the-sdk/extension-anatomy.html">Extension Anatomy</a></li>
|
||||
<li><a href="/new-extensibility-model/inside-the-sdk/activation-constraints.html">Activation Constraints</a></li>
|
||||
<li><a href="/new-extensibility-model/inside-the-sdk/logging.html">Logging Extension Diagnostics</a></li>
|
||||
<li><a href="/new-extensibility-model/inside-the-sdk/packages.html">Packages</a></li>
|
||||
<li><a href="/new-extensibility-model/inside-the-sdk/packages.html">NuGet Packages</a></li>
|
||||
</ul>
|
||||
<li class="parent">
|
||||
<a href="/new-extensibility-model/api/" aria-haspopup="menu">API</a>
|
||||
|
|
@ -72,10 +72,9 @@
|
|||
<li class="parent">
|
||||
<a href="/lsp/" aria-haspopup="menu">Language Server Protocol</a>
|
||||
<ul>
|
||||
|
||||
<li><a href="/lsp/LSPExtensionsSpecification.html">VS Extensions to LSP</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="/api.html">API</a></li>
|
||||
</ul>
|
||||
</nav>
|
||||
<article>
|
||||
|
|
|
|||
|
|
@ -4,4 +4,8 @@ description: A reference for extensibility announcements
|
|||
date: 2021-8-16
|
||||
---
|
||||
|
||||
# Announcements
|
||||
# Announcements
|
||||
Use this page to stay up-to-date on all upcoming extensibility announcements and critical SDK/API updates.
|
||||
|
||||
## August 26, 2021
|
||||
* VSExtensibility site/repository goes public!
|
||||
|
|
@ -172,6 +172,10 @@ main {
|
|||
border-bottom: 1px solid var(--border-color);
|
||||
}
|
||||
|
||||
table, th, td {
|
||||
border: 1px solid grey
|
||||
}
|
||||
|
||||
#menu {
|
||||
font-size: .80em;
|
||||
min-width: fit-content;
|
||||
|
|
|
|||
|
|
@ -0,0 +1,386 @@
|
|||
---
|
||||
title: VS Extensions to LSP Reference
|
||||
description: A reference for extensions to LSP
|
||||
date: 2021-8-16
|
||||
---
|
||||
|
||||
# Visual Studio extensions to the Language Server Protocol
|
||||
|
||||
This document describes the Visual Studio specific extensions to the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/specifications/specification-current/). 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`](#vsdiagnostic) extends [`Diagnostic`](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#diagnostic) adding support for tooltips, sorting, etc.
|
||||
1. Additional methods like [GetProjectContexts](#getprojectcontexts). These are listed in [`VSMethods`](#vsmethods).
|
||||
1. Additional capabilities that a language server can provide to the Visual Studio client. These are defined in [`VSServerCapabilities`](#vsservercapabilities) and can be communicated to the client in the [`InitializeResult.capabilities`](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#initializeResult) field of the [`initialize`](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#initialize) request.
|
||||
1. Additional values for enumerations described in the LSP protocol. For example [`VSDiagnosticTags`](#vsdiagnostictags) extends [`DiagnosticTag`](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#diagnosticTag).
|
||||
|
||||
A .NET implementation of these extensions can be found on [NuGet](https://www.nuget.org/packages/Microsoft.VisualStudio.LanguageServer.Protocol.Extensions).
|
||||
|
||||
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`](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#codeAction) entries of a [`codeAction/resolve`](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#codeAction_resolve) request into [`VSDiagnostic`](#vsdiagnostic) objects even if [`CodeAction.Diagnostics`](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#codeAction) is defined as an array of [`Diagnostic`](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#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](https://docs.microsoft.com/en-us/dotnet/standard/frameworks#how-to-specify-a-target-framework) 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`](#vstextdocumentidentifier) property.
|
||||
|
||||
_Server Capability_
|
||||
|
||||
- property path (optional): [`_vs_projectContextProvider`](#vsservercapabilities)
|
||||
- property type: `boolean`
|
||||
|
||||
_Request_
|
||||
|
||||
- method: `textDocument/_vs_getProjectContexts`
|
||||
- params: [`VSGetProjectContextsParams`](#vsgetprojectcontextsparams)
|
||||
|
||||
_Response_
|
||||
|
||||
- result: [`VSProjectContextList`](#vsprojectcontextlist)
|
||||
|
||||
# Extensions specification
|
||||
|
||||
## VSDiagnostic
|
||||
|
||||
[`VSDiagnostic`](#vsdiagnostic) extends [`Diagnostic`](https://microsoft.github.io/language-server-protocol/specifications/specification-current/) providing additional properties used by Visual Studio.
|
||||
```typescript
|
||||
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`](#vsdiagnosticprojectinformation) represents the project and context in which the [`VSDiagnostic`](#vsdiagnostic) is generated.
|
||||
```typescript
|
||||
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`](#vsdiagnosticrank) represents the rank of a [`VSDiagnostic`](#vsdiagnostic) object.
|
||||
```typescript
|
||||
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`](https://microsoft.github.io/language-server-protocol/specifications/specification-current/) values that are specific to Visual Studio.
|
||||
```typescript
|
||||
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`](#vsgetprojectcontextsparams) represents the parameter that is sent with the 'textDocument/_vs_getProjectContexts' request.
|
||||
```typescript
|
||||
export interface VSGetProjectContextsParams {
|
||||
|
||||
/**
|
||||
* Gets or sets the document for which project contexts are queried.
|
||||
**/
|
||||
_vs_textDocument : TextDocumentItem,
|
||||
}
|
||||
```
|
||||
|
||||
## VSImageId
|
||||
|
||||
[`VSImageId`](#vsimageid) represents the unique identifier for a Visual Studio image asset. The identified is composed by a [`VSImageId._vs_guid`](#vsimageid) and an integer. A list of valid image ids can be retrieved from the [KnownMonikers class](https://docs.microsoft.com/en-us/dotnet/api/microsoft.visualstudio.imaging.knownmonikers) from the Visual Studio SDK.
|
||||
```typescript
|
||||
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`](#vslocation) extends [`Location`](https://microsoft.github.io/language-server-protocol/specifications/specification-current/) providing additional properties used by Visual Studio.
|
||||
```typescript
|
||||
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`](#vsmethods) contains the string values for all Language Server Protocol Visual Studio specific methods.
|
||||
```typescript
|
||||
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`](#vsprojectcontext) represents a project context.
|
||||
```typescript
|
||||
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`](#vsprojectcontextlist) represents the response to the 'textDocument/_vs_getProjectContexts' request.
|
||||
```typescript
|
||||
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`](#vsprojectkind) represents the various kinds of contexts.
|
||||
```typescript
|
||||
export enum VSProjectKind {
|
||||
|
||||
/**
|
||||
* C++ project.
|
||||
**/
|
||||
CPlusPlus = 1,
|
||||
|
||||
/**
|
||||
* C# project.
|
||||
**/
|
||||
CSharp = 2,
|
||||
|
||||
/**
|
||||
* Visual Basic project.
|
||||
**/
|
||||
VisualBasic = 3,
|
||||
}
|
||||
```
|
||||
|
||||
## VSServerCapabilities
|
||||
|
||||
[`VSServerCapabilities`](#vsservercapabilities) extends [`ServerCapabilities`](https://microsoft.github.io/language-server-protocol/specifications/specification-current/) allowing to provide additional capabilities supported by Visual Studio.
|
||||
```typescript
|
||||
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`](#vssymbolinformation) extends [`SymbolInformation`](https://microsoft.github.io/language-server-protocol/specifications/specification-current/) providing additional properties used by Visual Studio.
|
||||
```typescript
|
||||
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`](#vstextdocumentidentifier) extends [`TextDocumentIdentifier`](https://microsoft.github.io/language-server-protocol/specifications/specification-current/) providing additional properties used by Visual Studio.
|
||||
```typescript
|
||||
export interface VSTextDocumentIdentifier extends TextDocumentIdentifier {
|
||||
|
||||
/**
|
||||
* Gets or sets the project context of the text document.
|
||||
**/
|
||||
_vs_projectContext? : VSProjectContext,
|
||||
}
|
||||
```
|
||||
|
|
@ -48,10 +48,10 @@ Following is the list of terms currently supported by expression engine.
|
|||
| Term | Description
|
||||
| -- | -- |
|
||||
| SolutionHasProjectBuildProperty:\<property>=\<regex> | The term is true when solution has a loaded project with the specified build property and property value matches to regex filter provided. |
|
||||
| SolutionHasProjectCapability:\<expression> | True whenever solution has a project with capabilities matching the provided subexpression. An expression can be something like VB | CSharp. |
|
||||
| SolutionHasProjectCapability:\<expression> | True whenever solution has a project with capabilities matching the provided sub-expression. An expression can be something like VB or C#. |
|
||||
| SolutionHasProjectFlavor:\<guid> | True whenever a solution has project that is flavored (aggregated) and has a flavor matching the given project type GUID. |
|
||||
| SolutionState:\<state> | True when solution state matches to provided value, see [solution states](#solution-states) for list of values. |
|
||||
| ProjectAddedItem:\<pattern> | The term is true when a file matching the "pattern" is added to a project in the soluion that is opened. |
|
||||
| ProjectAddedItem:\<pattern> | The term is true when a file matching the "pattern" is added to a project in the solution that is opened. |
|
||||
| ClientContext:\<key>=\<pattern> | True when the provided client context key matches to regular expression. See [client contexts](#client-contexts) for more details. |
|
||||
|
||||
## Solution states
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче