Merge pull request #6 from maiak/dev/mapropse/inside_the_sdk

Update to Inside the Sdk topics

Author: maiak

docs/extensibility/visualstudio.extensibility/inside-the-sdk/activation-constraints.md

@@ -25,13 +25,13 @@ Multiple activation constraints can be combined together using the [`And`](/dotn
 In the following example, the command configuration property `EnabledWhen` defines when the command is in the enabled state. The `ClientContext` method is one of the activation constraint factory methods. It generates the activation constraint, given the two arguments, a string and regular expression pattern to match against that string. Therefore, the following code indicates that a command is enabled when the user has selected a file with one of those extensions.
 
 ```csharp
-public override CommandConfiguration CommandConfiguration => new("My command")
+public override CommandConfiguration CommandConfiguration => new("%My command.DisplayName%")
 {
     EnabledWhen = ActivationConstraint.ClientContext(ClientContextKey.Shell.ActiveSelectionFileName, @"\.(jpg|jpeg|txt)$"),
 };
 ```
 
-The `ClientContextKey` class provides the range of IDE state information that you can test against; for a table of values, see [Client context keys](#client-context-keys).
+The [`ClientContextKey`](/dotnet/api/microsoft.visualstudio.extensibility.clientcontextkey) class provides the range of IDE state information that you can test against; for a table of values, see [Client context keys](#client-context-keys).
 
 The following example shows how to combine multiple constraints:
 
@@ -51,67 +51,46 @@ EnabledWhen =
 
 ## Activation constraint properties
 
-Currently, what you can control with activation constraints is the loading of an extension, and the enabled or visible state of a command. The configuration types contain property of type `ActivationConstraint`, typically with a `When` suffix that implies that something activates when the specified conditions are satisfied. The following properties are of type `ActivationConstraint`:
-
-| Property | Description |
-| - | - |
-| `ExtensionConfiguration.LoadedWhen` | Controls when is the extension loaded. |
-| `CommandConfiguration.EnabledWhen` | Controls when the command is enabled (becomes callable). A command that isn't enabled might appear as a grayed out UI item. |
-| `CommandConfiguration.VisibleWhen` | Controls when a command is visible in the IDE. For example, when the menu item or command button appears in the UI. |
+Activation constraints can be used to configure a variety of VisualStudio.Extensibility functionalities, including the [loading of an extension](/dotnet/api/microsoft.visualstudio.extensibility.extensionconfiguration.loadedwhen), and the [enabled](/dotnet/api/microsoft.visualstudio.extensibility.commands.commandconfiguration.enabledwhen) or [visible](/dotnet/api/microsoft.visualstudio.extensibility.commands.commandconfiguration.visiblewhen) state of a command. The configuration types contain property of type `ActivationConstraint`, typically with a `When` suffix that implies that something activates when the specified conditions are satisfied.
 
 ## Activation constraint factory methods
 
 This section shows the list of currently supported activation constraints. Each entry on the list is a factory method on the `ActivationConstraint` type.
 
 | Term | Description |
 | -- | -- |
-| [`SolutionHasProjectCapability`](/dotnet/api/microsoft.visualstudio.extensibility.activationconstraint.solutionhasprojectcapability)(\<expression>=[`ProjectCapability`](/dotnet/api/microsoft.visualstudio.extensibility.projectcapability) | True whenever solution has a project with capabilities matching the provided subexpression. An expression can be something like `VB | CSharp`. For more about project capabilities, see [Project query API overview](../project/project.md). |
-| [`SolutionState`](/dotnet/api/microsoft.visualstudio.extensibility.activationconstraint.solutionstate)(\<state>=[`SolutionState`](/dotnet/api/microsoft.visualstudio.extensibility.solutionstate) | True when solution state matches the provided value, see [solution states](#solution-states) for list of values. |
-| [`ProjectAddedItem`](/dotnet/api/microsoft.visualstudio.extensibility.activationconstraint.projectaddeditem)(\<pattern>=\<regex>) | The term is true when a file matching the "pattern" is added to a project in the solution that is opened. |
 | [`ClientContext`](/dotnet/api/microsoft.visualstudio.extensibility.activationconstraint.clientcontext)(\<key>=[`ClientContextKey`](/dotnet/api/microsoft.visualstudio.extensibility.clientcontextkey), \<pattern>=\<regex>) | True when the provided client context key matches to regular expression. See [client context keys](#client-context-keys). |
+| [`ActiveProjectCapability`](/dotnet/api/microsoft.visualstudio.extensibility.activationconstraint.activeprojectcapability)(\<expression>=[`ProjectCapability`](/dotnet/api/microsoft.visualstudio.extensibility.projectcapability)) | True whenever solution has a project with capabilities matching the provided subexpression. An expression can be something like `VB | CSharp`. For more about project capabilities, see [Project query API overview](../project/project.md). |
+| [`ProjectAddedItem`](/dotnet/api/microsoft.visualstudio.extensibility.activationconstraint.projectaddeditem)(\<pattern>=\<regex>) | The term is true when a file matching the "pattern" is added to a project in the solution that is opened. |
+| [`SolutionHasProjectCapability`](/dotnet/api/microsoft.visualstudio.extensibility.activationconstraint.solutionhasprojectcapability)(\<expression>=[`ProjectCapability`](/dotnet/api/microsoft.visualstudio.extensibility.projectcapability)) | True whenever solution has a project with capabilities matching the provided subexpression. An expression can be something like `VB | CSharp`. For more about project capabilities, see [Project query API overview](../project/project.md). |
+| [`SolutionState`](/dotnet/api/microsoft.visualstudio.extensibility.activationconstraint.solutionstate)(\<state>=[`SolutionState`](/dotnet/api/microsoft.visualstudio.extensibility.solutionstate)) | True when solution state matches the provided value, see [solution states](#solution-states) for list of values. |
 
 For compatibility reasons, the following legacy activation constraints are also supported:
 
 | Term | Description |
 | -- | -- |
+| [`ActiveProjectBuildProperty`](/dotnet/api/microsoft.visualstudio.extensibility.activationconstraint.activeprojectbuildproperty)(\<property>=\<regex>) | The term is true when the selected project has the specified build property and the property value matches the regex pattern provided. |
+| [`ActiveProjectFlavor`](/dotnet/api/microsoft.visualstudio.extensibility.activationconstraint.activeprojectflavor)(\<guid>) | True whenever the selected project has a flavor matching the given project type GUID. |
 | [`SolutionHasProjectBuildProperty`](/dotnet/api/microsoft.visualstudio.extensibility.activationconstraint.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. |
 | [`SolutionHasProjectFlavor`](/dotnet/api/microsoft.visualstudio.extensibility.activationconstraint.solutionhasprojectflavor)(\<guid>) | True whenever a solution has project that is flavored (aggregated) and has a flavor matching the given project type GUID. |
 
 ## Solution states
 
-The solution state refers to the state of the solution and its projects, whether a solution is loaded, whether it has zero, one, or multiple projects, and whether it is building.
-
-The following table shows the possible solution states:
-
-| State | Description |
-| -- | -- |
-| NoSolution | No solution loaded. |
-| Exists | A solution is opened but may be in loaded or loading state. |
-| FullyLoaded | A solution is opened and fully loaded. |
-| Empty | Solution contains no projects but may contain solution items. |
-| SingleProject | Solution contains a single project. |
-| MultipleProject | Solution contains multiple projects. |
-| Building | Solution is building. |
+The [solution state](/dotnet/api/microsoft.visualstudio.extensibility.solutionstate) refers to the state of the solution and its projects, whether a solution is loaded, whether it has zero, one, or multiple projects, and whether it is building.
 
 Activation constraints that correspond to solution states can be combined in the same way as any other activation constraints. For example, you can combine an activation constraint that specifies a `FullyLoaded` solution and a `SingleProject` solution to capture single-project solutions when they are fully loaded.
 
 ```csharp
-this.EnabledWhen = And(ActivationConstraint.SolutionState(SolutionState.SingleProject), ActivationConstraint.SolutionState(SolutionState.FullyLoaded);
+this.EnabledWhen = ActivationConstraint.And(
+    ActivationConstraint.SolutionState(SolutionState.SingleProject),
+    ActivationConstraint.SolutionState(SolutionState.FullyLoaded));
 ```
 
 ## Client context keys
 
 Activation rules can also utilize the [client context](extension-anatomy.md#client-context) contents as parts of its expression.
 
-Currently, the client context is limited to a small set of values in IDE state:
-
-| Context key | Definition |
-| -- | -- |
-| Shell.ActiveSelectionUri | Full URI for the selected item in solution explorer. |
-| Shell.ActiveSelectionPath | Full path for the selected item in solution explorer. |
-| Shell.ActiveSelectionFileName | File name of the selected item in solution explorer. |
-| Shell.ActiveEditorContentType | Content type of the active editor view. |
-| Shell.ActiveEditorFileName | File name for the document that belongs to active editor view. |
+Currently, the client context is limited to a [small set of values](/dotnet/api/microsoft.visualstudio.extensibility.clientcontextkey.shell#properties) in IDE state.
 
 ## Next steps
 

docs/extensibility/visualstudio.extensibility/inside-the-sdk/advanced-remote-ui.md

@@ -104,7 +104,7 @@ internal class MyToolWindowData
     }
 
     [DataMember]
-    public ObservableCollection<MyColor> Colors { get; } = new();
+    public ObservableList<MyColor> Colors { get; } = new();
 
     [DataMember]
     public AsyncCommand AddColorCommand { get; }
@@ -130,7 +130,7 @@ There are just a few noteworthy things in this code:
 
 1. `MyColor.Color` is a `string` but it's used as a `Brush` when data bound in XAML, this is a capability provided by WPF.
 1. The `AddColorCommand` async callback contains a 2-second delay to simulate a long-running operation.
-1. We use [ObservableCollection\<T\>](/dotnet/api/system.collections.objectmodel.observablecollection-1), which is supported by Remote UI, to dynamically update the list view.
+1. We use [ObservableList\<T\>](microsoft.visualstudio.extensibility.ui.observablelist-1), which is an extended [ObservableCollection\<T\>](/dotnet/api/system.collections.objectmodel.observablecollection-1) provided by Remote UI to also support range operations, allowing better performance.
 1. `MyToolWindowData` and `MyColor` don't implement [INotifyPropertyChanged](/dotnet/api/system.componentmodel.inotifypropertychanged) because, at the moment, all properties are readonly.
 
 ## Handle long-running async commands

docs/extensibility/visualstudio.extensibility/inside-the-sdk/contributions-and-configurations.md

@@ -44,8 +44,7 @@ The Command Parenting sample contributes another class, a `Command`, to Visual S
 [VisualStudioContribution]
 internal class SampleCommand : Command
 {
-    public SampleCommand(VisualStudioExtensibility extensibility)
-        : base(extensibility)
+    public SampleCommand()
     {
     }
     ...
@@ -67,19 +66,19 @@ Most Visual Studio contribution classes require or allow configuration. For exam
 [VisualStudioContribution]
 internal class SampleCommand : Command
 {
-    ...
-    public override CommandConfiguration CommandConfiguration => new("%SampleCommand.DisplayName%")
+    /// <inheritdoc />
+    public override CommandConfiguration CommandConfiguration => new("%CommandParentingSample.SampleCommand.DisplayName%")
     {
         Placements = new[]
         {
             // File in project context menu
-            CommandPlacement.FromVsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), 1072),
+            CommandPlacement.VsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), id: 1072, priority: 0),
 
             // Project context menu
-            CommandPlacement.FromVsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), 1026),
+            CommandPlacement.VsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), id:  1026, priority: 0),
 
             // Solution context menu
-            CommandPlacement.FromVsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), 1043),
+            CommandPlacement.VsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), id:  1043, priority: 0),
         },
     };
     ...
