dotnet · dotnet-maestro · Oct 29, 2025 · Oct 29, 2025 · Oct 29, 2025 · Oct 30, 2025
diff --git a/src/roslyn/.devcontainer/devcontainer.json b/src/roslyn/.devcontainer/devcontainer.json
@@ -39,7 +39,7 @@
         "omnisharp.useModernNet": true,
         "omnisharp.enableAsyncCompletion": true,
         // ms-dotnettools.csdevkit settings
-        "dotnet.defaultSolution": "Roslyn.sln",
+        "dotnet.defaultSolution": "Roslyn.slnx",
         // ms-vscode.powershell settings
         "powershell.promptToUpdatePowerShell": false,
         "powershell.integratedConsole.showOnStartup": false,

diff --git a/src/roslyn/.github/copilot-instructions.md b/src/roslyn/.github/copilot-instructions.md
@@ -14,7 +14,7 @@
 **Building**:
 - `build.sh` - Full solution build
 - `dotnet build Compilers.slnf` - Compiler-only build  
-- Run `dotnet msbuild <path to csproj> /t:UpdateXlf` when .resx files are modified to update corresponding .xlf files
+- `dotnet msbuild <path to csproj> /t:UpdateXlf` - Update .xlf files when their corresponding .resx file is modified
 
 **Testing**:
 - `test.sh` - Run all tests
@@ -24,7 +24,9 @@
 
 **Formatting**:
 - Whitespace formatting preferences are stored in the `.editorconfig` file
-- Run `dotnet format whitespace -f . --include ` followed by the relative paths to changed .cs and .vb files to apply formatting preferences
+- When running `dotnet format whitespace` use the `--folder .` option followed by `--include <path to file>` to avoid a design-time build
+- Apply formatting preferences to any modified .cs or .vb file
+- **Important**: Blank lines must not contain any whitespace characters (spaces or tabs). This will cause linting errors that must be fixed.
 
 ## Code Patterns
 
@@ -52,21 +54,27 @@ var symbolInfo = semanticModel.GetSymbolInfo(expression);
 - Use `UseExportProvider` for MEF services
 - Test utilities in `Microsoft.CodeAnalysis.Test.Utilities`
 - Language-specific test bases: `CSharpTestBase`, `VisualBasicTestBase`
+- Add `[WorkItem("https://github.com/dotnet/roslyn/issues/issueNumber")]` attribute to tests that fix specific GitHub issues
+- Prefer raw string literals (`"""..."""`) over verbatim strings (`@"..."`) when creating test source code
+- Avoid unnecessary intermediary assertions - tests should do the minimal amount of work to validate just the core issue being addressed
+  - In tests, use concise methods like `.Single()` instead of asserting count and extracting elements
+  - For compiler tests, validate diagnostics (e.g., `comp.VerifyEmitDiagnostics()`) so reviewers can easily see if the code is in error or represents something legal
 
 ## Critical Integration Points
 
-**Language Server Protocol**: `src/LanguageServer/` contains LSP implementation used by VS Code extension
-**ServiceHub**: Remote services (`src/Workspaces/Remote/`) run out-of-process for performance
-**Analyzers**: `src/Analyzers/` for static analysis, separate from `src/RoslynAnalyzers/` (internal tooling)
-**VSIX Packaging**: Multiple deployment targets - `src/VisualStudio/Setup/` for main VS integration
+- **Language Server Protocol**: `src/LanguageServer/` contains LSP implementation used by VS Code extension
+- **ServiceHub**: Remote services (`src/Workspaces/Remote/`) run out-of-process for performance
+- **Analyzers**: `src/Analyzers/` for static analysis, separate from `src/RoslynAnalyzers/` (internal tooling)
+- **VSIX Packaging**: Multiple deployment targets - `src/VisualStudio/Setup/` for main VS integration
 
 ## Key Conventions
 
