Create a multi-instance tool window

Applies to: Visual Studio Visual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

You can program a tool window so that multiple instances of it can be open simultaneously. By default, tool windows can have only one instance open.

When you use a multi-instance tool window, you can show several related sources of information at the same time. For example, you could put a multi-line TextBox control in a multi-instance tool window so that several code snippets are simultaneously available during a programming session. Also, for example, you could put a DataGrid control and a drop-down list box in a multi-instance tool window so that several real-time data sources can be tracked simultaneously.

Create a basic (single-instance) tool window

1. Create a project named MultiInstanceToolWindow using the VSIX template, and add a custom tool window item template named MIToolWindow.

   Note

   For more information about creating an extension with a tool window, see Create an extension with a tool window.

Make a tool window multi-instance

1. Open the MIToolWindowPackage.cs file and find the ProvideToolWindow attribute. and the MultiInstances=true parameter, as shown in the following example:

   [PackageRegistration(UseManagedResourcesOnly = true)]
       [InstalledProductRegistration("#110", "#112", "1.0", IconResourceID = 400)] // Info on this package for Help/About
       [ProvideMenuResource("Menus.ctmenu", 1)]
       [ProvideToolWindow(typeof(MultiInstanceToolWindow.MIToolWindow), MultiInstances = true)]
       [Guid(MIToolWindowPackage.PackageGuidString)]
       public sealed class MIToolWindowPackage : Package
   {. . .}
   

2. In the MIToolWindowCommand.cs file, find the ShowToolWindos() method. In this method, call the FindToolWindow method and set its create flag to false so that it will iterate through existing tool window instances until an available id is found.

3. To create a tool window instance, call the FindToolWindow method and set its id to an available value and its create flag to true.

   By default, the value of the id parameter of the FindToolWindow method is 0. This value makes a single-instance tool window. For more than one instance to be hosted, every instance must have its own unique id.

4. Call the Show method on the IVsWindowFrame object that is returned by the Frame property of the tool window instance.

5. By default, the ShowToolWindow method that is created by the tool window item template creates a single-instance tool window. The following example shows how to modify the ShowToolWindow method to create multiple instances.

   private void ShowToolWindow(object sender, EventArgs e)
   {
       for (int i = 0; i < 10; i++)
       {
           ToolWindowPane window = this.package.FindToolWindow(typeof(MIToolWindow), i, false);
           if (window == null)
           {
               // Create the window with the first free ID.
               window = (ToolWindowPane)this.package.FindToolWindow(typeof(MIToolWindow), i, true);
               if ((null == window) || (null == window.Frame))
               {
                   throw new NotSupportedException("Cannot create tool window");
               }
   
           IVsWindowFrame windowFrame = (IVsWindowFrame)window.Frame;
           Microsoft.VisualStudio.ErrorHandler.ThrowOnFailure(windowFrame.Show());
           break;
           }
       }
   }