@@ -89,7 +88,7 @@ internal class SampleCommand : Command
 
 *Compile-time constants* are subject to additional limitations compared to normal properties, for example they must be readonly and their initialization code can't include references to non-static members or multi-statement imperative code blocks. These restrictions are enforced by the VisualStudio.Extensibility build tools and results in error messages like the following:
 
-> Property SampleCommand.CommandConfiguration is a compile-time constant. References to user-defined non-static members are not supported when evaluating compile-time constant values.
+> An issue was encountered when evaluating the compile-time constant SampleCommand.CommandConfiguration. References to user-defined non-static members are not supported when evaluating compile-time constant values.
 
 In general, the extension shouldn't reference *compile-time constant* configuration properties at run time.
 
@@ -108,9 +107,7 @@ public abstract class Command : ExecutableCommandHandler, IVisualStudioContribut
     ...
 ```
 
-On rare occasions, configuration properties are optional. For example, the `Extension` class has a virtual `ExtensionConfiguration` property which includes some less common configurations.
-
-In certain cases, you may need to implement multiple configuration properties on the same class. This is common when extending `ExtensionPart` and implementing multiple interfaces, each one requiring its own configuration property.
+On rare occasions, configuration properties may be optional. In certain cases, you may need to implement multiple configuration properties on the same class. This is common when extending `ExtensionPart` and implementing multiple interfaces, each one requiring its own configuration property.
 
 ## Standalone configuration properties
 
@@ -128,7 +125,7 @@ namespace CommandParentingSample;
 internal static class ExtensionCommandConfiguration
 {
     [VisualStudioContribution]
-    public static ToolbarConfiguration ToolBar => new("%ToolBar.DisplayName%")
+    public static ToolbarConfiguration ToolBar => new("%CommandParentingSample.ToolBar.DisplayName%")
     {
         Children = new[]
         {
@@ -140,28 +137,26 @@ internal static class ExtensionCommandConfiguration
 
 Visual Studio contribution properties are also *compile-time constants* and are subject to the same limitations discussed earlier.
 
-The [Markdown Linter](https://github.com/Microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/MarkdownLinter/TextViewEventListener.cs) project shows a sample of a Visual Studio contribution property being referenced by another configuration property:
+A of a Visual Studio contribution property can also reference another configuration property. For example:
 
 ```csharp
