Merge pull request #13947 from tinaschrepfer/dev/tinali/17.14-edits

Dev/tinali/17.14 edits

Author: Stacyrch140

docs/extensibility/visualstudio.extensibility/editor/editor-concepts.md

@@ -14,7 +14,7 @@ ms.subservice: extensibility-integration
 
 This article describes the extensibility object model that represents the Visual Studio editor and the text document that is opened for editing. For an introduction to working with the editor extension functionality, see [Use Visual Studio editor extensibility](editor.md).
 
-The Visual Studio Editor extensibility object model is composed of a few integral parts. This article covers [ITextViewSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextviewsnapshot), [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot), and other abstract representations of the whole document, as well as `Position` and `Span`, which represent location and spans of text, respectively.
+The Visual Studio Editor extensibility object model is composed of a few integral parts. This article covers [ITextViewSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextviewsnapshot), [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot), and other abstract representations of the whole document, as well as [TextPosition](/dotnet/api/microsoft.visualstudio.extensibility.editor.textposition) and [TextRange](/dotnet/api/microsoft.visualstudio.extensibility.editor.textrange), which represent locations and spans of text, respectively.
 
 ## ITextViewSnapshot
 
@@ -36,25 +36,33 @@ If you're familiar with legacy Visual Studio extensions, [ITextDocumentSnapshot]
 
 Best Practices:
 
-- You can use Position and Span to represent substrings in the document without expending resources copying or allocating strings. Most APIs operate in terms of these primitives.
+- You can use Position and Range to represent substrings in the document without expending resources copying or allocating strings. Most APIs operate in terms of these primitives.
 - You can use the indexer syntax, `textDocument[0]`, to read character by character in the document without copying it to a string.
-- If you must create a string such as for use as a dictionary key, use the overload that takes a `Span`, to avoid creating a large throwaway string from the entire line or document.
+- If you must create a string such as for use as a dictionary key, use the overload that takes a `Range`, to avoid creating a large throwaway string from the entire line or document.
 - Avoid assuming lines or documents will be short. Many languages minify into huge lines or consume very large files
-- - [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot) references large data structures that may consume memory if an old enough version is stored. Best practice is to periodically update positions and spans that you're storing long term to the latest document version via their `TranslateTo()` method so the old `ITextDocumentSnapshot` version can be garbage collected.
+- - [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot) references large data structures that may consume memory if an old enough version is stored. Best practice is to periodically update positions and ranges that you're storing long term to the latest document version via their `TranslateTo()` method so the old `ITextDocumentSnapshot` version can be garbage collected.
 
 ## Position
 
-Represents a position within the text document. As opposed to `int` positions, the Position type is aware of the [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot) it came from and supports `GetChar()` to directly get the character at that point.
+[TextPosition](/dotnet/api/microsoft.visualstudio.extensibility.editor.textposition) represents a position within the text document. As opposed to `int` positions, the `TextPosition` type is aware of the [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot) it came from and supports `GetChar()` to directly get the character at that point.
 
-If you're familiar with legacy Visual Studio extensions, Position is almost the same as [SnapshotPoint](/dotnet/api/microsoft.visualstudio.text.snapshotpoint) and supports most of the same methods.
+If you're familiar with legacy Visual Studio extensions, `TextPosition` is almost the same as [SnapshotPoint](/dotnet/api/microsoft.visualstudio.text.snapshotpoint) and supports most of the same methods.
 
-## Span
+## Range
 
-Represents a contiguous substring of characters within an [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot). As opposed to a string created with `string.Substring()` or `ITextDocumentSnapshot.CopyToString()`, creating a Span doesn't require any allocations or additional memory. You can later call `Span.GetText()` to realize it into a string in a deferred fashion.
+[TextRange](/dotnet/api/microsoft.visualstudio.extensibility.editor.textrange) represents a contiguous substring of characters within an [ITextDocumentSnapshot](/dotnet/api/microsoft.visualstudio.extensibility.editor.itextdocumentsnapshot). As opposed to a string created with `string.Substring()` or `ITextDocumentSnapshot.CopyToString()`, creating a `TextRange` doesn't require any allocations or additional memory. You can later call [CopyToString()](/dotnet/api/microsoft.visualstudio.extensibility.editor.textextensions.copytostring) to realize it into a string in a deferred fashion.
 
-If you're familiar with legacy Visual Studio extensions, `Position` is almost the same as
+If you're familiar with legacy Visual Studio extensions, `TextRange` is almost the same as
 [SnapshotSpan](/dotnet/api/microsoft.visualstudio.text.snapshotSpan) and supports most of the same methods.
 
