Copilot instructions

1---
2applyTo: "src/Razor/**/*.{cs,vb}"
3---
4 
5# Razor Tooling and Compiler Instructions for AI Coding Agents
6 
7Razor was merged into the Roslyn repo from `dotnet/razor`, and most files keep
8their original sub-tree layout
9(`src/Razor/src/Razor/...`, `src/Razor/src/Compiler/...`, `src/Razor/src/Shared/...`,
10`src/Razor/src/Analyzers/...`).
11 
12## Critical Rules
13 
14- **Bug fixes**: Look for existing code that already handles the scenario before adding new code.
15  The bug is more likely in existing logic than a missing feature.
16- **Helpers**: Review existing helpers (`UsingDirectiveHelper`, `AddUsingsHelper`, etc.)
17  before writing new utility methods. Don't duplicate.
18- **Warning levels**: Track warnings with non-zero `RazorWarningLevel` values in
19  [`docs/razor/warning-levels.md`](../../docs/razor/warning-levels.md), including the diagnostic
20  ID, warning level, exact message, and trigger condition.
21 
22## File Types
23 
24- `.razor` -- Blazor components.
25- `.cshtml` -- Razor views/pages (referred to as "Legacy" in the codebase).
26 
27## Code Patterns
28 
29- **Collections**: Use `ListPool<T>.GetPooledObject(out var list)` and `PooledArrayBuilder<T>`
30  instead of allocating new collections. Prefer immutable collection types.
31- **Positions**: Use `GetRequiredAbsoluteIndex` for converting positions to absolute indexes.
32- **LSP conversions**: `sourceText.GetTextChange(textEdit)` converts LSP `TextEdit` to
33  Roslyn `TextChange`. Reverse: `sourceText.GetTextEdit(change)`. Both live in
34  `src\Razor\src\Razor\src\Microsoft.CodeAnalysis.Razor.Workspaces\Extensions\LspExtensions_SourceText.cs`.
35- **RazorCodeDocument**: Immutable -- every `With*` method creates a new instance passing ALL
36  fields through the constructor. When adding a new field, thread it through every existing
37  `With*` method. Prefer computing derived data via extension methods (e.g.,
38  `GetUnusedDirectives()`) rather than storing computed results as fields.
39- **Razor documents in Roslyn**: Stored as additional documents. Resolve via
40  `solution.GetDocumentIdsWithFilePath(filePath)` then `solution.GetAdditionalDocument(documentId)`.
41- **Remote services**: Place the public stub method (calling `RunServiceAsync`) directly
42  above its private implementation method.
43- **Visual Studio options**: Register Razor Advanced settings in
44  `Microsoft.VisualStudio.RazorExtension\UnifiedSettings\razor.registration.json`, localize
45  their UI text in `VSPackage.resx`, read them through `OptionsStorage`, and add remotely consumed
46  values to `ClientAdvancedSettings` so `IClientSettingsManager` synchronizes changes live.
47 
48## Adding OOP Remote Services
49 
50When adding a new `IRemote*Service` and `Remote*Service`:
51 
521. Interface: `src\Razor\src\Razor\src\Microsoft.CodeAnalysis.Razor.Workspaces\Remote\`
532. Implementation: `src\Razor\src\Razor\src\Microsoft.CodeAnalysis.Remote.Razor\`
543. Register in
55   `src\Razor\src\Razor\src\Microsoft.CodeAnalysis.Razor.Workspaces\Remote\RazorServices.cs`
56   (add to `MessagePackServices` or `JsonServices`).
574. **Add an entry to `eng\targets\RazorServices.props`** (at the Roslyn repo root, not under
58   `src\Razor`):
59   `Include="Microsoft.VisualStudio.Razor.{ShortName}"` with
60   `ClassName="{FullTypeName}+Factory"`. The `ShortName` is your interface name with
61   `IRemote` and `Service` stripped (e.g., `IRemoteFrobulatorService` becomes `Frobulator`).
625. Validate: `dotnet test src\Razor\src\Razor\test\Microsoft.CodeAnalysis.Remote.Razor.UnitTests --filter "FullyQualifiedName~RazorServicesTest"`
63