mirror of https://github.com/github/awesome-copilot.git synced 2026-02-20 10:25:13 +00:00

Files

Mads Kristensen d27f4e8ed2 Add guidelines for Visual Studio extension development using Community.VisualStudio.Toolkit

2026-01-05 16:15:24 -08:00

20 KiB

Raw Blame History

description, applyTo

description	applyTo
Guidelines for Visual Studio extension (VSIX) development using Community.VisualStudio.Toolkit	*/.cs, */.vsct, */.xaml, **/source.extension.vsixmanifest

Visual Studio Extension Development with Community.VisualStudio.Toolkit

Scope

These instructions apply ONLY to Visual Studio extensions using Community.VisualStudio.Toolkit.

Verify the project uses the toolkit by checking for:

Community.VisualStudio.Toolkit.* NuGet package reference
ToolkitPackage base class (not raw AsyncPackage)
BaseCommand<T> pattern for commands

If the project uses raw VSSDK (AsyncPackage directly) or the new VisualStudio.Extensibility model, do not apply these instructions.

Goals

Generate async-first, thread-safe extension code
Use toolkit abstractions (VS.* helpers, BaseCommand<T>, BaseOptionModel<T>)
Ensure all UI respects Visual Studio themes
Follow VSSDK and VSTHRD analyzer rules
Produce testable, maintainable extension code

Example Prompt Behaviors

✅ Good Suggestions

"Create a command that opens the current file's containing folder using BaseCommand<T>"
"Add an options page with a boolean setting using BaseOptionModel<T>"
"Write a tagger provider for C# files that highlights TODO comments"
"Show a status bar progress indicator while processing files"

❌ Avoid

Suggesting raw AsyncPackage instead of ToolkitPackage
Using OleMenuCommandService directly instead of BaseCommand<T>
Creating WPF elements without switching to UI thread first
Using .Result, .Wait(), or Task.Run for UI work
Hardcoding colors instead of using VS theme colors

Project Structure

src/
├── Commands/           # Command handlers (menu items, toolbar buttons)
├── Options/            # Settings/options pages
├── Services/           # Business logic and services
├── Tagging/            # ITagger implementations (syntax highlighting, outlining)
├── Adornments/         # Editor adornments (IntraTextAdornment, margins)
├── QuickInfo/          # QuickInfo/tooltip providers
├── SuggestedActions/   # Light bulb actions
├── Handlers/           # Event handlers (format document, paste, etc.)
├── Resources/          # Images, icons, license files
├── source.extension.vsixmanifest  # Extension manifest
├── VSCommandTable.vsct            # Command definitions (menus, buttons)
├── VSCommandTable.cs              # Auto-generated command IDs
└── *Package.cs                    # Main package class

Community.VisualStudio.Toolkit Patterns

Global Usings

Extensions using the toolkit should have these global usings in the Package file:

global using System;
global using Community.VisualStudio.Toolkit;
global using Microsoft.VisualStudio.Shell;
global using Task = System.Threading.Tasks.Task;

Package Class

[PackageRegistration(UseManagedResourcesOnly = true, AllowsBackgroundLoading = true)]
[InstalledProductRegistration(Vsix.Name, Vsix.Description, Vsix.Version)]
[ProvideMenuResource("Menus.ctmenu", 1)]
[Guid(PackageGuids.YourExtensionString)]
[ProvideOptionPage(typeof(OptionsProvider.GeneralOptions), Vsix.Name, "General", 0, 0, true, SupportsProfiles = true)]
public sealed class YourPackage : ToolkitPackage
{
    protected override async Task InitializeAsync(CancellationToken cancellationToken, IProgress<ServiceProgressData> progress)
    {
        await this.RegisterCommandsAsync();
    }
}

Commands

Commands use the [Command] attribute and inherit from BaseCommand<T>:

[Command(PackageIds.YourCommandId)]
internal sealed class YourCommand : BaseCommand<YourCommand>
{
    protected override async Task ExecuteAsync(OleMenuCmdEventArgs e)
    {
        // Command implementation
    }