-**Namespace Strategy**: `Microsoft.CodeAnalysis.[Language].[Area]` (e.g., `Microsoft.CodeAnalysis.CSharp.Formatting`)
-**File Organization**: Group by feature area, separate language-specific implementations
-**Immutability**: All syntax trees, documents, and solutions are immutable - create new instances for changes
-**Cancellation**: Always thread `CancellationToken` through async operations
-**MEF Lifecycle**: Use `[ImportingConstructor]` with obsolete attribute for MEF v2 compatibility
+- **Namespace Strategy**: `Microsoft.CodeAnalysis.[Language].[Area]` (e.g., `Microsoft.CodeAnalysis.CSharp.Formatting`)
+- **File Organization**: Group by feature area, separate language-specific implementations
+- **Immutability**: All syntax trees, documents, and solutions are immutable - create new instances for changes
+- **Cancellation**: Always thread `CancellationToken` through async operations
+- **MEF Lifecycle**: Use `[ImportingConstructor]` with obsolete attribute for MEF v2 compatibility
+- **PROTOTYPE Comments**: Only used to track follow-up work in feature branches and are disallowed in main branch
 
 ## Common Gotchas
 
@@ -82,4 +90,4 @@ var symbolInfo = semanticModel.GetSymbolInfo(expression);
 - `docs/contributing/Building, Debugging, and Testing on Unix.md` - Development setup
 - `src/Compilers/Core/Portable/` - Core compiler APIs
 - `src/Workspaces/Core/Portable/` - Workspace object model
