使用 Remote UI 和 VisualStudio.Extensibility SDK 建立一個可停靠的工具視窗,並帶有資料綁定的介面。
Note
本指南使用 VisualStudio.Extensibility SDK。 如需比較模型,請參閱選擇正確的延伸性模型。
完整範例
完整實作如下:
工具視窗定義:
// Copyright (c) Microsoft. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.
namespace ToolWindowSample;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.VisualStudio.Extensibility;
using Microsoft.VisualStudio.Extensibility.Commands;
using Microsoft.VisualStudio.Extensibility.ToolWindows;
using Microsoft.VisualStudio.RpcContracts.RemoteUI;
/// <summary>
/// A sample tool window.
/// </summary>
[VisualStudioContribution]
public class MyToolWindow : ToolWindow
{
private object? dataContext;
/// <summary>
/// Initializes a new instance of the <see cref="MyToolWindow" /> class.
/// </summary>
public MyToolWindow()
{
this.Title = "My Tool Window";
}
/// <inheritdoc />
public override ToolWindowConfiguration ToolWindowConfiguration => new()
{
Placement = ToolWindowPlacement.DocumentWell,
Toolbar = new ToolWindowToolbar(Toolbar),
};
[VisualStudioContribution]
private static ToolbarConfiguration Toolbar => new("%ToolWindowSample.MyToolWindow.Toolbar.DisplayName%")
{
Children = [ToolbarChild.Command<MyToolbarCommand>()],
};
/// <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));
}
}
開啟工具視窗的指令:
// Copyright (c) Microsoft. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.
namespace ToolWindowSample;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.VisualStudio.Extensibility;
using Microsoft.VisualStudio.Extensibility.Commands;
/// <summary>
/// A sample command for showing a tool window.
/// </summary>
[VisualStudioContribution]
public class MyToolWindowCommand : Command
{
/// <inheritdoc />
public override CommandConfiguration CommandConfiguration => new("%ToolWindowSample.MyToolWindowCommand.DisplayName%")
{
Placements = [CommandPlacement.KnownPlacements.ToolsMenu],
Icon = new(ImageMoniker.KnownValues.ToolWindow, IconSettings.IconAndText),
};
/// <inheritdoc />
public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
{
await this.Extensibility.Shell().ShowToolWindowAsync<MyToolWindow>(activate: true, cancellationToken);
}
}
Tip
請參閱完整可運作範例:ToolWindowSample ↗
相關概念:遠端 UI — 用於工具視窗內容的資料綁定模型, 貢獻與配置 — 工具視窗貢獻的宣告方式
理解這個例子
步驟 1:定義工具視窗類別
延伸ToolWindow並以[VisualStudioContribution]標記:
[VisualStudioContribution]
internal class MyToolWindow : ToolWindow
{
private MyDataModel? dataModel;
public MyToolWindow(VisualStudioExtensibility extensibility)
: base(extensibility)
{
Title = "My Tool Window";
}
public override ToolWindowConfiguration ToolWindowConfiguration => new()
{
Placement = ToolWindowPlacement.DocumentWell,
AllowAutoCreation = true,
};
public override async Task InitializeAsync(CancellationToken cancellationToken)
{
dataModel = new MyDataModel();
await dataModel.LoadAsync(cancellationToken);
}
public override Task<IRemoteUserControl> GetContentAsync(CancellationToken cancellationToken)
{
return Task.FromResult<IRemoteUserControl>(new MyToolWindowControl(dataModel!));
}
}
步驟二:建立資料模型
使用 NotifyPropertyChangedObject、[DataContract] 和 [DataMember] 進行遠端 UI 資料繫結:
[DataContract]
internal class MyDataModel : NotifyPropertyChangedObject
{
private string message = "Hello from the tool window!";
[DataMember]
public string Message
{
get => message;
set => SetProperty(ref message, value);
}
public async Task LoadAsync(CancellationToken cancellationToken)
{
// Load data asynchronously
}
}
步驟 3:建立遠端 UI 控制項
新增一個 RemoteUserControl 類別和一個對應的 XAML 資料範本。
MyToolWindowControl.cs:
internal class MyToolWindowControl : RemoteUserControl
{
public MyToolWindowControl(MyDataModel dataModel)
: base(dataContext: dataModel)
{
}
}
MyToolWindowControl.xaml — 將建構動作設定為 EmbeddedResource (非 Page):
<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">
<StackPanel Margin="10">
<TextBlock Text="{Binding Message}" FontSize="14" />
</StackPanel>
</DataTemplate>
Important
XAML 檔案 必須 使用 EmbeddedResource build 動作。 將其設為 Page 會導致工具視窗顯示為空白。
步驟 4:新增一個指令來顯示工具視窗
[VisualStudioContribution]
internal class ShowMyToolWindowCommand : Command
{
public ShowMyToolWindowCommand(VisualStudioExtensibility extensibility)
: base(extensibility)
{
}
public override CommandConfiguration CommandConfiguration => new("My Tool Window")
{
Placements = [CommandPlacement.KnownPlacements.ViewOtherWindowsMenu],
Icon = new(ImageMoniker.KnownValues.ToolWindow, IconSettings.IconAndText),
};
public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
{
await Extensibility.Shell().ShowToolWindowAsync<MyToolWindow>(activate: true, cancellationToken);
}
}
步驟 5(可選):新增工具列
定義一個工具列,並在 ToolWindowConfiguration 中參照它:
[VisualStudioContribution]
public static ToolbarConfiguration MyToolbar => new("%MyToolbar.DisplayName%")
{
Children = [
ToolbarChild.Command<RefreshCommand>(),
ToolbarChild.Separator,
ToolbarChild.Command<ClearCommand>(),
],
};
public override ToolWindowConfiguration ToolWindowConfiguration => new()
{
Placement = ToolWindowPlacement.DocumentWell,
Toolbar = new(MyToolbar),
};
Tips
✅ DO
- 將 XAML 檔案標記為 EmbeddedResource 建置動作(非頁面)。
- 在 ViewModel 屬性上使用
[DataContract]和[DataMember],以用於遠端 UI。 - 使用
NotifyPropertyChangedObject作為資料模型的基礎。 - 在
InitializeAsync()中初始化資料,在GetContentAsync()中建立 UI。 - 使用
ShowToolWindowAsync<T>(activate: true)顯示 from 指令。
❌ 不要
- 不要直接使用 WPF — 遠端 UI 是處理程序外擴充的必要條件。
- 不要把 XAML 建置動作設為(
Page工具視窗不會渲染)。 - 不要在建構器中創造昂貴的資源——使用
InitializeAsync。
🔧 故障排除
| 徵兆 | 修復 |
|---|---|
| 工具視窗是空的 | 驗證 XAML 建置動作為 EmbeddedResource |
| 資料綁定不會更新 | 確保 ViewModel 繼承 NotifyPropertyChangedObject 且屬性具備 [DataMember] |
| 視窗沒有出現 | 確認指令呼叫是否正確ShowToolWindowAsync |
| 工具列未顯示 | 確認 ToolWindowConfiguration.Toolbar 已設為 |