Merge pull request #10255 from MicrosoftDocs/main638520842492838657sync_temp

For protected branch, push strategy should use PR and merge to target branch method to work around git push error

Author: learn-build-service-prod[bot]

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

@@ -0,0 +1,105 @@
+---
+title: VisualStudio.Extensibility Diagnostics Explorer extension overview
+description: VisualStudio.Extensibilityo Diagnostics Explorer extension
+author: RyanToth3
+ms.author: rytoth
+monikerRange: ">=vs-2022"
+ms.subservice: extensibility-integration
+ms.topic: overview
+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. 
+
+## Get Started
+
+Follow these instructions to install, launch, and configure the Diagsnotics Explorer.
+
+### Install the Extension
+
+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.
+
+### Open the Diagnostics Explorer in Visual Studio
+
+To launch the Diagnostics Explorer in Visual Studio, select **VisualStudio.Extensibility Diagnostics Explorer** in the **Extensions** menu.
+
+![Screenshot of the command that opens the extension's tool window.](./media/image-1.png)
+
+### Enable collection of diagnostics
+
+The Diagnostics Explorer is configured to collect relevant diagnostic data from your extensions by default. If you want to disable or re-enable this data collection, you can toggle the **Enable collecting diagnostics** checkbox at the lower-left corner of the tool window. A restart of Visual Studio is required for any changes to this setting to take effect.
+
+![Screenshot of the "Enable collecting diagnostics" setting.](./media/image-11.png)
+
+## 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.
+
+![Screenshot of the left hand panel of the tool window.](./media/image-2.png)
+
+### Extensible Feature Pages
+
+Extensible feature pages have a ComboBox in the top-left for the different **Extensibility Points** in that feature area, each of which can be mapped directly to configuration objects in your extension. For example, in the **Commands** page there's an **Extensibility Point** for **Menus and Toolbars**, which shows you each of the menus and toolbars that Visual Studio discovered in your VisualStudio.Extensibility extensions.
+
+The data updates in real time as properties are updated in extensions. For example, if an extension changes the display name of one of its commands at runtime, the new display name of that command is shown in the cell in the **Display Name** column for that command immediately.
+
+![Screenshot of the Commands page.](./media/image-3.png)
+
+The **Extensibility Point** ComboBox also has an item called **Log**, which shows you a live view of those updates. The **Clear All** button beside the ComboBox can be used to clear all lines currently being displayed in the view.
+
+![Screenshot of the Command's Log page.](./media/image-4.png)
+
+You can filter the items in the view by using the **Extensions** ComboBox. When **All** is selected in this ComboBox, data for every installed VisualStudio.Extensibility extension is shown. If you change this ComboBox to the ID of a specific extension, only items related to that specific extension are shown. The value of this ComboBox is persisted even when you navigate between extensible feature pages.
+
+![Screenshot of the Command's page filtered to a specific extension.](./media/image-5.png)
+
+Some cells in the DataGrid display **[Click to Expand]**. This message means that the metadata related to that property is too verbose to be neatly displayed in a cell of the DataGrid. Clicking on the cell opens a modal dialog displaying the actual value of that cell.
+
+![Screenshot of the "Click to Expand" modal dialog."](./media/image-6.png)
+
+### 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.
+
+You can use the **Event** ComboBox to filter the view to only contain events with a specific name. When **All** is selected, then all events are shown. If a specific event is selected, all of the properties of the event are shown in the view. Some properties need to be expanded by clicking on **[Click to Expand]** if they're too verbose to be shown in a single cell.
+
+The **Contract** ComboBox filters the view to only show events related to a specific extensible feature. It also filters the `Event` ComboBox to only contain the names of events related to the specific extensible feature.
+
+Clicking the **Clear All** button deletes all the events currently shown in the view.
+
+![Screenshot of the Events page.](./media/image-7.png)
+
+#### Column Descriptions
+
+##### 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
+
+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
+
+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
+
+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
+
+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.
+
+![Screenshot of the Activation Constraint's Current State page.](./media/image-9.png)
+
+![Screenshot of the Activation Constraint's Events page.](./media/image-10.png)

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

@@ -43,6 +43,10 @@ There is some internal code in the ServiceHub host process that handles the RPC
 > [!TIP]
 > It can be convenient to have multiple monitors, so you can see both the debugger and the experimental instance at the same time on two different monitors. You might want to change the theme in the Experimental Instance to make it more obvious which IDE you're working with at any given time. See [Change fonts, colors, and themes in Visual Studio](../../../ide/how-to-change-fonts-and-colors-in-visual-studio.md).
 
+## Debug the extension using the Diagnostics Explorer
+
+Please see [VisualStudio.Extensibility Diagnostics Explorer](../diagnostics/visualstudio-extensibility-diagnostics-extension.md) for more information.
+
 ## Related content
 
 - [Learn more about debugging](/visualstudio/debugger/)

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

@@ -12,7 +12,7 @@ ms.subservice: extensibility-integration
 
 # Rule-based activation constraints
 
-One of the common concepts in VisualStudio.Extensibility is use of context-based activation rules. These are rules that govern the conditions under which an extension or a command is surfaced to the user. An example of a context-based activation rule is the [`VisibleWhen`](/dotnet/api/microsoft.visualstudio.extensibility.commands.commandconfiguration.visiblewhen) property in a command's configuration that declares when the command is made visible.
+One of the common concepts in VisualStudio.Extensibility is the use of context-based activation rules. These rules govern the conditions under which an extension or a command is surfaced to the user. An example of a context-based activation rule is the [`VisibleWhen`](/dotnet/api/microsoft.visualstudio.extensibility.commands.commandconfiguration.visiblewhen) property in a command's configuration that declares when the command is made visible.
 
 ## Constraint types
 
@@ -22,7 +22,7 @@ Multiple activation constraints can be combined together using the [`And`](/dotn
 
 ## Example definition
 
-In the following example, the command configuration property [`EnabledWhen`](/dotnet/api/microsoft.visualstudio.extensibility.commands.commandconfiguration.enabledwhen) defines when the command is in the enabled state. The [`ClientContext`](/dotnet/api/microsoft.visualstudio.extensibility.activationconstraint.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.
+In the following example, the command configuration property [`EnabledWhen`](/dotnet/api/microsoft.visualstudio.extensibility.commands.commandconfiguration.enabledwhen) defines when the command is in the enabled state. The [`ClientContext`](/dotnet/api/microsoft.visualstudio.extensibility.activationconstraint.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 selects a file with one of those extensions.
 
 ```csharp
 public override CommandConfiguration CommandConfiguration => new("%My command.DisplayName%")
@@ -64,6 +64,7 @@ This section shows the list of currently supported activation constraints. Each
 | [`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. |
+| [`EditorContentType`](/dotnet/api/microsoft.visualstudio.extensibility.activationconstraint.editorcontenttype)(\<contentType>) | True when active editor content type is or inherits from specific content type.
 
 For compatibility reasons, the following legacy activation constraints are also supported:
 
@@ -73,6 +74,7 @@ For compatibility reasons, the following legacy activation constraints are also
 | [`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. |
+| [`UIContext`](/dotnet/api/microsoft.visualstudio.extensibility.activationconstraint.uicontext)(\<guid>) | True when specified [UI Context](/dotnet/api/microsoft.visualstudio.vsconstants.uicontext) is active in Visual Studio instance. |
 
 ## Solution states
 

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

@@ -23,6 +23,7 @@ You'll learn about:
 - How reference types are handled in the Remote UI data context and its proxy.
 - How to use an *async command* as an event handler.
 - How to disable a single button when its *async command*'s callback is executing if multiple buttons are bound to the same command.
+- How to use XAML resource dictionaries from a Remote UI control.
 - How to use WPF types, like complex brushes, in the Remote UI data context.
 - How Remote UI handles threading.
 
@@ -261,6 +262,74 @@ In this case, we use `vs:EventHandler` to attach to each button its own separate
 
 ![Diagram of async Command with targeted RunningCommandsCount.](./media/targeted-counter.gif)
 
+## User XAML resource dictionaries
+
+Starting with Visual Studio 17.10, Remote UI supports [XAML resource dictionaries](/windows/apps/design/style/xaml-resource-dictionary). This allows multiple Remote UI controls to share styles, templates, and other resources. It also allows you to define different resources (E.g., strings) for different languages.
+
+Similarly to a Remote UI control XAML, resource files must be configured as embedded resources:
+
+```xml
+<ItemGroup>
+  <EmbeddedResource Include="MyResources.xaml" />
+  <Page Remove="MyResources.xaml" />
+</ItemGroup>
+```
+
+Remote UI references resource dictionaries in a different way than WPF: they are not added to the control's merged dictionaries (merged dictionaries are not supported at all by Remote UI) but referenced by name in the control's .cs file:
+
+```cs
+internal class MyToolWindowContent : RemoteUserControl
+{
+    public MyToolWindowContent()
+        : base(dataContext: new MyToolWindowData())
+    {
+        this.ResourceDictionaries.AddEmbeddedResource(
+            "MyToolWindowExtension.MyResources.xaml");
+    }
+...
+```
+
+`AddEmbeddedResource` takes the full name of the embedded resource which, by default, is composed of the root namespace for the project, any subfolder path it may be under, and the file name. It is possible to override such name by setting a `LogicalName` for the `EmbeddedResource` in the project file.
+
+The resource file itself is a normal WPF resource dictionary:
+
+```xml
+<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    xmlns:system="clr-namespace:System;assembly=mscorlib">
+  <system:String x:Key="removeButtonText">Remove</system:String>
+  <system:String x:Key="addButtonText">Add color</system:String>
+</ResourceDictionary>
+```
+
+You can reference a resource from the resource dictionary in the Remote UI control using `DynamicResource`:
+
+```xml
+<Button Content="{DynamicResource removeButtonText}" ...
+```
+
+## Localizing XAML resource dictionaries
+
+Remote UI resource dictionaries can be localized in the same way as you would localize embedded resources: you create other XAML files with the same name and a language suffix, for example `MyResources.it.xaml` for Italian resources:
+
+```xml
+<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    xmlns:system="clr-namespace:System;assembly=mscorlib">
+  <system:String x:Key="removeButtonText">Rimuovi</system:String>
+  <system:String x:Key="addButtonText">Aggiungi colore</system:String>
+</ResourceDictionary>
+```
+
+You can use wildcards in the project file to include all localized XAML dictionaries as embedded resources:
+
+```xml
+<ItemGroup>
+  <EmbeddedResource Include="MyResources.*xaml" />
+  <Page Remove="MyResources.*xaml" />
+</ItemGroup>
+```
+
 ## Use WPF types in the data context
 
 Until now, the data context of our *remote user control* has been composed of primitives (numbers, strings, etc.), observable collections and our own classes marked with `DataContract`. it's sometimes useful to include simple WPF types in the data context like complex brushes.