Merge pull request #108 from microsoft/dev/ansarrat/ToolWindowDocs

Add tool window sample and tool window api docs

New_Extensibility_Model/Samples/Samples.sln

@@ -3,20 +3,22 @@ Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio Version 17
 VisualStudioVersion = 17.0.31516.38
 MinimumVisualStudioVersion = 10.0.40219.1
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SimpleRemoteCommandSample", "SimpleRemoteCommandSample\SimpleRemoteCommandSample.csproj", "{11EB62B3-79FD-450D-BC86-6FF414178B7E}"
-EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{070F0AEA-C0A0-4B5D-9286-55574A37BE7A}"
 	ProjectSection(SolutionItems) = preProject
 		Directory.Build.props = Directory.Build.props
 		shipping.ruleset = shipping.ruleset
 	EndProjectSection
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "MarkdownLinter", "MarkdownLinter\MarkdownLinter.csproj", "{F005B03E-66DC-4145-8BBA-9E21ABE582C2}"
-EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "CommandRegistrationsSample", "CommandRegistrationsSample\CommandRegistrationsSample.csproj", "{26601396-0E9A-4B38-8FE9-D5107B77D445}"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "InsertGuidExtension", "InsertGuidExtension\InsertGuidExtension.csproj", "{0B822716-63CA-41A9-8914-254A34C1976B}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "MarkdownLinter", "MarkdownLinter\MarkdownLinter.csproj", "{F005B03E-66DC-4145-8BBA-9E21ABE582C2}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SimpleRemoteCommandSample", "SimpleRemoteCommandSample\SimpleRemoteCommandSample.csproj", "{11EB62B3-79FD-450D-BC86-6FF414178B7E}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "ToolWindowExtension", "ToolWindowExtension\ToolWindowExtension.csproj", "{4605F69C-8179-409E-A3FA-431DD41F35CB}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -39,6 +41,10 @@ Global
 		{0B822716-63CA-41A9-8914-254A34C1976B}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{0B822716-63CA-41A9-8914-254A34C1976B}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{0B822716-63CA-41A9-8914-254A34C1976B}.Release|Any CPU.Build.0 = Release|Any CPU
+		{4605F69C-8179-409E-A3FA-431DD41F35CB}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{4605F69C-8179-409E-A3FA-431DD41F35CB}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{4605F69C-8179-409E-A3FA-431DD41F35CB}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{4605F69C-8179-409E-A3FA-431DD41F35CB}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

New_Extensibility_Model/Samples/ToolWindowExtension/MyToolWindow.cs

@@ -0,0 +1,44 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace ToolWindowExtension
+{
+	using Microsoft.VisualStudio.Extensibility;
+	using Microsoft.VisualStudio.Extensibility.ToolWindows;
+	using Microsoft.VisualStudio.RpcContracts.RemoteUI;
+
+	/// <summary>
+	/// A sample tool window.
+	/// </summary>
+	[ToolWindow(ToolWindowPlacement.DocumentWell)]
+	public class MyToolWindow : ToolWindow
+	{
+		private object? dataContext;
+
+		/// <summary>
+		/// Initializes a new instance of the <see cref="MyToolWindow" /> class.
+		/// </summary>
+		/// <param name="extensibility">
+		/// Extensibility object instance.
+		/// </param>
+		public MyToolWindow(VisualStudioExtensibility extensibility)
+			: base(extensibility)
+		{
+			this.Title = "My Tool Window";
+		}
+
+		/// <inheritdoc />
+		public override Task InitializeAsync(CancellationToken cancellationToken)
+		{
+			this.dataContext = new MyToolWindowData(this.Extensibility);
+
+			return Task.CompletedTask;
+		}
+
+		/// <inheritdoc />
+		public override Task<IRemoteUserControl> GetContentAsync(CancellationToken cancellationToken)
+		{
+			return Task.FromResult<IRemoteUserControl>(new MyToolWindowControl(this.dataContext));
+		}
+	}
+}

New_Extensibility_Model/Samples/ToolWindowExtension/MyToolWindowCommand.cs

@@ -0,0 +1,37 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace ToolWindowExtension
+{
+	using Microsoft.VisualStudio.Extensibility;
+	using Microsoft.VisualStudio.Extensibility.Commands;
+	using Microsoft.VisualStudio.Extensibility.Definitions;
+
+	/// <summary>
+	/// A sample command for showing a tool window.
+	/// </summary>
+	[Command("ToolWindowExtension.MyToolWindowCommand", "My Tool Window", placement: CommandPlacement.ToolsMenu)]
+	[CommandIcon(KnownMonikers.ToolWindow, IconSettings.IconAndText)]
+	public class MyToolWindowCommand : Command
+	{
+		/// <summary>
+		/// Initializes a new instance of the <see cref="MyToolWindowCommand" /> class.
+		/// </summary>
+		/// <param name="extensibility">
+		/// Extensibility object instance.
+		/// </param>
+		/// <param name="name">
+		/// Command identifier.
+		/// </param>
+		public MyToolWindowCommand(VisualStudioExtensibility extensibility, string name)
+			: base(extensibility, name)
+		{
+		}
+
+		/// <inheritdoc />
+		public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
+		{
+			await this.Extensibility.Shell().ShowToolWindowAsync<MyToolWindow>(activate: true, cancellationToken);
+		}
+	}
+}

New_Extensibility_Model/Samples/ToolWindowExtension/MyToolWindowControl.cs

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace ToolWindowExtension
+{
+	using Microsoft.VisualStudio.Extensibility.UI;
+
+	/// <summary>
+	/// A sample remote user control to use as tool window UI content.
+	/// </summary>
+	internal class MyToolWindowControl : RemoteUserControl
+	{
+		/// <summary>
+		/// Initializes a new instance of the <see cref="MyToolWindowControl" /> class.
+		/// </summary>
+		/// <param name="dataContext">
+		/// Data context of the remote control which can be referenced from xaml through data binding.
+		/// </param>
+		/// <param name="synchronizationContext">
+		/// Optional synchronizationContext that the extender can provide to ensure that <see cref="IAsyncCommand"/>
+		/// are executed and properties are read and updated from the extension main thread.
+		/// </param>
+		public MyToolWindowControl(object? dataContext, SynchronizationContext? synchronizationContext = null)
+			: base(dataContext, synchronizationContext)
+		{
+		}
+	}
+}

New_Extensibility_Model/Samples/ToolWindowExtension/MyToolWindowControl.xaml

