建立 Visual Studio 工具視窗

發行項
03/01/2024

工具視窗是將複雜的 UI 和互動新增至 Visual Studio 的方法。它們通常會提供使用者易用的方式來與各種 API 和功能互動。例如，[方案總管] 工具視窗提供目前專案/方案/資料夾的樹狀檢視，並提供開啟、重新命名和建立檔案的簡單操作。

工具視窗是單一執行個體，這表示一次只能開啟 [工具視窗] 的一個執行個體。關閉 IDE 的 [工具視窗] 時，它只是隱藏，而不是像文件一樣被完全關閉和處置。

開始使用

若要開始使用，請遵循建立您的第一個擴充程式教學課程。

使用 [工具視窗]

本指南介紹了使用 [工具視窗] 時的主要使用者案例：

建立工具視窗
將內容新增至工具視窗
建立命令以顯示工具視窗
控制工具視窗的可見度

建立工具視窗

使用新的 [擴充性模型] 建立工具視窗，就像擴充基類 ToolWindow 一樣簡單，並使用 VisualStudioContribution 屬性裝飾您的類別。

[VisualStudioContribution]
public class MyToolWindow : ToolWindow

ToolWindow 屬性

ToolWindow 抽象類別需要實作 ToolWindowConfiguration 組態，此組態有一些您應該熟悉的屬性：

參數	類型	必要	描述	預設值
放置	ToolWindowPlacement	No	Visual Studio 中應該第一次開啟工具視窗的位置。 `ToolWindowPlacement.DockedTo` 允許將工具視窗停駐到符合舊 VSIX 樣式工具視窗識別碼的 GUID。深入了解 ToolWindowPlacement。	ToolWindowPlacement.Floating
DockDirection	固定	No	相對於工具視窗第一次開啟時應停駐的位置方向。請參閱停駐。	Dock.None
AllowAutoCreation	Bool	No	指定是否可以自動建立工具視窗。將此設定為 false，表示當 Visual Studio 關閉時開啟的工具視窗，不會在 Visual Studio 再次開啟時自動還原。	`true`

範例

[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
    }
}

將內容新增至工具視窗

由於 VisualStudio.Extensibility 中的擴充功能可能來自 IDE 的跨處理序，因此我們不能直接使用 WPF 作為 [工具視窗] 中內容的表示層。相反地，將內容新增至工具視窗需要建立 RemoteUserControl 和該控制項的對應資料範本。雖然下面有一些簡單的範例，但建議您在新增工具視窗內容時閱讀遠端 UI 文件。

[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：(這是範例檔案名稱，應該與資料範本檔案的名稱相同)

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

MyToolWindowControl.xaml (這是範例檔案名稱，應該與衍生自 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>

有關建立 RemoteUserControl 的詳細資訊，請參閱遠端 UI。

建立命令以顯示工具視窗

顯示工具視窗的常見機制是新增命令，該命令在叫用時會呼叫 ShellExtensibility.ShowToolWindowAsync() 來顯示工具視窗。

ShowToolWindowAsync() 具有布林值參數，activate：

當 true 時，工具視窗同時顯示於 IDE 和提供焦點。
當 false 時，工具視窗會顯示在 IDE 中，但如果其他工具視窗處於作用中狀態，則只能在索引標籤群組中顯示為索引標籤。

範例

[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);
    }
}

請參閱命令文件，以深入了解如何建立和使用命令。

控制工具視窗的可見度

除了使用命令之外，另一種控制工具視窗可見度的方法，是使用以規則為基礎的啟用條件約束。這可讓工具視窗在符合特定條件時自動開啟，並在不再適用這些條件時再次隱藏。

ToolWindowVisibleWhenAttribute

VisibleWhen 屬性有一些您應該熟悉的參數：

參數	類型	必要	描述
運算式	String	Yes	布林運算式字串，若為 true，則表示內容為使用中，而且會顯示工具視窗。
TermNames	String[]	Yes	運算式中使用的詞彙名稱。
TermValues	String[]	Yes	每個詞彙的值。詞彙值必須與詞彙名稱陣列的順序相同。

範例

// 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$"),
};

如需有效詞彙值的詳細資訊，請參閱以規則為基礎的啟用條件約束。

下一步

請務必閱讀遠端 UI 在 VisualStudio.Extensibility 架構中的運作方式。

工具視窗內容是使用 WPF 建立的，因此請參閱 WPF 文件以取得指引。

如需使用工具視窗建立擴充功能的完整範例，請參閱 ToolWindow 範例。

Share via