Dela via

Skapa Visual Studio-verktygsfönster

Verktygsfönster är ett sätt att lägga till komplexa användargränssnitt och interaktioner i Visual Studio. De är vanligtvis ett användarvänligt sätt att interagera med olika API:er och funktioner. Lösningsutforskarens verktygsfönster innehåller till exempel en trädbaserad vy över det aktuella projektet/lösningen/mappen och ger enkla gester för att öppna, byta namn på och skapa filer.

Verktygsfönster är eninstans, vilket innebär att endast en instans av verktygsfönstret kan vara öppen i taget. När ett verktygsfönster stängs i IDE är det synligt dolt och är inte helt stängt och bortskaffas som dokument.

Kom igång

Kom igång genom att följa självstudiekursen skapa ditt första tillägg.

Arbeta med Verktygsfönster

Den här guiden är utformad för att täcka de vanligaste användarscenarierna när du arbetar med Verktyg Windows:

Skapa ett verktygsfönster

Att skapa ett verktygsfönster med den nya utökningsmodellen är lika enkelt som att utöka basklassen ToolWindow och pryda klassen med attributet VisualStudioContribution.

[VisualStudioContribution]
public class MyToolWindow : ToolWindow

ToolWindow-attribut

Den ToolWindow abstrakta klassen kräver implementeringen av konfigurationen ToolWindowConfiguration , som har några egenskaper som du bör bekanta dig med:

Parameter Typ Krävs Beskrivning Standardvärde
Placering Placering av verktygsfönster Nej Den plats i Visual Studio där verktygsfönstret ska öppnas första gången. ToolWindowPlacement.DockedTo tillåter dockning av verktygsfönstret till ett GUID som matchar ett gammalt VSIX-verktygsfönster-ID. Läs mer om ToolWindowPlacement. ToolWindowPlacement.Floating
DockDirection Docka Nej Riktningen i förhållande till placeringen där verktygsfönstret ska dockas när det öppnas för första gången. Se Dock. Dock.Ingen
AllowAutoCreation Bool Nej Anger om verktygsfönstret kan skapas automatiskt eller inte. Om den här parametern anges till false innebär det att verktygsfönster som är öppna när Visual Studio stängs inte återställs automatiskt när Visual Studio öppnas igen. true

Exempel

[VisualStudioContribution]
public class MyToolWindow : ToolWindow
{
    public MyToolWindow(VisualStudioExtensibility extensibility)
        : base(extensibility)
    {
        this.Title = "My Tool Window";
    }

    public override ToolWindowConfiguration ToolWindowConfiguration => new()
    {
        Placement = ToolWindowPlacement.Floating,
        DockDirection = Dock.Right,
        AllowAutoCreation = true,
    };

    public override Task<IRemoteUserControl> GetContentAsync(CancellationToken cancellationToken)
    {
        // Create and return a RemoteUserControl
    }
}

Lägga till innehåll i ett verktygsfönster

Eftersom tillägg i VisualStudio.Extensibility kan vara frånkopplade processer från IDE:n kan vi inte direkt använda WPF (Windows Presentation Foundation) som ett presentationslager för innehåll i verktygsfönster. I stället måste du skapa en RemoteUserControl och motsvarande datamall för den kontrollen för att lägga till innehåll i ett verktygsfönster. Även om det finns några enkla exempel nedan rekommenderar vi att du läser dokumentationen för fjärrgränssnittet när du lägger till innehåll i verktygsfönstret.

[VisualStudioContribution]
public class MyToolWindow : ToolWindow
{
    public MyToolWindow(VisualStudioExtensibility extensibility)
        : base(extensibility)
    {
        this.Title = "My Tool Window";
    }

    public override ToolWindowConfiguration ToolWindowConfiguration => new()
    {
        Placement = ToolWindowPlacement.DocumentWell,
    };

    public override async Task InitializeAsync(CancellationToken cancellationToken)
    {
        // Do any work here that is needed before creating the control.
    }

    public override Task<IRemoteUserControl> GetContentAsync(CancellationToken cancellationToken)
    {
        return Task.FromResult<IRemoteUserControl>(new MyToolWindowControl());
    }
}

MyToolWindowControl.cs: (Det här är ett exempelfilnamn och bör ha samma namn som datamallfilen)