@@ -0,0 +1,36 @@
+<DataTemplate xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+              xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+              xmlns:colors="clr-namespace:Microsoft.VisualStudio.PlatformUI;assembly=Microsoft.VisualStudio.Shell.15.0"
+              xmlns:styles="clr-namespace:Microsoft.VisualStudio.Shell;assembly=Microsoft.VisualStudio.Shell.15.0">
+  <Border Background="{DynamicResource {x:Static colors:EnvironmentColors.ToolWindowBackgroundBrushKey}}"
+          TextElement.Foreground="{DynamicResource {x:Static colors:EnvironmentColors.ToolWindowTextBrushKey}}"
+          Padding="5">
+    <StackPanel Orientation="Horizontal"
+                HorizontalAlignment="Center"
+                VerticalAlignment="Center">
+      <TextBlock Margin="0,0,5,0"
+                 Text="Custom Message:"
+                 VerticalAlignment="Center" />
+      <TextBox x:Name="TitleTextBox"
+               MinHeight="26"
+               MinWidth="200"
+               HorizontalContentAlignment="Left"
+               VerticalContentAlignment="Center"
+               Text="{Binding Message, Mode=TwoWay, UpdateSourceTrigger=PropertyChanged}"
+               Style="{StaticResource {x:Static styles:VsResourceKeys.TextBoxStyleKey}}" />
+      <Button x:Name="ShowMessageButton"
+              Content="Show Dialog"
+              IsEnabled="False"
+              Margin="5,0,0,0"
+              MinHeight="25"
+              MinWidth="60"
+              Style="{StaticResource {x:Static styles:VsResourceKeys.ButtonStyleKey}}"
+              Command="{Binding ShowMessageCommand}" />
+    </StackPanel>
+  </Border>
+  <DataTemplate.Triggers>
+    <DataTrigger Binding="{Binding HasError}" Value="False">
+      <Setter TargetName="ShowMessageButton" Property="IsEnabled" Value="True" />
+    </DataTrigger>
+  </DataTemplate.Triggers>
+</DataTemplate>

New_Extensibility_Model/Samples/ToolWindowExtension/MyToolWindowData.cs

@@ -0,0 +1,86 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace ToolWindowExtension
+{
+	using System.Runtime.Serialization;
+	using Microsoft;
+	using Microsoft.VisualStudio.Extensibility;
+	using Microsoft.VisualStudio.Extensibility.Shell;
+	using Microsoft.VisualStudio.Extensibility.UI;
+
+	/// <summary>
+	/// A sample data context object to use with tool window UI content.
+	/// </summary>
+	[DataContract]
+	internal class MyToolWindowData : NotifyPropertyChangedObject
+	{
+		private bool hasError;
+		private string message = "My custom message";
+
+		/// <summary>
+		/// Initializes a new instance of the <see cref="MyToolWindowData" /> class.
+		/// </summary>
+		/// <param name="extensibility">
+		/// Extensibility object instance.
+		/// </param>
+		public MyToolWindowData(VisualStudioExtensibility extensibility)
+		{
+			Requires.NotNull(extensibility, nameof(extensibility));
+
+			this.Context = new ClientContext(new Dictionary<string, object?>(), extensibility);
+			this.ShowMessageCommand = new AsyncCommand(this.ShowMessageAsync);
+		}
+
+		/// <summary>
+		/// Gets the async command used to show a message prompt.
+		/// </summary>
+		[DataMember]
+		public IAsyncCommand ShowMessageCommand
+		{
+			get;
+		}
+
+		/// <summary>
+		/// Gets or sets a value indicating whether there is an error in the data context.
+		/// </summary>
+		[DataMember]
+		public bool HasError
+		{
+			get => this.hasError;
+			set => this.SetProperty(ref this.hasError, value);
+		}
+
+		/// <summary>
+		/// Gets or sets the message to display in the message prompt.
+		/// </summary>
+		[DataMember]
+		public string Message
+		{
+			get => this.message;
+			set
+			{
+				if (string.IsNullOrWhiteSpace(value))
+				{
+					this.HasError = true;
+				}
+				else
+				{
+					this.HasError = false;
+				}
+
+				this.SetProperty(ref this.message, value);
+			}
+		}
+
+		private ClientContext Context
+		{
+			get;
+		}
+
+		private async Task ShowMessageAsync(object? commandParameter, CancellationToken cancellationToken)
+		{
+			await this.Context.ShowPromptAsync(this.Message, PromptOptions.OK, cancellationToken);
+		}
+	}
+}

New_Extensibility_Model/Samples/ToolWindowExtension/ToolWindowExtension.csproj

@@ -0,0 +1,24 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+	<PropertyGroup>
+		<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
+		<ImplicitUsings>enable</ImplicitUsings>
+		<LangVersion>10</LangVersion>
+		<Nullable>enable</Nullable>
+		<TargetFramework>net6.0-windows</TargetFramework>
+		<UseWPF>true</UseWPF>
+	</PropertyGroup>
+
+	<ItemGroup>
+		<PackageReference Include="Microsoft.VisualStudio.Extensibility.Sdk" Version="17.4.11-alpha" />
+	</ItemGroup>
+
+	<ItemGroup>
+		<EmbeddedResource Include="MyToolWindowControl.xaml" />
+	</ItemGroup>
+
+	<ItemGroup>
+		<Page Remove="MyToolWindowControl.xaml" />
+	</ItemGroup>
+
+</Project>

README.md

@@ -28,6 +28,7 @@ For future updates please bookmark our [announcements](docs/announcements.md) pa
 * [Rule based conditions](docs/new-extensibility-model/inside-the-sdk/activation-constraints.md)
 * [Remote UI](docs/new-extensibility-model/inside-the-sdk/remote-ui.md)
 * [Advanced Remote UI concepts](docs/new-extensibility-model/inside-the-sdk/advanced-remote-ui.md)