    // Optional: Control command state (enabled, checked, visible)
    protected override void BeforeQueryStatus(EventArgs e)
    {
        Command.Checked = someCondition;
        Command.Enabled = anotherCondition;
    }
}

Options Pages

internal partial class OptionsProvider
{
    [ComVisible(true)]
    public class GeneralOptions : BaseOptionPage<General> { }
}

public class General : BaseOptionModel<General>
{
    [Category("Category Name")]
    [DisplayName("Setting Name")]
    [Description("Description of the setting.")]
    [DefaultValue(true)]
    public bool MySetting { get; set; } = true;
}

MEF Components

Tagger Providers

Use [Export] and appropriate [ContentType] attributes:

[Export(typeof(IViewTaggerProvider))]
[ContentType("CSharp")]
[ContentType("Basic")]
[TagType(typeof(IntraTextAdornmentTag))]
[TextViewRole(PredefinedTextViewRoles.Document)]
internal sealed class YourTaggerProvider : IViewTaggerProvider
{
    [Import]
    internal IOutliningManagerService OutliningManagerService { get; set; }

    public ITagger<T> CreateTagger<T>(ITextView textView, ITextBuffer buffer) where T : ITag
    {
        if (textView == null || !(textView is IWpfTextView wpfTextView))
            return null;

        if (textView.TextBuffer != buffer)
            return null;

        return wpfTextView.Properties.GetOrCreateSingletonProperty(
            () => new YourTagger(wpfTextView)) as ITagger<T>;
    }
}

QuickInfo Sources

[Export(typeof(IAsyncQuickInfoSourceProvider))]
[Name("YourQuickInfo")]
[ContentType("code")]
[Order(Before = "Default Quick Info Presenter")]
internal sealed class YourQuickInfoSourceProvider : IAsyncQuickInfoSourceProvider
{
    public IAsyncQuickInfoSource TryCreateQuickInfoSource(ITextBuffer textBuffer)
    {
        return textBuffer.Properties.GetOrCreateSingletonProperty(
            () => new YourQuickInfoSource(textBuffer));
    }
}

Suggested Actions (Light Bulb)

[Export(typeof(ISuggestedActionsSourceProvider))]
[Name("Your Suggested Actions")]
[ContentType("text")]
internal sealed class YourSuggestedActionsSourceProvider : ISuggestedActionsSourceProvider
{
    public ISuggestedActionsSource CreateSuggestedActionsSource(ITextView textView, ITextBuffer textBuffer)
    {
        return new YourSuggestedActionsSource(textView, textBuffer);
    }
}

Threading Guidelines

Always switch to UI thread for WPF operations

await ThreadHelper.JoinableTaskFactory.SwitchToMainThreadAsync(cancellationToken);
// Now safe to create/modify WPF elements

Background work

ThreadHelper.JoinableTaskFactory.RunAsync(async () =>
{
    await ThreadHelper.JoinableTaskFactory.SwitchToMainThreadAsync();
    await VS.Commands.ExecuteAsync("View.TaskList");
});

VSSDK & Threading Analyzer Rules

Extensions should enforce these analyzer rules. Add to .editorconfig:

dotnet_diagnostic.VSSDK*.severity = error
dotnet_diagnostic.VSTHRD*.severity = error

Performance Rules

ID	Rule	Fix
VSSDK001	Derive from `AsyncPackage`	Use `ToolkitPackage` (derives from AsyncPackage)
VSSDK002	`AllowsBackgroundLoading = true`	Add to `[PackageRegistration]`

Threading Rules (VSTHRD)

ID	Rule	Fix
VSTHRD001	Avoid `.Wait()`	Use `await`
VSTHRD002	Avoid `JoinableTaskFactory.Run`	Use `RunAsync` or `await`
VSTHRD010	COM calls require UI thread	`await ThreadHelper.JoinableTaskFactory.SwitchToMainThreadAsync()`
VSTHRD100	No `async void`	Use `async Task`
VSTHRD110	Observe async results	`await task;` or suppress with pragma

