Copilot instructions

1---
2applyTo: "src/{Analyzers,CodeStyle,Features,Workspaces,EditorFeatures,VisualStudio,LanguageServer}/**/*.{cs,vb}"
3---
4 
5# Roslyn IDE Development Guide
6 
7## Architecture Overview
8 
9Roslyn uses a **layered service architecture** built on MEF (Managed Extensibility Framework):
10 
11- **Workspaces** (`src/Workspaces/`): Core abstractions — `Workspace`, `Solution`, `Project`, `Document`
12- **Features** (`src/Features/`): Language-agnostic IDE features (refactoring, navigation, completion)
13- **Analyzers** (`src/Analyzers/`): IDE diagnostic analyzers and code fixes (IDE0xxx diagnostics)
14- **CodeStyle** (`src/CodeStyle/`): Code-style analyzer packaging shared with the command-line
15- **LanguageServer** (`src/LanguageServer/`): Shared LSP protocol implementation and Roslyn LSP executable (`roslyn-language-server`)
16- **EditorFeatures** (`src/EditorFeatures/`): VS Editor integration and text manipulation
17- **VisualStudio** (`src/VisualStudio/`): Visual Studio-specific implementations
18 
19### Service Resolution
20```csharp
21// Workspace services
22var service = workspace.Services.GetRequiredService<IMyWorkspaceService>();
23 
24// Language-specific services
25var csharpService = workspace.Services.GetLanguageServices(LanguageNames.CSharp)
26    .GetRequiredService<IMyCSharpService>();
27```
28 
29### MEF Export Patterns
30```csharp
31// Workspace service (language-agnostic)
32[ExportWorkspaceService(typeof(IMyService)), Shared]
33internal class MyService : IMyService { }
34 
35// Language service (per-language — never share across C#/VB)
36[ExportLanguageService(typeof(IMyService), LanguageNames.CSharp), Shared]
37internal class CSharpMyService : IMyService { }
38 
39// Constructor — always include both attributes
40[ImportingConstructor]
41[Obsolete(MefConstruction.ImportingConstructorMessage, error: true)]
42public MyService(IDependency dependency) { }
43```
44 
45## Resource & Localization
46 
47- UI strings live in `.resx` files (e.g., `AnalyzersResources.resx`, `FeaturesResources.resx`, `WorkspacesResources.resx`)
48- Reference via generated designer class: `FeaturesResources.Some_string`
49- For localizable strings: `new LocalizableResourceString(nameof(FeaturesResources.Some_string), FeaturesResources.ResourceManager, typeof(FeaturesResources))`
50- After modifying `.resx` files, run `dotnet msbuild <path to csproj> /t:UpdateXlf` to update `.xlf` localization files
51 
52## Analyzers & Code Fixes (IDE0xxx)
53 
54- IDE code-style analyzers inherit from `AbstractBuiltInCodeStyleDiagnosticAnalyzer` — not raw `DiagnosticAnalyzer`
55- Always provide a `FixAllProvider` for code fixes (typically `WellKnownFixAllProviders.BatchFixer`)
56- Diagnostic ID constants live in `src/Analyzers/Core/Analyzers/IDEDiagnosticIds.cs`
57 
58## Out-of-Process (OOP) Services
59 
60- ServiceHub components live under `src/Workspaces/Remote/` and have special deployment considerations for .NET Core vs .NET Framework — keep both targets in mind when changing remote services
61 
62## Key Development Patterns
63 
64### TestAccessor Pattern
65Expose internal state to tests without making it public:
66```csharp
67internal class ProductionClass
68{
69    private int _privateField;
70 
71    internal TestAccessor GetTestAccessor() => new(this);
72 
73    internal readonly struct TestAccessor
74    {
75        private readonly ProductionClass _instance;
76        internal TestAccessor(ProductionClass instance) => _instance = instance;
77        internal ref int PrivateField => ref _instance._privateField;
78    }
79}
80```
81**TestAccessor calls are forbidden in production code** — enforced by analyzer RS0043.
82 
83### SyntaxGenerator (Language-Agnostic Code Generation)
84Use `SyntaxGenerator` to generate code without language-specific knowledge:
85```csharp
86var generator = SyntaxGenerator.GetGenerator(document);
87var methodDecl = generator.MethodDeclaration("MyMethod", ...);
88```
89 
90## Coding Conventions
91 
92- **Private fields**: `_camelCase`
93- **Naming**: MEF exports match interface names without "I" prefix
94- **Null checks**: Use `Contract.ThrowIfNull()` instead of manual null checks
95- **Immutability**: All `Document`, `Solution`, `Project` instances are immutable — use `With*` methods
96- **Cancellation**: Always thread `CancellationToken` through async operations
97- **Performance**: Avoid LINQ in hot paths, prefer `for` loops or `.AsSpan()`, use `ObjectPool<T>`
98 
99## Common Gotchas
100 
101- **ImportingConstructor must be marked `[Obsolete]`** with `MefConstruction.ImportingConstructorMessage`
102- **Language services must be exported with a specific language name** — don't use generic exports for both C#/VB
103- **Workspace changes must use immutable updates** — `Workspace.SetCurrentSolution()`
104