Vsixtoolkit

# 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

- **Adhere to `.editorconfig` settings** when present in the repository

Code Style (.editorconfig)

**If an `.editorconfig` file exists in the repository, all generated and modified code MUST follow its rules.**

This includes but is not limited to:

- Indentation style (tabs vs spaces) and size

- Line endings and final newline requirements

- Naming conventions (fields, properties, methods, etc.)

- Code style preferences (`var` usage, expression bodies, braces, etc.)

- Analyzer severity levels and suppressions

Before generating code, check for `.editorconfig` in the repository root and apply its settings. When in doubt, match the style of surrounding code in the file being edited.

.NET Framework and C# Language Constraints

**Visual Studio extensions target .NET Framework 4.8** but can use modern C# syntax (up to C# 14) with constraints imposed by the .NET Framework runtime.

✅ Supported Modern C# Features

- Primary constructors

- File-scoped namespaces

- Global usings

- Pattern matching (all forms)

- Records (with limitations)

- `init` accessors

- Target-typed `new`

- Nullable reference types (annotations only)

- Raw string literals

- Collection expressions

❌ Not Supported (.NET Framework Limitations)

- `Span<T>`, `ReadOnlySpan<T>`, `Memory<T>` (no runtime support)

- `IAsyncEnumerable<T>` (without polyfill packages)

- Default interface implementations

- `Index` and `Range` types (no runtime support for `^` and `..` operators)

- `init`-only setters on structs (runtime limitation)

- Some `System.Text.Json` features

Best Practice

When writing code, prefer APIs available in .NET Framework 4.8. If a modern API is needed, check if a polyfill NuGet package exists (e.g., `Microsoft.Bcl.AsyncInterfaces` for `IAsyncEnumerable<T>`).

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.