Visual Studio Theming

All UI must respect VS themes (Light, Dark, Blue, High Contrast)

WPF Theming with Environment Colors

<!-- MyControl.xaml -->
<UserControl x:Class="MyExt.MyControl"
             xmlns:vsui="clr-namespace:Microsoft.VisualStudio.PlatformUI;assembly=Microsoft.VisualStudio.Shell.15.0">
    <Grid Background="{DynamicResource {x:Static vsui:EnvironmentColors.ToolWindowBackgroundBrushKey}}">
        <TextBlock Foreground="{DynamicResource {x:Static vsui:EnvironmentColors.ToolWindowTextBrushKey}}"
                   Text="Hello, themed world!" />
    </Grid>
</UserControl>

Toolkit Auto-Theming (Recommended)

The toolkit provides automatic theming for WPF UserControls:

<UserControl x:Class="MyExt.MyUserControl"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:toolkit="clr-namespace:Community.VisualStudio.Toolkit;assembly=Community.VisualStudio.Toolkit"
             toolkit:Themes.UseVsTheme="True">
    <!-- Controls automatically get VS styling -->
</UserControl>

For dialog windows, use DialogWindow:

<platform:DialogWindow
    x:Class="MyExt.MyDialog"
    xmlns:platform="clr-namespace:Microsoft.VisualStudio.PlatformUI;assembly=Microsoft.VisualStudio.Shell.15.0"
    xmlns:toolkit="clr-namespace:Community.VisualStudio.Toolkit;assembly=Community.VisualStudio.Toolkit"
    toolkit:Themes.UseVsTheme="True">
</platform:DialogWindow>

Common Theme Color Tokens

Category	Token	Usage
Background	`EnvironmentColors.ToolWindowBackgroundBrushKey`	Window/panel background
Foreground	`EnvironmentColors.ToolWindowTextBrushKey`	Text
Command Bar	`EnvironmentColors.CommandBarTextActiveBrushKey`	Menu items
Links	`EnvironmentColors.ControlLinkTextBrushKey`	Hyperlinks

Theme-Aware Icons

Use KnownMonikers from the VS Image Catalog for theme-aware icons:

public ImageMoniker IconMoniker => KnownMonikers.Settings;

In VSCT:

<Icon guid="ImageCatalogGuid" id="Settings"/>
<CommandFlag>IconIsMoniker</CommandFlag>

Common VS SDK APIs

VS Helper Methods (Community.VisualStudio.Toolkit)

// Status bar
await VS.StatusBar.ShowMessageAsync("Message");
await VS.StatusBar.ShowProgressAsync("Working...", currentStep, totalSteps);

// Solution/Projects
Solution solution = await VS.Solutions.GetCurrentSolutionAsync();
IEnumerable<SolutionItem> items = await VS.Solutions.GetActiveItemsAsync();
bool isOpen = await VS.Solutions.IsOpenAsync();

// Documents
DocumentView docView = await VS.Documents.GetActiveDocumentViewAsync();
string text = docView?.TextBuffer?.CurrentSnapshot.GetText();
await VS.Documents.OpenAsync(fileName);
await VS.Documents.OpenInPreviewTabAsync(fileName);

// Commands
await VS.Commands.ExecuteAsync("View.TaskList");

// Settings
await VS.Settings.OpenAsync<OptionsProvider.GeneralOptions>();

// Messages
await VS.MessageBox.ShowAsync("Title", "Message");
await VS.MessageBox.ShowErrorAsync("Extension Name", ex.ToString());

// Events
VS.Events.SolutionEvents.OnAfterOpenProject += OnAfterOpenProject;
VS.Events.DocumentEvents.Saved += OnDocumentSaved;

Working with Settings

// Read settings synchronously
var value = General.Instance.MyOption;