+## Tracking modes
+
+`TextPosition` and `TextRange` are associated with a specific `ITextDocumentSnapshot`: the state of the document at a specific time. Such positions and ranges can be translated to a different snapshot using the `TranslateTo` methods. Such translation takes in account any text added or removed before, after (or, in the case of ranges, in the middle) the position or range. When any of such edits happen exactly at the position or exactly at the edge of the range, [TextPositionTrackingMode](/dotnet/api/microsoft.visualstudio.extensibility.editor.textpositiontrackingmode) and [TextRangeTrackingMode](/dotnet/api/microsoft.visualstudio.extensibility.editor.textrangetrackingmode) are used to specify how the translation should behave.
+
+## Tag
+
+[Taggers](./walkthroughs/taggers.md) are used to associate data (a [tag](/dotnet/api/microsoft.visualstudio.extensibility.editor.itag)) with spans of text, such data is consumed by other Visual Studio features (E.g., [CodeLens](./walkthroughs/codelens.md), [classification](./walkthroughs/classification.md), etc.).
+
 ## Related content
 
 Review sample code for a simple editor-based extension:

docs/extensibility/visualstudio.extensibility/editor/editor.md

@@ -18,7 +18,7 @@ The Visual Studio editor generally refers to the functionality of editing text f
 
 The editor object model is described at [Editor concepts](editor-concepts.md).
 
-The following sections summarize the high level editor extensibility scenarios that VisualStudio.Extensibility supports. However, because each of these scenarios are rich in concepts and APIs, a separate, more detailed section will be linked to provide a more in-depth explanation of the APIs and how to use them.
+The following sections summarize the high level editor extensibility scenarios that VisualStudio.Extensibility supports. However, because each of these scenarios is rich in concepts and APIs, a separate, more detailed section will be linked to provide a more in-depth explanation of the APIs and how to use them.
 
 ## Reading text and observing changes in the editor
 The most fundamental extensibility point for the Visual Studio editor is to manipulate text, either reading the text in the editor, or editing the text. These scenarios are core to any editor based extensions. For example, in order to provide diagnostics information such as warnings or errors, the extension has to read the code that's in the editor, and then interpret it. An extension also needs a way to detect when the text in the editor is being changed, or if there's a new file being opened, or an open file is being closed. 
@@ -36,15 +36,15 @@ Besides manipulating text, extensions can also plugin into many features in the
 ### Text view margin
 Extensions can contribute new text view margins to the Visual Studio editor. A text view margin is a rectangular UI control attached to a text view on one of its four sides. These UI controls offer additional information at a glance, which allows developers to stay productive working in the editor. Many of the most popular features in the Visual Studio editor utilize text view margins, like the zoom control, breakpoint indicator, line number indicator, and many more.
 
-For detailed walkthough of how to customize text view margin with your extension, refer to [Extending Visual Studio editor with a new margin](./walkthroughs/textview-margin.md)
+For detailed walkthrough of how to customize text view margin with your extension, refer to [Extending Visual Studio editor with a new margin](./walkthroughs/textview-margin.md)
 
 ### CodeLens
 Extensions can contribute new CodeLenses to the Visual Studio editor. A CodeLens 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. Some common CodeLenses include code reference CodeLens, which provide information on all the different parts of the code that reference a particular block of code, or the code history CodeLens, which provide information on how the particular block of code has been changed in source control.
 
 For detailed walkthrough of how to provide your own CodeLens with your extension, refer to [Extending Visual Studio editor with a new CodeLens](./walkthroughs/codelens.md)
 
 ### Taggers
-Extensions can contribute new taggers to the Visual Studio editor. Taggers are used to associate data with spans of text, such data is consumed by other Visual Studio features (E.g., CodeLens).
+Extensions can contribute new taggers to the Visual Studio editor. Taggers are used to associate data with ranges of text, such data is consumed by other Visual Studio features (E.g., [CodeLens](./walkthroughs/codelens.md), [classification](./walkthroughs/classification.md), etc.).
 
 For detailed walkthrough of how to provide your own taggers with your extension, refer to [Extending Visual Studio editor with a new tagger](./walkthroughs/taggers.md)
 

docs/extensibility/visualstudio.extensibility/editor/walkthroughs/classification.md