internal class MyToolWindowControl : RemoteUserControl
{
    public MyToolWindowControl()
        : base(dataContext: null)
    {
    }
}

MyToolWindowControl.xaml: (Detta är ett exempelfilnamn och bör ha samma namn som klassen som härleds från RemoteUserControl)

<DataTemplate xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
              xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
              xmlns:vs="http://schemas.microsoft.com/visualstudio/extensibility/2022/xaml">
    <Label></Label>
</DataTemplate>

Mer information om hur du skapar ett RemoteUserControlfinns i Fjärrgränssnitt.

Skapa ett kommando för att visa ett verktygsfönster

En vanlig mekanism för att visa ett verktygsfönster är att lägga till ett kommando som, när det anropas, visar verktygsfönstret genom att anropa ShellExtensibility.ShowToolWindowAsync().

ShowToolWindowAsync() har en boolesk parameter, activate:

  • När trueär verktygsfönstret både synligt i IDE och givet fokus.
  • När falsevisas verktygsfönstret i IDE, men kan bara visas som en flik i en flikgrupp om andra verktygsfönster är aktiva.

Exempel

[VisualStudioContribution]
public class MyToolWindowCommand : Command
{
    public MyToolWindowCommand(VisualStudioExtensibility extensibility)
        : base(extensibility)
    {
    }
    
    public override CommandConfiguration CommandConfiguration => new("My Tool Window")
    {
        Placements = new[] { CommandPlacement.KnownPlacements.ToolsMenu },
        Icon = new(ImageMoniker.KnownValues.ToolWindow, IconSettings.IconAndText),
    };

    public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
    {
        await this.Extensibility.Shell().ShowToolWindowAsync<MyToolWindow>(activate: true, cancellationToken);
    }
}

Mer information om hur du skapar och använder kommandon finns i kommandodokumenten .

Kontrollera synligheten för ett verktygsfönster

Ett annat sätt att styra synligheten för ett verktygsfönster, förutom att använda kommandon, är att använda regelbaserade aktiveringsbegränsningar. De här begränsningarna gör att verktygsfönster automatiskt kan öppnas när vissa villkor uppfylls och döljas igen när dessa villkor inte längre är tillämpliga.

VerktygWindowVisibleWhenAttribute

Attributet VisibleWhen har några parametrar som du bör bekanta dig med:

Parameter Typ Krävs Beskrivning
Uttryck Sträng Ja En boolesk uttryckssträng som, när den är sann, innebär att kontexten är aktiv och att verktygsfönstret visas.
Termnamn Sträng[] Ja Namnen på de termer som används i uttrycket.
Termvärden Sträng[] Ja Värdena för varje term. Termvärdena måste vara i samma ordning som termnamnmatrisen.

Exempel

// The tool window will be shown if the active document is a .cs file, and
// will be hidden if the active document is any any other type of file.
public override ToolWindowConfiguration ToolWindowConfiguration => new()
{
    VisibleWhen = ActivationConstraint.ClientContext(ClientContextKey.Shell.ActiveSelectionFileName, @"\.cs$"),
};

Mer information om giltiga termvärden finns i Regelbaserade aktiveringsbegränsningar.

Lägga till ett verktygsfält i ett verktygsfönster

Du kan lägga till ett verktygsfält i ett verktygsfönster. Definiera först ett verktygsfält enligt beskrivningen i dokumentationen menyer och verktygsfält:

[VisualStudioContribution]
public static ToolbarConfiguration MyToolbar => new("%MyToolbar.DisplayName%")
{
    Children = [
        ToolbarChild.Command<MyCommand1>(), // Assuming there is a `Command` defined in the extension called `MyCommand1`
        ToolbarChild.Separator,
        ToolbarChild.Command<MyCommand2>(), // Assuming there is a `Command` defined in the extension called `MyCommand2`
    ],
};

Referera sedan till verktygsfältet från verktygsfönstrets konfiguration:

public override ToolWindowConfiguration ToolWindowConfiguration => new()
{
    ...
    Toolbar = new(MyToolbar),
};

Nästa steg

Läs mer om hur fjärrgränssnittet fungerar i VisualStudio.Extensibility-ramverket.

Verktygsfönstrets innehåll skapas med WPF, så se WPF-dokumentationen för vägledning.

Se ToolWindow-exemplet för ett fullständigt exempel på hur du skapar ett tillägg med ett verktygsfönster.