-internal static class MarkdownLinterExtensionContributions
+public static class MenuConfigurations
 {
     [VisualStudioContribution]
-    internal static DocumentTypeConfiguration MarkdownDocumentType => new("markdown")
+    public static CommandGroupConfiguration MyCommandGroup => new(GroupPlacement.KnownPlacements.ExtensionsMenu)
     {
-        FileExtensions = new[] { ".md", ".mdk", ".markdown" },
-        BaseDocumentType = DocumentType.KnownValues.Text,
+        Children = new GroupChild[]
+        {
+            GroupChild.Menu(MyMenu),
+        },
     };
-}
 
-[VisualStudioContribution]
-internal class TextViewEventListener : ExtensionPart, ITextViewOpenClosedListener, ITextViewChangedListener
-{
-    ...
-    public TextViewExtensionConfiguration TextViewExtensionConfiguration => new()
+    [VisualStudioContribution]
+    public static MenuConfiguration MyMenu => new("%MyMenu.DisplayName%")
     {
-        AppliesTo = new[]
+        Children = new[]
         {
-            DocumentFilter.FromDocumentType(MarkdownLinterExtensionContributions.MarkdownDocumentType),
+            MenuChild.Command<MyCommand>(),
         },
     };
     ...

docs/extensibility/visualstudio.extensibility/inside-the-sdk/extension-anatomy.md

@@ -16,13 +16,30 @@ An extension utilizing VisualStudio.Extensibility typically has several componen
 
 ## Extension instance
 
-The starting point for each extension is an instance of `Microsoft.VisualStudio.Extensibility.Extension`. This instance contains the necessary methods for Visual Studio to query services provided by the extension. It also provides virtual methods for the extension to provide localized resources and extension-owned local services to be shared between the components of the extension.
-
-Extension projects have their own class that derives from `Microsoft.VisualStudio.Extensibility.Extension` to customize certain aspects of the extension.
-
-Extensions must have a class that derives from `Microsoft.VisualStudio.Extensibility.Extension`. For an example implementation, see [MarkdownLinter](https://github.com/microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/MarkdownLinter).
-
-For extension developers that are familiar with the existing VS SDK APIs, this class is similar to `AsyncPackage` class that is used in the VS SDK extensibility model.
+Extensions must have a class that derives from [`Extension`](/dotnet/api/microsoft.visualstudio.extensibility.extension). For an example implementation, see [MarkdownLinter](https://github.com/microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/MarkdownLinter).
+
+An instance of the `Extension` class is the starting point for the extension's execution. This instance contains the necessary methods for Visual Studio to query services provided by the extension. It also provides virtual methods for the extension to provide localized resources and extension-owned local services to be shared between the components of the extension.
+
+The configuration for the `Extension` class also contains the [metadata](/dotnet/api/microsoft.visualstudio.extensibility.extensionconfiguration.metadata) for the extension which is shown in the Visual Studio [Manage Extensions window](/visualstudio/ide/finding-and-using-visual-studio-extensions?view=vs-2022#use-the-manage-extensions-dialog-box) and, for published extensions, on the [Visual Studio Marketplace](https://marketplace.visualstudio.com/).
+
+```csharp
+[VisualStudioContribution]
+public class MarkdownLinterExtension : Extension
+{
+    /// <inheritdoc/>
+    public override ExtensionConfiguration ExtensionConfiguration => new()
+    {
+        Metadata = new(
+                id: "MarkdownLinter.0cf26ba2-edd5-4419-8646-a55d0a83f7d8",
+                version: this.ExtensionAssemblyVersion,
+                publisherName: "Microsoft",
+                displayName: "Markdown Linter Sample Extension",
+                description: "Sample markdown linter extension"),
+    };
+    ...
+```
+
+For extension developers who are familiar with the existing VS SDK APIs, the `Metadata` contained in `ExtensionConfiguration` is used to generate the [.vsixmanifest](/visualstudio/extensibility/anatomy-of-a-vsix-package#the-vsix-manifest) file. Also, the `Extension` class is similar to the [`AsyncPackage`](/dotnet/api/microsoft.visualstudio.shell.asyncpackage) class that is used in the VS SDK extensibility model.
 
 ## VisualStudioExtensibility object