Merge pull request #10490 from MicrosoftDocs/main638672474446769190sync_temp

Repo sync for protected branch

Author: Court72

docs/extensibility/visualstudio.extensibility/diagnostics/media/image-1.png

@@ -11,7 +11,7 @@ ms.date: 05/09/2024
 
 # Overview
 
-The VisualStudio.Extensibility Diagnostics Explorer extension is designed to help debug VisualStudio.Extensibility extensions while developing them. The target audience for this extension is extension authors, not extension consumers. This extension provides an interface for inspecting the extensibility points that extensions are interacting with, and what configuration objects extensions are providing to the IDE, and the metadata of those configuration objects. 
+The VisualStudio.Extensibility Diagnostics Explorer extension is designed to help debug VisualStudio.Extensibility extensions while developing them. The target audience for this extension is extension authors, not extension consumers. This extension provides an interface for inspecting the extensibility points that extensions are interacting with, and what configuration objects extensions are providing to the IDE, and the metadata of those configuration objects.
 
 ## Get Started
 
@@ -22,7 +22,7 @@ Follow these instructions to install, launch, and configure the Diagsnotics Expl
 You can get the Diagnostics Explorer either directly through the Extension Manager in Visual Studio, or from the Visual Studio Marketplace [here](https://aka.ms/VisualStudio.Extensibility/DiagnosticsExplorer).
 
 > [!NOTE]
-> The VisualStudio.Extensibility Diagnostics Explorer extension is compatable with Visual Studio 2022 17.10 and higher.
+> The VisualStudio.Extensibility Diagnostics Explorer extension is compatible with Visual Studio 2022 17.12 and higher.
 
 ### Open the Diagnostics Explorer in Visual Studio
 
@@ -38,9 +38,7 @@ The Diagnostics Explorer is configured to collect relevant diagnostic data from
 
 ## Diagnostics Pages
 
-The left-hand panel of the Diagnostics Explorer tool window contains a list different *feature pages*. These pages correspond to the extensible features for which you can find diagnostic information about the components and configurations that Visual Studio discovered from your extensions. For example, you can select **Commands** to view diagnostics related to your commands, command sets, menus and toolbars, placements, and more.
-
-Also in the list are two special pages that aren't directly related to any components in your extension: [**Events**](#events-page), a live viewer for extensibility-related events, and [**Activation Constraints**](#activation-constraints-page), which shows relevant IDE state to help you craft your activation constraints.
+The left-hand panel of the Diagnostics Explorer tool window contains a list different *diagnostics pages*. There are two types of diagnostics pages - extensible features and extensibility infrastructure. Extensible features pages provide diagnostic information about a specific extensible component within Visual Studio, like commands. Extensibility infrastructure pages provide diagnostic information that's relevant regardless of which extensibility points your extension plugs into. The [**Events**](#events-page) page, a live viewer for extensibility-related events, and the [**Client Contexts**](#client-contexts-page) page, which shows relevant IDE state to help you craft your activation constraints, are the two extensibility infrastructure pages.
 
 ![Screenshot of the left hand panel of the tool window.](./media/image-2.png)
 
@@ -64,7 +62,9 @@ Some cells in the DataGrid display **[Click to Expand]**. This message means tha
 
 ![Screenshot of the "Click to Expand" modal dialog."](./media/image-6.png)
 
-### Events Page
+### Extensible Infrastructure Pages
+
+#### Events Page
 
 The events page shows you when "something happens" in the IDE. Each event appears as a new row in the DataGrid, along with any properties related to that event. For example, when a command is executed, a **Commands - Executing** event appears in the view showing the ID of the extension that the command belongs to and the ID of the command that was executed.
 
@@ -76,29 +76,29 @@ Clicking the **Clear All** button deletes all the events currently shown in the
 
 ![Screenshot of the Events page.](./media/image-7.png)
 
-#### Column Descriptions
+##### Column Descriptions
 
-##### Extension ID
+###### Extension ID
 
 The **Extension Id** column shows the ID of the extension that the instance of the event is related to. It's possible for this cell to be empty for some events if they don't belong to a specific extension but instead apply to the IDE as a whole.
 
-##### Item ID
+###### Item ID
 
 The **Item Id** column shows the ID of the extension item that the instance of the event is related to. For example, the **Item Id** for the **Commands - Executing** event would be the ID of the command that was executed.
 
-##### Properties
+###### Properties
 
 The **Properties** column shows the set of properties related to that instance of the event that could be displayed in a single cell in a DataGrid. More verbose properties would only be visible from the **More Info** dialog, or by changing the **Event** ComboBox to the name of the specific event that you're interested in.
 
-##### More Info
+###### More Info
 
 The **More Info** column displays more verbose metadata related to an event. Clicking a cell in this column opens a modal dialog containing all of the metadata related to the event represented by that row.
 
 ![Screenshot of the More Info dialog.](./media/image-8.png)
 
-### Activation Constraints Page
+#### Client Contexts Page
 
-The activation constraints page shows the state of various properties related to the IDE itself. The **Context** ComboBox changes the data in the view to either show all of the activation constraints related to the currently selected item in the **Acitvation Constraints** ComboBox, or a log of all the times these properties changed since the tool window was opened. When the **Events** context is selected, the **Clear All** button can be used to delete all the events currently being displayed in the view.
+The client contexts page shows the state of various properties related to the IDE itself. The **Context** ComboBox changes the data in the view to either show all of the activation constraints related to the currently selected item in the **Client Contexts** ComboBox, or a log of all the times these properties changed since the tool window was opened. When the **Events** context is selected, the **Clear All** button can be used to delete all the events currently being displayed in the view.
 
 ![Screenshot of the Activation Constraint's Current State page.](./media/image-9.png)
 

docs/extensibility/visualstudio.extensibility/diagnostics/media/image-10.png

@@ -22,6 +22,7 @@ For the initial release of the new Visual Studio extensibility model, only the f
 - Performing text edits and selection/caret changes.
 - Defining new document types.
 - Extending text views with new text view margins.
+- Extending text views with new Code Lenses.
 
 The Visual Studio editor generally refers to the functionality of editing text files, known as documents, of any type. Individual files may be opened for editing, and the open editor window is referred to as a `TextView`.
 
@@ -222,6 +223,20 @@ To avoid misplaced edits, edits from editor extensions are applied as follows:
 1. Edit requests are sent to Visual Studio IDE, where it succeeds only if the object being mutated hasn't changed since the version the request was made one. If the document has changed, the change may be rejected, requiring the extension to retry on newer version. Outcome of mutation operation is stored in `result`.
 1. Edits are applied atomically, meaning without interruption from other executing threads. The best practice is to do all changes that should occur within a narrow time frame into a single `EditAsync()` call, to reduce the likelihood of unexpected behavior arising from user edits, or language service actions that occur between edits (for example, extension edits getting interleaved with Roslyn C# moving the caret).
 
+## Changing caret position or selecting text from an extension
+
+Editing text document from an extension implicitly affects caret position. For example, inserting some text at the caret will move the caret to the end of the inserted text. Extensions can also use [`ITextViewSnapshot.AsEditable().SetSelections()`](/dotnet/api/microsoft.visualstudio.text.itextvieweditor.setselections) to set the caret explicitly to a different position or make text selections. To illustrate, the following code would insert some text, but keep the caret at the original position:
+
+```csharp
+await this.Extensibility.Editor().EditAsync(batch =>
+{
+    var caret = textView.Selection.Extent.Start;
+    textView.Document.AsEditable(batch).Replace(textView.Selection.Extent, newGuidString);
+    textView.AsEditable(batch).SetSelections([new Selection(activePosition: caret, anchorPosition: caret, insertionPosition: caret)]);
+},
+cancellationToken);
+```
+
 ### Asynchronous execution
 
 [ITextViewSnapshot.GetTextDocumentAsync](/visualstudio/extensibility/visualstudio.extensibility/editor/editor-concepts?view=vs-2022#itextviewsnapshot) opens a copy of the text document in the Visual Studio extension. Since extensions run in a separate process, all extension interactions are asynchronous, cooperative, and have some caveats:
@@ -283,6 +298,97 @@ For more information, see [Word Count Margin Sample](https://github.com/Microsof
 
 Vertical text view margins whose content needs to be aligned with text view lines are not yet supported.
 
+## Extending Visual Studio editor with a new Code Lens
+
+Extensions can contribute new Code Lenses to the Visual Studio editor. A Code Lens is a visual indicator displayed above lines of text providing actionable contextual information such as number of references to a code element, results of the last unit test run or actions to run/debug a unit test.
+
+### Text view Code Lens
+Text view Code Lens provide text-based information to segments of code. This is the simplest forms of Code Lens. The following concepts illustrate how to create a text view Code Lens:
+- [`ICodeLensProvider`](/dotnet/api/microsoft.visualstudio.extensibility.editor.icodelensprovider) interface is the main interface to implement. Your implementation of this interface will define when your Code Lens will be activated, and which segments of code your Code Lens will be applicable to, and how it will be displayed.
+- Within your implementation of [`ICodeLensProvider`](/dotnet/api/microsoft.visualstudio.extensibility.editor.icodelensprovider), you will need to define when the Code Lens should be activated by implementing [`CodeLensProviderConfiguration`](/dotnet/api/microsoft.visualstudio.extensibility.editor.codelensproviderconfiguration).
+- You will also need to implement the [`TryCreateCodeLensAsync`](/dotnet/api/microsoft.visualstudio.extensibility.editor.icodelensprovider.trycreatecodelensasync) method. This method will be invoked when your Code Lens is activated. In this method, you can define how you want your Code Lens to be displayed and when it should be displayed. This method returns an instance of [`CodeLens`](/dotnet/api/microsoft.visualstudio.extensibility.editor.codelens).
+- You will need to create your own sub-class of [`CodeLens`](/dotnet/api/microsoft.visualstudio.extensibility.editor.codelens), where you get to define how you want your display text to appear through the [`GetLabelAsync`](/dotnet/api/microsoft.visualstudio.extensibility.editor.codelens.getlabelasync) method. This method returns an instance of [`CodeLensLabel`](/dotnet/api/microsoft.visualstudio.extensibility.editor.codelenslabel), which you can use to configure the text, tooltip, and an optional icon.
+
+### Invokable Code Lens
+Invokable Code Lens allows extensions to perform some action (e.g. run a unit test) when user clicks on the Code Lens. Extensions can contribute invokable Code Lens by implementing [`InvokableCodeLens`](/dotnet/api/microsoft.visualstudio.extensibility.editor.invokablecodelens), which derives from [`CodeLens`](/dotnet/api/microsoft.visualstudio.extensibility.editor.codelens).
+
+### Visual Code Lens
+Visual Code Lens allows extensions to provide custom UI, like a list of references to a method, to be displayed in a popup above the Code Lens when user clicks on the Code Lens. Extensions can contribute visual Code Lens by implementing [`VisualCodeLens`](/dotnet/api/microsoft.visualstudio.extensibility.editor.visualcodelens), which derives from [`CodeLens`](/dotnet/api/microsoft.visualstudio.extensibility.editor.codelens). Similar to text view margins, because extensions in VisualStudio.Extensibility might be out-of-process from the Visual Studio, visual Code Lenses provide UI by creating a [`RemoteUserControl`](./../inside-the-sdk/remote-ui.md) and the corresponding data template for that control. While there are some simple examples below, we recommend reading the [Remote UI documentation](./../inside-the-sdk/remote-ui.md) when creating visual Code Lens' UI content.
+
+The sample code below demonstrates how to create a text view Code Lens and an invokable Code Lens:
+
+```csharp
+public TextViewExtensionConfiguration TextViewExtensionConfiguration => new()
+{
+    AppliesTo = new[]
+    {
+        DocumentFilter.FromDocumentType(DocumentType.KnownValues.Code),
+    },
+};
+
+public CodeLensProviderConfiguration CodeLensProviderConfiguration =>
+    new("CodeLens Sample Provider") {};
+
+public Task<CodeLens?> TryCreateCodeLensAsync(CodeElement codeElement, CodeElementContext codeElementContext, CancellationToken token)
+{
+    if (codeElement.Kind == CodeElementKind.KnownValues.Method)
+    {
+        return Task.FromResult<CodeLens?>(new ClickableCodeLens(codeElement, this.Extensibility));
+    }
+    
+    return Task.FromResult<CodeLens?>(new WordCountCodeLens(codeElement, codeElementContext, this.Extensibility, this));
+}
+
+...
+
+public class ClickableCodeLens : InvokableCodeLens
+{
+    public override Task ExecuteAsync(CodeElementContext codeElementContext, IClientContext clientContext, CancellationToken cancelToken)
+    {
+        this.clickCount++;
+        this.Invalidate();
+        return Task.CompletedTask;
+    }
+
+    public override Task<CodeLensLabel> GetLabelAsync(CodeElementContext codeElementContext, CancellationToken token)
+    {
+        return Task.FromResult(new CodeLensLabel()
+        {
+            Text = this.clickCount == 0 ? "Click me" : $"Clicked {this.clickCount} times",
+            Tooltip = "Invokable CodeLens Sample Tooltip",
+        });
+    }
+}
+
+public class WordCountCodeLens : VisualCodeLens
+{   
+    public override Task<IRemoteUserControl> GetVisualizationAsync(CodeElementContext codeElementContext, IClientContext clientContext, CancellationToken token)
+    {
+        return Task.FromResult<IRemoteUserControl>(new WordCountCodeLensVisual(this.wordCountData));
+    }
+
+    public override Task<CodeLensLabel> GetLabelAsync(CodeElementContext codeElementContext, CancellationToken token)
+    {
+        this.wordCountData.WordCount = CountWords(codeElementContext.Range);
+        return Task.FromResult(new CodeLensLabel()
+        {
+            Text = $"Words: {this.wordCountData.WordCount}",
+            Tooltip = "Number of words in this code element",
+        });
+    }
+}
+```
+
+In addition to configuring Code Lens provider display name, Code Lens providers can also configure priority of their Code Lens. The priority value is used to determine the relative ordering of your Code Lens respective to other Code Lenses. This is done through the [`Priority`](/dotnet/api/microsoft.visualstudio.extensibility.editor.codelensproviderconfiguration.priority) property in the [`CodeLensProviderConfiguration`](/dotnet/api/microsoft.visualstudio.extensibility.editor.codelensproviderconfiguration) object.
+
+Code Lenses typically visualize some data related to the text view. For example, they might want to display the number of references to a method. To do so, your Code Lens provider should also [listen to text view events](#add-a-text-view-listener) to react to opening, closing of text views and user typing.
+
+Visual Studio only creates one instance of your Code Lens provider regardless of how many applicable text views a user opens. This means that if your Code Lens needs to maintain state, you need to ensure your Code Lens provider has a way to keep the state of currently open text views.
+
+For more information, see [Code Lens Sample](https://github.com/Microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/CodeLensSample/).
+
+*Contributing Code Lenses to new documents types (or existing document types not supporting Code Lens) is not yet supported.*
+
 ## Related content
 
 Learn about the editor interfaces and types at [Editor concepts](editor-concepts.md).