-- Solution filters: `Roslyn.sln`, `Compilers.slnf`, `Ide.slnf` for focused builds
+- Solution filters: `Roslyn.slnx`, `Compilers.slnf`, `Ide.slnf` for focused builds
diff --git a/src/roslyn/.github/instructions/Compiler.instructions.md b/src/roslyn/.github/instructions/Compiler.instructions.md
@@ -0,0 +1,96 @@
+# Roslyn Compiler Instructions for AI Coding Agents
+
+---
+applyTo: "src/{Compilers,Dependencies,ExpressionEvaluator,Tools}/**/*.{cs,vb}"
+---
+
+## Architecture Overview
+
+Roslyn follows a **layered compiler architecture**:
+- **Lexer → Parser → Syntax Trees → Semantic Analysis → Lowering/Rewriting → Symbol Tables → Emit**
+- Core abstraction: `Compilation` is immutable and reusable. Create new compilations via `AddSyntaxTrees()`, `RemoveSyntaxTrees()`, `ReplaceSyntaxTree()` for incremental changes
+- **Internal vs Public APIs**: Use `InternalSyntax` namespace for performance-critical parsing; `Microsoft.CodeAnalysis` for public consumption
+
+### Key Directories
+- `src/Compilers/Core/Portable/` - Language-agnostic compiler infrastructure
+- `src/Compilers/CSharp/Portable/` - C# compiler implementation  
+- `src/Compilers/VisualBasic/Portable/` - VB compiler implementation
+- `src/Dependencies/` - High-performance collections (`PooledObjects`, `Threading`)
+- `src/ExpressionEvaluator/` - Debugger expression evaluation (uses special `LexerMode.DebuggerSyntax`)
+- `src/Tools/` - Compiler tooling (BuildBoss, format tools, analyzers)
+
+## Essential Patterns
+
+### Test Structure Convention
+Inherit from language-specific base classes: `CSharpTestBase` for C#, `VisualBasicTestBase` for VB
+```cs
+public class MyTests : CSharpTestBase
+{
+    [Fact]
+    public void TestMethod()
+    {
+        var comp = CreateCompilation(sourceCode);
+        // Test compilation, symbols, diagnostics
+    }
+}
+```
+
+### Memory Management
+- **Avoid LINQ in hot paths** - use manual enumeration or `struct` enumerators
+- **Avoid `foreach` over collections without struct enumerators** 
+- **Use object pools extensively** - see patterns in `src/Dependencies/PooledObjects/`
+- **Prefer `Debug.Assert()` over exceptions** for internal validation
+
+## Build & Test Workflows
+
+### Essential Build Commands
+```powershell
+# Full build (use VS Code tasks when available)
+./build.sh
+
+# Build specific components  
+dotnet build Compilers.slnf                    # Compiler-only build
+dotnet build src/Compilers/CSharp/csc/AnyCpu/  # C# compiler
+
+# Generate compiler code after changes
+dotnet run --file eng/generate-compiler-code.cs
+```
+
+### Testing Strategy
+- **Unit tests**: Test individual compiler phases (lexing, parsing)
+- **Compilation tests**: Create `Compilation` objects and verify symbols/diagnostics
+- **Cross-language patterns**: Many test patterns work for both C# and VB with minor syntax changes
+- **Keep tests focused**: Avoid unnecessary assertions. Tests should do the minimal work necessary to get to the core assertions that validate the issue being addressed. For example, use `Single()` instead of checking counts and then accessing the first element.
+
+## Debugger Integration
+
+**Expression Evaluator** uses special parsing modes:
+- `LexerMode.DebuggerSyntax` for expression evaluation
+- `IsInFieldKeywordContext` flag for context-aware parsing
+- `ConsumeFullText` parameter for complete expression parsing
+
+## MSBuild Integration
+
+Compiler tasks are in `src/Compilers/Core/MSBuildTask/`:
+- `Csc.cs` - C# compiler task
+- `Vbc.cs` - VB compiler task  
+- `ManagedCompiler.cs` - Base compiler task functionality
+
+## Performance Considerations
+
+1. **Lexer/Parser optimizations**: Use `InternalSyntax` types for performance-critical code
+2. **Immutable data structures**: Roslyn heavily uses immutable collections and copy-on-write semantics
+3. **Caching**: `Compilation` objects cache semantic information - reuse when possible
+4. **Threading**: Most compiler operations are thread-safe through immutability
+
+## Symbol Resolution
+
+Navigate the symbol hierarchy:
+```cs
+var compilation = CreateCompilation(source);
+var globalNamespace = compilation.GlobalNamespace;
+var typeSymbol = globalNamespace.GetTypeMembers("MyClass").Single();
+var methodSymbol = typeSymbol.GetMembers("MyMethod").Single();
+```
+
+Symbol equality is complex due to generics and substitution - always test with multiple generic scenarios.
diff --git a/src/roslyn/.github/instructions/IDE.instructions.md b/src/roslyn/.github/instructions/IDE.instructions.md
@@ -0,0 +1,154 @@
+---
+applyTo: "src/{Analyzers,CodeStyle,Features,Workspaces,EditorFeatures,VisualStudio}/**/*.{cs,vb}"
+---
+
+# Roslyn IDE Development Guide
+
+This guide provides essential knowledge for working effectively with Roslyn's IDE-focused codebase.
+
+## Architecture Overview
+
+Roslyn uses a **layered service architecture** built on MEF (Managed Extensibility Framework):
+
+- **Workspaces** (`src/Workspaces/`): Core abstractions - `Workspace`, `Solution`, `Project`, `Document`
+- **Features** (`src/Features/`): Language-agnostic IDE features (refactoring, navigation, completion)
+- **LanguageServer** (`src/LanguageServer/`): Shared LSP protocol implementation and Roslyn LSP executable
+- **EditorFeatures** (`src/EditorFeatures/`): VS Editor integration and text manipulation
+- **VisualStudio** (`src/VisualStudio/`): Visual Studio-specific implementations
+
+### Service Resolution Pattern
+
+```csharp
+// Get workspace services
+var service = workspace.Services.GetRequiredService<IMyWorkspaceService>();
+
+// Get language-specific services  
+var csharpService = workspace.Services.GetLanguageServices(LanguageNames.CSharp)
+    .GetRequiredService<IMyCSharpService>();
+
+// In tests, use ExportProvider directly
+var service = ExportProvider.GetExportedValue<IMyService>();
+```
+
+### MEF Export Patterns
+
+```csharp
+// Workspace service
+[ExportWorkspaceService(typeof(IMyService)), Shared]
+internal class MyService : IMyService { }
+
+// Language service
+[ExportLanguageService(typeof(IMyService), LanguageNames.CSharp), Shared]
+internal class CSharpMyService : IMyService { }
+
+// Always use ImportingConstructor with obsolete warning
+[ImportingConstructor]
+[Obsolete(MefConstruction.ImportingConstructorMessage, error: true)]
+public MyService(IDependency dependency) { }
+```
+
+## Key Development Patterns
+
+### TestAccessor Pattern
+For exposing internal state to tests without making it public:
+
+```csharp
+internal class ProductionClass
+{
+    private int _privateField;
+
+    internal TestAccessor GetTestAccessor() => new(this);
+
+    internal readonly struct TestAccessor
+    {
+        private readonly ProductionClass _instance;
+        internal TestAccessor(ProductionClass instance) => _instance = instance;
+        internal ref int PrivateField => ref _instance._privateField;
+    }
+}
+```
+
+### Diagnostic Analyzer Structure
+```csharp
+[DiagnosticAnalyzer(LanguageNames.CSharp, LanguageNames.VisualBasic)]
+public sealed class MyAnalyzer : DiagnosticAnalyzer
+{
+    private static readonly DiagnosticDescriptor s_rule = new(
+        "MyAnalyzer001", "Title", "Message format", "Category",
+        DiagnosticSeverity.Warning, isEnabledByDefault: true);
+
+    public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics 
+        => ImmutableArray.Create(s_rule);
+
+    public override void Initialize(AnalysisContext context)
+    {
+        context.RegisterSyntaxNodeAction(AnalyzeNode, SyntaxKind.ClassDeclaration);
+    }
+}
+```
+
+## Essential Build & Test Commands
+
+```bash
+# Full build
+.build.sh
+
+# Run specific test project
+dotnet test src/EditorFeatures/Test/
+
+# Build with analyzers
+.build.sh -testUsedAssemblies
+
+# Generate compiler code (if changing syntax)
+dotnet run --file eng/generate-compiler-code.cs
+```
+
+## Working with Tests
+
+### Test Workspace Creation
+```csharp
+[UseExportProvider]
+public class MyTests
+{
+    [Fact]
+    public async Task TestSomething()
+    {
+        var workspace = EditorTestWorkspace.CreateCSharp("class C { }");
+        var document = workspace.Documents.Single();
+        // Test logic here
+    }
+}
+```
+
+### Common Test Utilities
+- `DescriptorFactory.CreateSimpleDescriptor()` - Create test diagnostic descriptors
+- `VerifyCS.VerifyAnalyzerAsync()` - Verify C# analyzer behavior
+- `TestWorkspace.CreateCSharp()` - Create test workspaces
+- `UseExportProviderAttribute` - Required for MEF-dependent tests
+
+## Coding Conventions
+
+### Performance Rules
+- **Avoid LINQ in hot paths** - Use manual loops in compiler/analyzer code
+- **Avoid `foreach` over non-struct enumerators** - Use `for` loops or `.AsSpan()`
+- **Use object pooling** - See `ObjectPool<T>` usage patterns
+- **Prefer `ReadOnlySpan<T>`** over `IEnumerable<T>` for performance-critical APIs
+
+### Naming Conventions
+- Private fields: `_camelCase` 
+- Internal test accessors: `GetTestAccessor()` returning `TestAccessor` struct
+- Diagnostic IDs: Consistent prefixes (RS, CA, IDE followed by numbers)
+- MEF exports: Match interface names without "I" prefix
+
+### Resource Management
+- MEF services are automatically disposed by the container
+- Use `TestAccessor` pattern instead of `internal` accessibility for test-only APIs
+- Always implement `IDisposable` for stateful services
+
+## Common Gotchas
+
+- **ImportingConstructor must be marked `[Obsolete]`** with `MefConstruction.ImportingConstructorMessage`
+- **Use `Contract.ThrowIfNull()`** instead of manual null checks in public APIs
+- **TestAccessor calls are forbidden in production code** - enforced by analyzer RS0043
+- **Language services must be exported with specific language name** - don't use generic exports
+- **Workspace changes must use immutable updates** - call `Workspace.SetCurrentSolution()` appropriately
diff --git a/src/roslyn/.vscode/launch.json b/src/roslyn/.vscode/launch.json
@@ -70,7 +70,27 @@
       "program": "C:/Program Files/Microsoft Visual Studio/2022/Preview/MSBuild/Current/Bin/amd64/MSBuild.exe",
       "args": [
         "-restore",
+        "-p:RoslynCompilerType=Custom",
         "-p:RoslynTargetsPath=${workspaceFolder}/artifacts/bin/Microsoft.Net.Compilers.Toolset.Package/Debug/tasks/net472",
+        "-t:Rebuild",
+      ],
+      // A simple project that can be used to debug the build tasks against.
+      "cwd": "${workspaceFolder}/src/Tools/Source/CompilerGeneratorTools/Source/BoundTreeGenerator",
+      "stopAtEntry": false,
+      "console": "internalConsole"
+    },
+    {
+      "name": "Launch Microsoft.Build.Tasks.CodeAnalysis.dll via MSBuild.exe (netfx bridge)",
+      "type": "clr",
+      "request": "launch",
+      "preLaunchTask": "build toolset",
+      "program": "C:/Program Files/Microsoft Visual Studio/2022/Preview/MSBuild/Current/Bin/amd64/MSBuild.exe",
+      "args": [
+        "-restore",
+        "-p:RoslynCompilerType=Custom",
+        "-p:RoslynTargetsPath=${workspaceFolder}/artifacts/bin/Microsoft.Net.Compilers.Toolset.Package/Debug/tasks/net472",
+        "-p:RoslynTasksAssembly=${workspaceFolder}/artifacts/bin/Microsoft.Net.Compilers.Toolset.Package/Debug/tasks/netcore/binfx/Microsoft.Build.Tasks.CodeAnalysis.Sdk.dll",
+        "-t:Rebuild",
       ],
       // A simple project that can be used to debug the build tasks against.
       "cwd": "${workspaceFolder}/src/Tools/Source/CompilerGeneratorTools/Source/BoundTreeGenerator",
@@ -85,7 +105,9 @@
       "program": "C:/Program Files/Microsoft Visual Studio/2022/Preview/MSBuild/Current/Bin/amd64/MSBuild.exe",
       "args": [
         "-restore",
+        "-p:RoslynCompilerType=Custom",
         "-p:RoslynTargetsPath=${workspaceFolder}/artifacts/bin/Microsoft.Net.Compilers.Toolset.Package/Debug/tasks/netcore",
+        "-t:Rebuild",
       ],
       // A simple project that can be used to debug the build tasks against.
       "cwd": "${workspaceFolder}/src/Tools/Source/CompilerGeneratorTools/Source/BoundTreeGenerator",
@@ -100,7 +122,9 @@
       "program": "dotnet",
       "args": [
         "build",
+        "-p:RoslynCompilerType=Custom",
         "-p:RoslynTargetsPath=${workspaceFolder}/artifacts/bin/Microsoft.Net.Compilers.Toolset.Package/Debug/tasks/netcore",
+        "-t:Rebuild",
       ],
       // A simple project that can be used to debug the build tasks against.
       "cwd": "${workspaceFolder}/src/Tools/Source/CompilerGeneratorTools/Source/BoundTreeGenerator",

diff --git a/src/roslyn/.vscode/settings.json b/src/roslyn/.vscode/settings.json
@@ -33,13 +33,17 @@
     "powershell.startAutomatically": false,
     // ms-azure-devops.azure-pipelines settings
     "azure-pipelines.customSchemaFile": ".vscode/dnceng-schema.json",
-    "dotnet.defaultSolution": "Roslyn.sln",
+    "dotnet.defaultSolution": "Roslyn.slnx",
     "dotnet.completion.showCompletionItemsFromUnimportedNamespaces": true,
     "dotnet.testWindow.disableAutoDiscovery": true,
     "dotnet.testWindow.disableBuildOnRefresh": true,
     "cSpell.words": [
+        "darc",
         "Nerdbank",
         "NETCOREAPP",
+        "renderable",
+        "renderables",
+        "sarif",
         "Unregistration",
         "Unregistrations",
         "Xunit"