// Read settings asynchronously
var general = await General.GetLiveInstanceAsync();
var value = general.MyOption;

// Write settings
General.Instance.MyOption = newValue;
General.Instance.Save();

// Or async
general.MyOption = newValue;
await general.SaveAsync();

// Listen for settings changes
General.Saved += OnSettingsSaved;

Text Buffer Operations

// Get snapshot
ITextSnapshot snapshot = textBuffer.CurrentSnapshot;

// Get line
ITextSnapshotLine line = snapshot.GetLineFromLineNumber(lineNumber);
string lineText = line.GetText();

// Create tracking span
ITrackingSpan trackingSpan = snapshot.CreateTrackingSpan(span, SpanTrackingMode.EdgeInclusive);

// Edit buffer
using (ITextEdit edit = textBuffer.CreateEdit())
{
    edit.Replace(span, newText);
    edit.Apply();
}

// Insert at caret position
DocumentView docView = await VS.Documents.GetActiveDocumentViewAsync();
if (docView?.TextView != null)
{
    SnapshotPoint position = docView.TextView.Caret.Position.BufferPosition;
    docView.TextBuffer?.Insert(position, "text to insert");
}

VSCT Command Table

Menu/Command Structure

<Commands package="YourPackage">
  <Menus>
    <Menu guid="YourPackage" id="SubMenu" type="Menu">
      <Parent guid="YourPackage" id="MenuGroup"/>
      <Strings>
        <ButtonText>Menu Name</ButtonText>
        <CommandName>Menu Name</CommandName>
        <CanonicalName>.YourExtension.MenuName</CanonicalName>
      </Strings>
    </Menu>
  </Menus>

  <Groups>
    <Group guid="YourPackage" id="MenuGroup" priority="0x0600">
      <Parent guid="guidSHLMainMenu" id="IDM_VS_CTXT_CODEWIN"/>
    </Group>
  </Groups>

  <Buttons>
    <Button guid="YourPackage" id="CommandId" type="Button">
      <Parent guid="YourPackage" id="MenuGroup"/>
      <Icon guid="ImageCatalogGuid" id="Settings"/>
      <CommandFlag>IconIsMoniker</CommandFlag>
      <CommandFlag>DynamicVisibility</CommandFlag>
      <Strings>
        <ButtonText>Command Name</ButtonText>
        <CanonicalName>.YourExtension.CommandName</CanonicalName>
      </Strings>
    </Button>
  </Buttons>
</Commands>

<Symbols>
  <GuidSymbol name="YourPackage" value="{guid-here}">
    <IDSymbol name="MenuGroup" value="0x0001"/>
    <IDSymbol name="CommandId" value="0x0100"/>
  </GuidSymbol>
</Symbols>

Best Practices

1. Performance

Check file/buffer size before processing large documents
Use NormalizedSnapshotSpanCollection for efficient span operations
Cache parsed results when possible
Use ConfigureAwait(false) in library code

// Skip large files
if (buffer.CurrentSnapshot.Length > 150000)
    return null;

2. Error Handling

Wrap external operations in try-catch
Log errors appropriately
Never let exceptions crash VS

try
{
    // Operation
}
catch (Exception ex)
{
    await ex.LogAsync();
}

3. Disposable Resources

Implement IDisposable on taggers and other long-lived objects
Unsubscribe from events in Dispose

public void Dispose()
{
    if (!_isDisposed)
    {
        _buffer.Changed -= OnBufferChanged;
        _isDisposed = true;
    }
}

4. Content Types

Common content types for [ContentType] attribute:

"text" - All text files
"code" - All code files
"CSharp" - C# files
"Basic" - VB.NET files
"CSS", "LESS", "SCSS" - Style files
"TypeScript", "JavaScript" - Script files
"HTML", "HTMLX" - HTML files
"XML" - XML files
"JSON" - JSON files

5. Images and Icons

Use KnownMonikers from the VS Image Catalog:

public ImageMoniker IconMoniker => KnownMonikers.Settings;