@@ -0,0 +1,80 @@
+---
+title: Customizing classification in the editor
+description: A walkthrough of how to provide your own classification in the Visual Studio editor using extensions
+ms.date: 4/23/2025
+ms.topic: conceptual
+ms.author: maprospe
+monikerRange: ">=vs-2022"
+author: tinaschrepfer
+manager: mijacobs
+ms.subservice: extensibility-integration
+---
+
+# Extending Visual Studio editor with a new classification tagger
+
+A Visual Studio extension can classify a document's syntax allowing for
+the text to be colorized accordingly, which is achieved by contributing
+a tagger that returns `ClassificationTag` values.
+
+A detailed description of how to provide a tagger can be found in the
+[Extending Visual Studio editor with a new tagger](./taggers.md) article.
+
+To provide classification, we first implement a tagger provider and a
+tagger:
+
+```cs
+[VisualStudioContribution]
+internal class MyClassificationTaggerProvider :
+    ExtensionPart,
+    ITextViewTaggerProvider<ClassificationTag>,
+    ITextViewChangedListener
+{
+    ...
+```
+
+```cs
+internal class MyClassificationTagger :
+    TextViewTagger<ClassificationTag>
+{
+    ...
+```
+
+Since we want the document colorization to appear as instantly as possible,
+the generation of taggers needs to be as fast as possible. [This](./taggers.md) article 
+stresses the importance of:
+- only generating tags for the requested document portion (or a small
+superset of it), not the whole document;
+- avoiding parsing the whole document in order to generate tags.
+
+Once the tagger structure is ready and the syntax parsing for the specific
+file format is implemented, the tagger can provide text classification, by creating `ClassificationTag` values using the available
+`ClassificationType` know values, and calling `UpdateTagsAsync`.
+
+```cs
+List<TaggedTrackingTextRange<ClassificationTag>> tags = new();
+List<TextRange> ranges = new();
+
+...
+
+ranges.Add(new(document, lineStart, lineLength));
+tags.Add(
+    new TaggedTrackingTextRange<ClassificationTag>(
+        new TrackingTextRange(
+            document,
+            tagStartPosition,
+            tagLength,
+            TextRangeTrackingMode.ExtendNone),
+        new ClassificationTag(ClassificationType.KnownValues.Operator)));
+
+...
+
+await this.UpdateTagsAsync(ranges, tags, CancellationToken.None);
+```
+
+At this time, VisualStudio.Extensibility doesn't support defining text colors
+for new classification types yet, so we must use existing classification types
+(`ClassificationType.KnownValues`).
+
+[VisualStudio.Extensibility in-proc extension](../../get-started/in-proc-extensions.md), can use [ClassificationTypeDefinition](/dotnet/api/microsoft.visualstudio.text.classification.classificationtypedefinition)
+to define new classification types. Their name can be referenced using
+`ClassificationType.Custom`.

docs/extensibility/visualstudio.extensibility/editor/walkthroughs/taggers.md

@@ -11,12 +11,13 @@ ms.subservice: extensibility-integration
 ---
 
 # Extending Visual Studio editor with a new tagger
-Extensions can contribute new taggers to Visual Studio. Taggers are used to associate data with spans of text. The data provided by taggers are consumed by other Visual Studio features (for example, [CodeLens](./codelens.md)).
+Extensions can contribute new taggers to Visual Studio. Taggers are used to associate data with ranges of text. The data provided by taggers are consumed by other Visual Studio features (for example, [CodeLens](./codelens.md)).
 
 VisualStudio.Extensibility only supports tag types that are provided by the [Microsoft.VisualStudio.Extensibility](https://www.nuget.org/packages/Microsoft.VisualStudio.Extensibility) package and implement the `Microsoft.VisualStudio.Extensibility.Editor.ITag` interface:
 
 - `CodeLensTag` can be used together with an [ICodeLensProvider](./codelens.md) to add Code Lenses to documents
 - `TextMarkerTag` can be used to highlight portions of documents. VisualStudio.Extensibility doesn't support defining new Text Marker styles yet, so only styles that are built into Visual Studio or provided by a VSSDK extension can be used for now (a [VisualStudio.Extensibility in-proc extension](../../get-started/in-proc-extensions.md) can create Text Marker styles with an `[Export(typeof(EditorFormatDefinition))]`).
+- `ClassificationTag` can be used to classify a document's syntax allowing for the text to be colorized accordingly.
 
 To generate tags, the extension must contribute an extension part that implements `ITextViewTaggerProvider<>` for the type (or types) of tags provided. The extension part also needs to implement `ITextViewChangedListener` to react to document changes:
 
@@ -142,7 +143,7 @@ internal class MarkdownCodeLensTagger : TextViewTagger<CodeLensTag>
 
 Both the `TextViewChangedAsync` and `RequestTagsAsync` methods, should call `UpdateTagsAsync` providing the ranges that tags are being updated for and the new tags themselves. The `TextViewTagger<>` base class holds a cache of previously generated tags, calling `UpdateTagsAsync` invalidates all existing tags for the provided ranges and replaces them with the newly provided ones.
 
-While generating tags for the entire document is a possible strategy, it is preferrable to only generate tags for the requested ranges (in `RequestTagsAsync`) and the edited ranges (in `TextViewChangedAsync`). It is also common to have to extend such ranges to cover meaningful spans of the document syntax (for example, entire statements, entire lines of code, etc.).
+While generating tags for the entire document is a possible strategy, it is preferable to only generate tags for the requested ranges (in `RequestTagsAsync`) and the edited ranges (in `TextViewChangedAsync`). It is also common to have to extend such ranges to cover meaningful spans of the document syntax (for example, entire statements, entire lines of code, etc.).
 
 Handling text view changes in particular requires some additional code. The following code snippet is an example:
 

docs/extensibility/visualstudio.extensibility/toc.yml

@@ -46,7 +46,9 @@ items:
       - name: Extending Visual Studio editor with a new CodeLens
         href: ./editor/walkthroughs/codelens.md
       - name: Extending Visual Studio editor with a new tagger
-        href: ./editor/walkthroughs/taggers.md  
+        href: ./editor/walkthroughs/taggers.md
+      - name: Extending Visual Studio editor with new classification tagger
+        href: ./editor/walkthroughs/classification.md
   - name: Editor concepts
     href: ./editor/editor-concepts.md
   - name: Editor RPC