+* [Tool Windows](docs/new-extensibility-model/extension-guides/toolWindow/toolWindow.md)
 
 ## Samples and walkthroughs
 A Visual Studio solution containing all samples can be found at [Samples.sln](https://github.com/microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/Samples.sln).
@@ -37,6 +38,7 @@ A Visual Studio solution containing all samples can be found at [Samples.sln](ht
 * [Insert guid extension sample](https://github.com/microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/InsertGuidExtension)
 * [Command registration, localization sample](https://github.com/microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/CommandRegistrationsSample)
 * [Comment Remover, in-proc extension sample](https://github.com/microsoft/VSExtensibility/tree/main/New_Extensibility_Model/Samples/CommentRemover)
+* [Tool Window sample](./New_Extensibility_Model/Samples/ToolWindowExtension/)
 
 ## API Docs
 

docs/new-extensibility-model/api/Microsoft.VisualStudio.Extensibility.md

@@ -73,6 +73,12 @@
   - [ClearDiagnosticsAsync(textDocument,cancellationToken)](#M-Microsoft-VisualStudio-Extensibility-Documents-DiagnosticsProvider-ClearDiagnosticsAsync-Microsoft-VisualStudio-Extensibility-Editor-Data-ITextDocument,System-Threading-CancellationToken- 'Microsoft.VisualStudio.Extensibility.Documents.DiagnosticsProvider.ClearDiagnosticsAsync(Microsoft.VisualStudio.Extensibility.Editor.Data.ITextDocument,System.Threading.CancellationToken)')
   - [ClearDiagnosticsAsync(documentMoniker,cancellationToken)](#M-Microsoft-VisualStudio-Extensibility-Documents-DiagnosticsProvider-ClearDiagnosticsAsync-System-Uri,System-Threading-CancellationToken- 'Microsoft.VisualStudio.Extensibility.Documents.DiagnosticsProvider.ClearDiagnosticsAsync(System.Uri,System.Threading.CancellationToken)')
   - [Dispose()](#M-Microsoft-VisualStudio-Extensibility-Documents-DiagnosticsProvider-Dispose-System-Boolean- 'Microsoft.VisualStudio.Extensibility.Documents.DiagnosticsProvider.Dispose(System.Boolean)')
+- [Dock](#T-Microsoft-VisualStudio-Extensibility-ToolWindows-Dock 'Microsoft.VisualStudio.Extensibility.ToolWindows.Dock')
+  - [Bottom](#F-Microsoft-VisualStudio-Extensibility-ToolWindows-Dock-Bottom 'Microsoft.VisualStudio.Extensibility.ToolWindows.Dock.Bottom')
+  - [Left](#F-Microsoft-VisualStudio-Extensibility-ToolWindows-Dock-Left 'Microsoft.VisualStudio.Extensibility.ToolWindows.Dock.Left')
+  - [None](#F-Microsoft-VisualStudio-Extensibility-ToolWindows-Dock-None 'Microsoft.VisualStudio.Extensibility.ToolWindows.Dock.None')
+  - [Right](#F-Microsoft-VisualStudio-Extensibility-ToolWindows-Dock-Right 'Microsoft.VisualStudio.Extensibility.ToolWindows.Dock.Right')
+  - [Top](#F-Microsoft-VisualStudio-Extensibility-ToolWindows-Dock-Top 'Microsoft.VisualStudio.Extensibility.ToolWindows.Dock.Top')
 - [ExecutableCommand](#T-Microsoft-VisualStudio-Extensibility-Commands-ExecutableCommand 'Microsoft.VisualStudio.Extensibility.Commands.ExecutableCommand')
   - [#ctor(id)](#M-Microsoft-VisualStudio-Extensibility-Commands-ExecutableCommand-#ctor-System-UInt16- 'Microsoft.VisualStudio.Extensibility.Commands.ExecutableCommand.#ctor(System.UInt16)')
   - [Id](#P-Microsoft-VisualStudio-Extensibility-Commands-ExecutableCommand-Id 'Microsoft.VisualStudio.Extensibility.Commands.ExecutableCommand.Id')
@@ -148,6 +154,13 @@
   - [InvalidVersionString](#P-Microsoft-VisualStudio-Extensibility-Resources-InvalidVersionString 'Microsoft.VisualStudio.Extensibility.Resources.InvalidVersionString')
   - [ResourceManager](#P-Microsoft-VisualStudio-Extensibility-Resources-ResourceManager 'Microsoft.VisualStudio.Extensibility.Resources.ResourceManager')
   - [UnsupportedDocumentMoniker](#P-Microsoft-VisualStudio-Extensibility-Resources-UnsupportedDocumentMoniker 'Microsoft.VisualStudio.Extensibility.Resources.UnsupportedDocumentMoniker')
+- [ShellExtensibility](#T-Microsoft-VisualStudio-Extensibility-Shell-ShellExtensibility 'Microsoft.VisualStudio.Extensibility.Shell.ShellExtensibility')
+  - [#ctor(extensibilityPoint)](#M-Microsoft-VisualStudio-Extensibility-Shell-ShellExtensibility-#ctor-Microsoft-VisualStudio-Extensibility-ExtensibilityPoint- 'Microsoft.VisualStudio.Extensibility.Shell.ShellExtensibility.#ctor(Microsoft.VisualStudio.Extensibility.ExtensibilityPoint)')
+  - [Dispose()](#M-Microsoft-VisualStudio-Extensibility-Shell-ShellExtensibility-Dispose-System-Boolean- 'Microsoft.VisualStudio.Extensibility.Shell.ShellExtensibility.Dispose(System.Boolean)')
+  - [GetToolWindow\`\`1()](#M-Microsoft-VisualStudio-Extensibility-Shell-ShellExtensibility-GetToolWindow``1 'Microsoft.VisualStudio.Extensibility.Shell.ShellExtensibility.GetToolWindow``1')
+  - [HideToolWindowAsync\`\`1(cancellationToken)](#M-Microsoft-VisualStudio-Extensibility-Shell-ShellExtensibility-HideToolWindowAsync``1-System-Threading-CancellationToken- 'Microsoft.VisualStudio.Extensibility.Shell.ShellExtensibility.HideToolWindowAsync``1(System.Threading.CancellationToken)')
+  - [ServiceAvailabilityChanged(sender,args)](#M-Microsoft-VisualStudio-Extensibility-Shell-ShellExtensibility-ServiceAvailabilityChanged-System-Object,Microsoft-ServiceHub-Framework-BrokeredServicesChangedEventArgs- 'Microsoft.VisualStudio.Extensibility.Shell.ShellExtensibility.ServiceAvailabilityChanged(System.Object,Microsoft.ServiceHub.Framework.BrokeredServicesChangedEventArgs)')
+  - [ShowToolWindowAsync\`\`1(activate,cancellationToken)](#M-Microsoft-VisualStudio-Extensibility-Shell-ShellExtensibility-ShowToolWindowAsync``1-System-Boolean,System-Threading-CancellationToken- 'Microsoft.VisualStudio.Extensibility.Shell.ShellExtensibility.ShowToolWindowAsync``1(System.Boolean,System.Threading.CancellationToken)')
 - [SynchronizedBufferTextWriter](#T-Microsoft-VisualStudio-Extensibility-Documents-SynchronizedBufferTextWriter 'Microsoft.VisualStudio.Extensibility.Documents.SynchronizedBufferTextWriter')
   - [#ctor(pipeWriter,encoding)](#M-Microsoft-VisualStudio-Extensibility-Documents-SynchronizedBufferTextWriter-#ctor-System-IO-Pipelines-PipeWriter,System-Text-Encoding- 'Microsoft.VisualStudio.Extensibility.Documents.SynchronizedBufferTextWriter.#ctor(System.IO.Pipelines.PipeWriter,System.Text.Encoding)')
   - [Dispose()](#M-Microsoft-VisualStudio-Extensibility-Documents-SynchronizedBufferTextWriter-Dispose-System-Boolean- 'Microsoft.VisualStudio.Extensibility.Documents.SynchronizedBufferTextWriter.Dispose(System.Boolean)')
@@ -156,6 +169,29 @@
 - [ToggleCommand](#T-Microsoft-VisualStudio-Extensibility-Commands-ToggleCommand 'Microsoft.VisualStudio.Extensibility.Commands.ToggleCommand')
   - [#ctor(extensibility,id)](#M-Microsoft-VisualStudio-Extensibility-Commands-ToggleCommand-#ctor-Microsoft-VisualStudio-Extensibility-VisualStudioExtensibility,System-UInt16- 'Microsoft.VisualStudio.Extensibility.Commands.ToggleCommand.#ctor(Microsoft.VisualStudio.Extensibility.VisualStudioExtensibility,System.UInt16)')
   - [IsChecked](#P-Microsoft-VisualStudio-Extensibility-Commands-ToggleCommand-IsChecked 'Microsoft.VisualStudio.Extensibility.Commands.ToggleCommand.IsChecked')
+- [ToolWindow](#T-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindow')
+  - [#ctor(extensibility)](#M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-#ctor-Microsoft-VisualStudio-Extensibility-VisualStudioExtensibility- 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindow.#ctor(Microsoft.VisualStudio.Extensibility.VisualStudioExtensibility)')
+  - [Extensibility](#P-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-Extensibility 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindow.Extensibility')
+  - [Title](#P-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-Title 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindow.Title')
+  - [Dispose()](#M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-Dispose 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindow.Dispose')
+  - [Dispose(disposing)](#M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-Dispose-System-Boolean- 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindow.Dispose(System.Boolean)')
+  - [GetContentAsync(cancellationToken)](#M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-GetContentAsync-System-Threading-CancellationToken- 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindow.GetContentAsync(System.Threading.CancellationToken)')
+  - [HideAsync(cancellationToken)](#M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-HideAsync-System-Threading-CancellationToken- 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindow.HideAsync(System.Threading.CancellationToken)')
+  - [InitializeAsync(cancellationToken)](#M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-InitializeAsync-System-Threading-CancellationToken- 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindow.InitializeAsync(System.Threading.CancellationToken)')
+  - [OnHideAsync(cancellationToken)](#M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-OnHideAsync-System-Threading-CancellationToken- 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindow.OnHideAsync(System.Threading.CancellationToken)')
+  - [OnShowAsync(cancellationToken)](#M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-OnShowAsync-System-Threading-CancellationToken- 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindow.OnShowAsync(System.Threading.CancellationToken)')
+  - [ShowAsync(activate,cancellationToken)](#M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-ShowAsync-System-Boolean,System-Threading-CancellationToken- 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindow.ShowAsync(System.Boolean,System.Threading.CancellationToken)')
+- [ToolWindowAttribute](#T-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowAttribute 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowAttribute')
+  - [#ctor(placement,dockDirection,allowAutoCreation)](#M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowAttribute-#ctor-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowPlacement,Microsoft-VisualStudio-Extensibility-ToolWindows-Dock,System-Boolean- 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowAttribute.#ctor(Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowPlacement,Microsoft.VisualStudio.Extensibility.ToolWindows.Dock,System.Boolean)')
+  - [#ctor(placement,dockDirection,allowAutoCreation)](#M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowAttribute-#ctor-System-String,Microsoft-VisualStudio-Extensibility-ToolWindows-Dock,System-Boolean- 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowAttribute.#ctor(System.String,Microsoft.VisualStudio.Extensibility.ToolWindows.Dock,System.Boolean)')
+  - [AllowAutoCreation](#P-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowAttribute-AllowAutoCreation 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowAttribute.AllowAutoCreation')
+  - [DockDirection](#P-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowAttribute-DockDirection 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowAttribute.DockDirection')
+  - [Placement](#P-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowAttribute-Placement 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowAttribute.Placement')
+- [ToolWindowPlacement](#T-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowPlacement 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowPlacement')
+  - [DocumentWell](#F-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowPlacement-DocumentWell 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowPlacement.DocumentWell')
+  - [Floating](#F-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowPlacement-Floating 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowPlacement.Floating')
+- [ToolWindowVisibleWhenAttribute](#T-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowVisibleWhenAttribute 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowVisibleWhenAttribute')
+  - [#ctor(expression,termNames,termValues)](#M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowVisibleWhenAttribute-#ctor-System-String,System-String[],System-String[]- 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowVisibleWhenAttribute.#ctor(System.String,System.String[],System.String[])')
 - [ViewsExtensibility](#T-Microsoft-VisualStudio-Extensibility-Documents-ViewsExtensibility 'Microsoft.VisualStudio.Extensibility.Documents.ViewsExtensibility')
   - [#ctor(extensibilityPoint)](#M-Microsoft-VisualStudio-Extensibility-Documents-ViewsExtensibility-#ctor-Microsoft-VisualStudio-Extensibility-ExtensibilityPoint- 'Microsoft.VisualStudio.Extensibility.Documents.ViewsExtensibility.#ctor(Microsoft.VisualStudio.Extensibility.ExtensibilityPoint)')
   - [Output](#P-Microsoft-VisualStudio-Extensibility-Documents-ViewsExtensibility-Output 'Microsoft.VisualStudio.Extensibility.Documents.ViewsExtensibility.Output')
@@ -1073,6 +1109,52 @@ A [Task](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=
 
 This method has no parameters.
 
+<a name='T-Microsoft-VisualStudio-Extensibility-ToolWindows-Dock'></a>
+## Dock `type`
+
+##### Namespace
+
+Microsoft.VisualStudio.Extensibility.ToolWindows
+
+##### Summary
+
+Dock direction that can be used to control how a tool window is docked when it's first shown.
+
+<a name='F-Microsoft-VisualStudio-Extensibility-ToolWindows-Dock-Bottom'></a>
+### Bottom `constants`
+
+##### Summary
+
+Docks the tool window below its placement target.
+
+<a name='F-Microsoft-VisualStudio-Extensibility-ToolWindows-Dock-Left'></a>
+### Left `constants`
+
+##### Summary
+
+Docks the tool window to the left of its placement target.
+
+<a name='F-Microsoft-VisualStudio-Extensibility-ToolWindows-Dock-None'></a>
+### None `constants`
+
+##### Summary
+
+Docks the tool window alongside its placement target.
+
+<a name='F-Microsoft-VisualStudio-Extensibility-ToolWindows-Dock-Right'></a>
+### Right `constants`
+
+##### Summary
+
+Docks the tool window to the right of its placement target.
+
+<a name='F-Microsoft-VisualStudio-Extensibility-ToolWindows-Dock-Top'></a>
+### Top `constants`
+
+##### Summary
+
+Docks the tool window above its placement target.
+
 <a name='T-Microsoft-VisualStudio-Extensibility-Commands-ExecutableCommand'></a>
 ## ExecutableCommand `type`
 
@@ -1921,6 +2003,123 @@ Returns the cached ResourceManager instance used by this class.
 
 Looks up a localized string similar to Unsupported document moniker..
 
+<a name='T-Microsoft-VisualStudio-Extensibility-Shell-ShellExtensibility'></a>
+## ShellExtensibility `type`
+
+##### Namespace
+
+Microsoft.VisualStudio.Extensibility.Shell
+
+##### Summary
+
+Provides functionality to interact with Visual Studio shell services such as progress reporting, notifications, etc.
+
+<a name='M-Microsoft-VisualStudio-Extensibility-Shell-ShellExtensibility-#ctor-Microsoft-VisualStudio-Extensibility-ExtensibilityPoint-'></a>
+### #ctor(extensibilityPoint) `constructor`
+
+##### Summary
+
+Initializes a new instance of the [ShellExtensibility](#T-Microsoft-VisualStudio-Extensibility-Shell-ShellExtensibility 'Microsoft.VisualStudio.Extensibility.Shell.ShellExtensibility') class.
+
+##### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| extensibilityPoint | [Microsoft.VisualStudio.Extensibility.ExtensibilityPoint](#T-Microsoft-VisualStudio-Extensibility-ExtensibilityPoint 'Microsoft.VisualStudio.Extensibility.ExtensibilityPoint') | Another instance of extensibility point object to use for initialization. |
+
+<a name='M-Microsoft-VisualStudio-Extensibility-Shell-ShellExtensibility-Dispose-System-Boolean-'></a>
+### Dispose() `method`
+
+##### Summary
+
+*Inherit from parent.*
+
+##### Parameters
+
+This method has no parameters.
+
+<a name='M-Microsoft-VisualStudio-Extensibility-Shell-ShellExtensibility-GetToolWindow``1'></a>
+### GetToolWindow\`\`1() `method`
+
+##### Summary
+
+Gets the tool window of the given type.
+
+##### Returns
+
+The tool window matching the given type or null if not found.
+
+##### Parameters
+
+This method has no parameters.
+
+##### Generic Types
+
+| Name | Description |
+| ---- | ----------- |
+| T | The type of the tool window. |
+
+<a name='M-Microsoft-VisualStudio-Extensibility-Shell-ShellExtensibility-HideToolWindowAsync``1-System-Threading-CancellationToken-'></a>
+### HideToolWindowAsync\`\`1(cancellationToken) `method`
+
+##### Summary
+
+Hides the tool window of the given type.
+
+##### Returns
+
+A [Task](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Threading.Tasks.Task 'System.Threading.Tasks.Task') representing the asynchronous operation.
+
+##### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| cancellationToken | [System.Threading.CancellationToken](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Threading.CancellationToken 'System.Threading.CancellationToken') | A [CancellationToken](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Threading.CancellationToken 'System.Threading.CancellationToken') to cancel the in-progress request. |
+
+##### Generic Types
+
+| Name | Description |
+| ---- | ----------- |
+| T | The type of the tool window. |
+
+<a name='M-Microsoft-VisualStudio-Extensibility-Shell-ShellExtensibility-ServiceAvailabilityChanged-System-Object,Microsoft-ServiceHub-Framework-BrokeredServicesChangedEventArgs-'></a>
+### ServiceAvailabilityChanged(sender,args) `method`
+
+##### Summary
+
+Handles the service instance when availability of brokered services has changed.
+
+##### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| sender | [System.Object](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Object 'System.Object') | Sender. |
+| args | [Microsoft.ServiceHub.Framework.BrokeredServicesChangedEventArgs](#T-Microsoft-ServiceHub-Framework-BrokeredServicesChangedEventArgs 'Microsoft.ServiceHub.Framework.BrokeredServicesChangedEventArgs') | BrokeredServicesChangedEventArgs. |
+
+<a name='M-Microsoft-VisualStudio-Extensibility-Shell-ShellExtensibility-ShowToolWindowAsync``1-System-Boolean,System-Threading-CancellationToken-'></a>
+### ShowToolWindowAsync\`\`1(activate,cancellationToken) `method`
+
+##### Summary
+
+Shows the tool window of the given type.
+
+##### Returns
+
+A [Task](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Threading.Tasks.Task 'System.Threading.Tasks.Task') representing the asynchronous operation.
+
+##### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| activate | [System.Boolean](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Boolean 'System.Boolean') | Whether or not to activate the tool window during the show. Activating a tool window will move focus into it. |
+| cancellationToken | [System.Threading.CancellationToken](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Threading.CancellationToken 'System.Threading.CancellationToken') | A [CancellationToken](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Threading.CancellationToken 'System.Threading.CancellationToken') to cancel the in-progress request. |
+
+##### Generic Types
+
+| Name | Description |
+| ---- | ----------- |
+| T | The type of the tool window. |
+
 <a name='T-Microsoft-VisualStudio-Extensibility-Documents-SynchronizedBufferTextWriter'></a>
 ## SynchronizedBufferTextWriter `type`
 
@@ -2011,6 +2210,314 @@ Initializes a new instance of the [ToggleCommand](#T-Microsoft-VisualStudio-Exte
 
 *Inherit from parent.*
 
+<a name='T-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow'></a>
+## ToolWindow `type`
+
+##### Namespace
+
+Microsoft.VisualStudio.Extensibility.ToolWindows
+
+##### Summary
+
+Provides functionality for defining and interacting with a tool window.
+
+<a name='M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-#ctor-Microsoft-VisualStudio-Extensibility-VisualStudioExtensibility-'></a>
+### #ctor(extensibility) `constructor`
+
+##### Summary
+
+Initializes a new instance of the [ToolWindow](#T-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindow') class.
+
+##### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| extensibility | [Microsoft.VisualStudio.Extensibility.VisualStudioExtensibility](#T-Microsoft-VisualStudio-Extensibility-VisualStudioExtensibility 'Microsoft.VisualStudio.Extensibility.VisualStudioExtensibility') | Extensibility object. |
+
+<a name='P-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-Extensibility'></a>
+### Extensibility `property`
+
+##### Summary
+
+Gets the Visual Studio extensibility point.
+
+<a name='P-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-Title'></a>
+### Title `property`
+
+##### Summary
+
+Gets or sets the title of the tool window.
+
+<a name='M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-Dispose'></a>
+### Dispose() `method`
+
+##### Summary
+
+*Inherit from parent.*
+
+##### Parameters
+
+This method has no parameters.
+
+<a name='M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-Dispose-System-Boolean-'></a>
+### Dispose(disposing) `method`
+
+##### Summary
+
+Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
+
+##### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| disposing | [System.Boolean](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Boolean 'System.Boolean') | Whether managed resources should be disposed. This should be `false` when
+[Dispose](#M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-Dispose-System-Boolean- 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindow.Dispose(System.Boolean)') is called from a finalizer, `true` otherwise. |
+
+<a name='M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-GetContentAsync-System-Threading-CancellationToken-'></a>
+### GetContentAsync(cancellationToken) `method`
+
+##### Summary
+
+Gets the tool window's UI content.
+
+##### Returns
+
+An [IRemoteUserControl](#T-Microsoft-VisualStudio-RpcContracts-RemoteUI-IRemoteUserControl 'Microsoft.VisualStudio.RpcContracts.RemoteUI.IRemoteUserControl') which represents the tool window's UI content.
+
+##### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| cancellationToken | [System.Threading.CancellationToken](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Threading.CancellationToken 'System.Threading.CancellationToken') | A cancellation token to cancel the in-progress content creation. |
+
+<a name='M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-HideAsync-System-Threading-CancellationToken-'></a>
+### HideAsync(cancellationToken) `method`
+
+##### Summary
+
+Hides the tool window.
+
+##### Returns
+
+A [Task](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Threading.Tasks.Task 'System.Threading.Tasks.Task') representing the asynchronous operation.
+
+##### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| cancellationToken | [System.Threading.CancellationToken](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Threading.CancellationToken 'System.Threading.CancellationToken') | A cancellation token to cancel the in-progress hide. |
+
+<a name='M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-InitializeAsync-System-Threading-CancellationToken-'></a>
+### InitializeAsync(cancellationToken) `method`
+
+##### Summary
+
+Initializes the tool window.
+
+##### Returns
+
+A [Task](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Threading.Tasks.Task 'System.Threading.Tasks.Task') representing the asynchronous operation.
+
+##### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| cancellationToken | [System.Threading.CancellationToken](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Threading.CancellationToken 'System.Threading.CancellationToken') | A cancellation token to cancel the in-progress initialization. |
+
+##### Remarks
+
+This method is called prior to calling [GetContentAsync](#M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-GetContentAsync-System-Threading-CancellationToken- 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindow.GetContentAsync(System.Threading.CancellationToken)') and can be used
+for any work that needs to be done prior to creating the tool window's UI content.
+
+<a name='M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-OnHideAsync-System-Threading-CancellationToken-'></a>
+### OnHideAsync(cancellationToken) `method`
+
+##### Summary
+
+Notifies that the tool window is being hidden.
+
+##### Returns
+
+A [Task](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Threading.Tasks.Task 'System.Threading.Tasks.Task') representing the asynchronous operation.
+
+##### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| cancellationToken | [System.Threading.CancellationToken](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Threading.CancellationToken 'System.Threading.CancellationToken') | A cancellation token to cancel the in-progress hide. |
+
+<a name='M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-OnShowAsync-System-Threading-CancellationToken-'></a>
+### OnShowAsync(cancellationToken) `method`
+
+##### Summary
+
+Notifies that the tool window is being shown.
+
+##### Returns
+
+A [Task](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Threading.Tasks.Task 'System.Threading.Tasks.Task') representing the asynchronous operation.
+
+##### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| cancellationToken | [System.Threading.CancellationToken](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Threading.CancellationToken 'System.Threading.CancellationToken') | A cancellation token to cancel the in-progress show. |
+
+<a name='M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindow-ShowAsync-System-Boolean,System-Threading-CancellationToken-'></a>
+### ShowAsync(activate,cancellationToken) `method`
+
+##### Summary
+
+Shows the tool window.
+
+##### Returns
+
+A [Task](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Threading.Tasks.Task 'System.Threading.Tasks.Task') representing the asynchronous operation.
+
+##### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| activate | [System.Boolean](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Boolean 'System.Boolean') | Whether or not to activate the tool window during the show. Activating a tool window will move focus into it. |
+| cancellationToken | [System.Threading.CancellationToken](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Threading.CancellationToken 'System.Threading.CancellationToken') | A cancellation token to cancel the in-progress hide. |
+
+<a name='T-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowAttribute'></a>
+## ToolWindowAttribute `type`
+
+##### Namespace
+
+Microsoft.VisualStudio.Extensibility.ToolWindows
+
+##### Summary
+
+An attribute used on ToolWindow classes to register a tool window and define its default behaviors.
+
+<a name='M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowAttribute-#ctor-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowPlacement,Microsoft-VisualStudio-Extensibility-ToolWindows-Dock,System-Boolean-'></a>
+### #ctor(placement,dockDirection,allowAutoCreation) `constructor`
+
+##### Summary
+
+Initializes a new instance of the [ToolWindowAttribute](#T-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowAttribute 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowAttribute') class.
+
+##### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| placement | [Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowPlacement](#T-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowPlacement 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowPlacement') | The placement location for the tool window. Valid values come from [ToolWindowPlacement](#T-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowPlacement 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowPlacement'). |
+| dockDirection | [Microsoft.VisualStudio.Extensibility.ToolWindows.Dock](#T-Microsoft-VisualStudio-Extensibility-ToolWindows-Dock 'Microsoft.VisualStudio.Extensibility.ToolWindows.Dock') | The direction relative to the placement where the tool window should be docked. |
+| allowAutoCreation | [System.Boolean](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Boolean 'System.Boolean') | Whether or not the tool window can be created automatically. |
+
+<a name='M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowAttribute-#ctor-System-String,Microsoft-VisualStudio-Extensibility-ToolWindows-Dock,System-Boolean-'></a>
+### #ctor(placement,dockDirection,allowAutoCreation) `constructor`
+
+##### Summary
+
+Initializes a new instance of the [ToolWindowAttribute](#T-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowAttribute 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowAttribute') class.
+
+##### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| placement | [System.String](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.String 'System.String') | The placement location for the tool window. Valid values come from guids of other tool windows. |
+| dockDirection | [Microsoft.VisualStudio.Extensibility.ToolWindows.Dock](#T-Microsoft-VisualStudio-Extensibility-ToolWindows-Dock 'Microsoft.VisualStudio.Extensibility.ToolWindows.Dock') | The direction relative to the placement where the tool window should be docked. |
+| allowAutoCreation | [System.Boolean](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.Boolean 'System.Boolean') | Whether or not the tool window can be created automatically. |
+
+<a name='P-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowAttribute-AllowAutoCreation'></a>
+### AllowAutoCreation `property`
+
+##### Summary
+
+Gets a value indicating whether the tool window can be created automatically.
+
+##### Remarks
+
+When true, the tool window will be created if it should be visible in the current window layout or when any
+relevant visibility contexts activate. When false the tool window will not be created as part of loading any
+window layout or due to visibility contexts, and the only way to trigger the creation is to manually show it.
+
+<a name='P-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowAttribute-DockDirection'></a>
+### DockDirection `property`
+
+##### Summary
+
+Gets the dock direction where the tool window should be placed relative to the [Placement](#P-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowAttribute-Placement 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowAttribute.Placement') value.
+
+##### Remarks
+
+If the [Placement](#P-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowAttribute-Placement 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowAttribute.Placement') has the value [Floating](#F-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowPlacement-Floating 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowPlacement.Floating') this value is ignored. If
+the [Placement](#P-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowAttribute-Placement 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowAttribute.Placement') has the value [DocumentWell](#F-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowPlacement-DocumentWell 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowPlacement.DocumentWell') this value will dock
+the tool window to the corresponding side of the main window's document well. If the [Placement](#P-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowAttribute-Placement 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowAttribute.Placement') is
+any other value the tool window will be docked relative to the [Placement](#P-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowAttribute-Placement 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowAttribute.Placement') based on the value of the
+"Insert new tabs to the right" setting with the exception of [Left](#F-Microsoft-VisualStudio-Extensibility-ToolWindows-Dock-Left 'Microsoft.VisualStudio.Extensibility.ToolWindows.Dock.Left') which will always dock to
+the left of the [Placement](#P-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowAttribute-Placement 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowAttribute.Placement').
+
+<a name='P-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowAttribute-Placement'></a>
+### Placement `property`
+
+##### Summary
+
+Gets the default placement location for the tool window. This can be a well-known string from
+[ToolWindowPlacement](#T-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowPlacement 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowPlacement'), or the guid string of another tool window.
+
+##### Remarks
+
+If the value is [Floating](#F-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowPlacement-Floating 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowPlacement.Floating') the tool window will be created in its own floating
+window. If the value is [DocumentWell](#F-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowPlacement-DocumentWell 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowPlacement.DocumentWell') the tool window will be docked in
+relation to the main window's document well. Any other value will attempt to find the referenced location and
+dock the tool window relative to that location, but if that location cannot be found, the tool window will
+fallback to opening in a floating window.
+
+<a name='T-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowPlacement'></a>
+## ToolWindowPlacement `type`
+
+##### Namespace
+
+Microsoft.VisualStudio.Extensibility.ToolWindows
+
+##### Summary
+
+Known default tool window placements.
+
+<a name='F-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowPlacement-DocumentWell'></a>
+### DocumentWell `constants`
+
+##### Summary
+
+Places the tool window in the active document well by default.
+
+<a name='F-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowPlacement-Floating'></a>
+### Floating `constants`
+
+##### Summary
+
+Places the tool window in a standalone floating window by default.
+
+<a name='T-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowVisibleWhenAttribute'></a>
+## ToolWindowVisibleWhenAttribute `type`
+
+##### Namespace
+
+Microsoft.VisualStudio.Extensibility.ToolWindows
+
+##### Summary
+
+An attribute used on ToolWindow classes to register a visibility context for showing a tool window.
+
+<a name='M-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowVisibleWhenAttribute-#ctor-System-String,System-String[],System-String[]-'></a>
+### #ctor(expression,termNames,termValues) `constructor`
+
+##### Summary
+
+Initializes a new instance of the [ToolWindowVisibleWhenAttribute](#T-Microsoft-VisualStudio-Extensibility-ToolWindows-ToolWindowVisibleWhenAttribute 'Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowVisibleWhenAttribute') class.
+
+##### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| expression | [System.String](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.String 'System.String') | A boolean expression string. |
+| termNames | [System.String[]](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.String[] 'System.String[]') | The names of the terms used in the expression. |
+| termValues | [System.String[]](http://msdn.microsoft.com/query/dev14.query?appId=Dev14IDEF1&l=EN-US&k=k:System.String[] 'System.String[]') | The values of each term in the same order as term names array. |
+
 <a name='T-Microsoft-VisualStudio-Extensibility-Documents-ViewsExtensibility'></a>
 ## ViewsExtensibility `type`
 

docs/new-extensibility-model/extension-guides/toolWindow/toolWindow.md

@@ -0,0 +1,152 @@
+---
+title: Tool Windows reference
+description: A reference for extensibility tool windows
+date: 2022-7-20
+---
+
+# Tool Windows
+
+Tool windows are a way to add complex UI and interactions to Visual Studio. They typically provide a user friendly mechanism for interacting with various APIs and features. For example, the Solution Explorer provides a tree-based view of the current project/solution/folder and allows simple gestures for opening, renaming, creating files.
+
+Tool windows are single-instance , meaning that only one instance of the tool window can be open at a time. After a single-instance tool window is opened, it remains open until Visual Studio is closed, and when closed the tool window is only visibly hidden instead of being fully closed and disposed like documents. Tool windows can be dynamic, meaning that they are visible whenever their related context rule applies. The use of auto-visibility can reduce the clutter of windows in the IDE. Tool windows can be docked, floating, or tabbed in the document well. The default size and location apply only when the tool window is first opened and after that the tool window state is persisted.
+
+## Creating new tool windows
+
+To get started, follow the [create the project](../getting-started/create-your-first-extension.md) section in Getting Started section.
+
+### Registering a tool window
+
+Creating a tool window with the new Extensibility Model is as simple as extending the base class `Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindow` and adorning your class with the attribute `Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowAttribute`.
+
+The attribute [Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowAttribute](./../../api/Microsoft.VisualStudio.Extensibility.md/#toolwindowattribute-type) has a few parameters that you should become familiar with:
+
+| Parameter | Type | Required | Description |
+| --------- |----- | -------- | ----------- |
+| Placement | ToolWindowPlacement or String | No | The location in Visual Studio where the tool window should be opened the first time. If this value is a string it's expected to be a guid matching an old vsix-style tool window id. See more about [ToolWindowPlacement](#tool-window-placement). |
+| DockDirection | Dock | No | The direction relative to the placement where the tool window should be docked when opened the first time. See more about [Dock](#dock). |
+| AllowAutoCreation | Bool | No | Whether or not the tool window can be created automatically. Setting this to false means that tool windows that are open when Visual Studio is closed will not be automatically restored when Visual Studio is opened again. |
+
+```csharp
+// This is a default tool window registration that will result in:
+// 1) Placement of ToolWindowPlacement.Floating
+// 2) Dock direction of Dock.None
+// 3) Allow auto-creation being enabled
+[ToolWindow]
+public class MyToolWindow : ToolWindow
+{
+    public MyToolWindow(VisualStudioExtensibility extensibility)
+        : base(extensibility)
+    {
+        this.Title = "My Tool Window";
+    }
+
+    public override Task<IRemoteUserControl> GetContentAsync(CancellationToken cancellationToken)
+    {
+        // TODO: Create and return a RemoteUserControl
+    }
+}
+```
+See the [ToolWindowExtension](./../../../../New_Extensibility_Model/Samples/ToolWindowExtension) sample to get started with creating an extension with a tool window.
+
+### Creating content for a tool window
+
+Once a tool window is registered it will need content. Adding content requires creating a [RemoteUserControl](./../../inside-the-sdk/remote-ui.md) and corresponding data template for the control.
+
+```csharp
+    [ToolWindow(ToolWindowPlacement.DocumentWell)]
+    public class MyToolWindow : ToolWindow
+    {
+        public MyToolWindow(VisualStudioExtensibility extensibility)
+            : base(extensibility)
+        {
+            this.Title = "My Tool Window";
+        }
+
+        public override Task<IRemoteUserControl> GetContentAsync(CancellationToken cancellationToken)
+        {
+            // The data object allows for data binding in the control.
+            var dataContext = new MyToolWindowData(this.Extensibility);
+
+            // The only work done here should be related to creating the content.
+            // If additional work is needed prior to creating the control, it
+            // can be done by overriding the InitializeAsync method
+            var control = new MyToolWindowControl(dataContext);
+            return Task.FromResult<IRemoteUserControl>(control);
+        }
+    }
+```
+
+MyToolWindowControl.cs: (this is an example file name and should have the same name as the data template file)
+
+```csharp
+internal class MyToolWindowControl : RemoteUserControl
+{
+    public MyToolWindowControl(object? dataContext, SynchronizationContext? synchronizationContext = null)
+        : base(dataContext, synchronizationContext)
+    {
+    }
+}
+```
+
+MyToolWindowControl.xaml (this is an example file name and should have the same name as the class that derives from RemoteUserControl)
+
+```xml
+<DataTemplate xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+              xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
+    <!-- TODO: Fill with content -->
+</DataTemplate>
+```
+
+See the [Remote UI](./../../inside-the-sdk/remote-ui.md) docs for more information on creating a RemoteUserControl.
+
+### Registering a command to show tool window
+
+A common mechanism for opening a tool window is to add a command that, when invoked, shows the tool window.
+
+```csharp
+[Command("ToolWindowExtension.MyToolWindowCommand", "My Tool Window", placement: CommandPlacement.ToolsMenu)]
+[CommandIcon(KnownMonikers.ToolWindow, IconSettings.IconAndText)]
+public class MyToolWindowCommand : Command
+{
+    public MyToolWindowCommand(VisualStudioExtensibility extensibility, string name)
+        : base(extensibility, name)
+    {
+    }
+
+    public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
+    {
+        // "Activate: true" here means that the tool window will be shown and given focus
+        // "Activate: false" here means that the tool window will only be shown which may result in only showing its tab
+        await this.Extensibility.Shell().ShowToolWindowAsync<MyToolWindow>(activate: true, cancellationToken);
+    }
+}
+```
+
+See the [Commands](./../command/command.md) docs to learn more about setting up commands.
+
+### Registering a tool window with dynamic visibility
+
+Another mechanism for opening a tool window is to set up activation constraints for when it should be shown or hidden. This allows tool windows to automatically be opened when certain conditions are met, and hidden again when those conditions are no longer applicable.
+
+The attribute [Microsoft.VisualStudio.Extensibility.ToolWindows.ToolWindowVisibleWhenAttribute](./../../api/Microsoft.VisualStudio.Extensibility.md/#toolwindowvisiblewhenattribute-type) has a few parameters that you should become familiar with:
+
+| Parameter | Type | Required | Description |
+| --------- |----- | -------- | ----------- |
+| Expression | String | Yes | A boolean expression string which, when true, will mean the context is active and the tool window will be shown. |
+| TermNames | String[] | Yes | The names of the terms used in the expression. |
+| TermValues | String[] | Yes | The values of each term. The term values must be in the same order as term names array. |
+
+```csharp
+// The tool window will be shown if a .cs file is the active document, and
+// will be hidden whenever any other file type is the active document.
+[ToolWindow]
+[ToolWindowVisibleWhen("FileSelected",
+                       new string[] { "FileSelected" },
+                       new string[] { "ClientContext:Shell.ActiveSelectionFileName=.cs$" })]
+public class MyToolWindow : ToolWindow
+{
+    // TODO: Implement the rest of the class
+}
+```
+
+See the [Using rule based activation constraints](../../inside-the-sdk/activation-constraints.md/#rule-based-activation-constraints) docs for more information on valid term values.