From 33cf4cd4c7a7aef1f586db0770ce8c274a17dca7 Mon Sep 17 00:00:00 2001 From: David Wengier Date: Mon, 13 Oct 2025 08:30:01 +1100 Subject: [PATCH] Simplify copilot-instructions.md --- .github/copilot-instructions.md | 112 +++++--------------------------- 1 file changed, 18 insertions(+), 94 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 3cf841cda74..4b3f21cb8db 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -8,25 +8,17 @@ This repository implements: - **Razor Compiler**: The core Razor compilation engine and source generators - **Language Server**: LSP-based language services for cross-platform editor support -- **Visual Studio Integration**: Rich editing experience and tooling for Visual Studio +- **Visual Studio Integration**: Rich editing experience and tooling for Visual Studio +- **Visual Studio Code Extension**: Rich editing experience and tooling for Visual Studio - **IDE Tools**: Debugging, IntelliSense, formatting, and other developer productivity features -### Key Components - -| Component | Purpose | Key Projects | -|-----------|---------|--------------| -| **Compiler** | Core Razor compilation and code generation | `Microsoft.AspNetCore.Razor.Language`, `Microsoft.CodeAnalysis.Razor.Compiler` | -| **Language Server** | Cross-platform language services via LSP | `Microsoft.AspNetCore.Razor.LanguageServer` | -| **Visual Studio** | VS-specific tooling and integration | `Microsoft.VisualStudio.RazorExtension`, `Microsoft.VisualStudio.LanguageServices.Razor` | -| **Workspaces** | Project system and document management | `Microsoft.CodeAnalysis.Razor.Workspaces` | - ## Razor Language Concepts When working with this codebase, understand these core Razor concepts: ### File Types and Extensions - `.razor` - Blazor components (client-side and server-side) -- `.cshtml` - Razor views and pages (ASP.NET Core MVC/Pages) +- `.cshtml` - Razor views and pages (ASP.NET Core MVC/Pages) also referred to as "Legacy" in the codebase ### Language Kinds Razor documents contain multiple languages: @@ -35,51 +27,24 @@ Razor documents contain multiple languages: - **HTML markup** - Static HTML and dynamic content - **JavaScript/CSS** - Client-side code within Razor files -### Key Architecture Patterns -- **RazorCodeDocument** - Central document model containing parsed syntax tree and generated outputs -- **Language Server Protocol (LSP)** - Cross-platform editor integration -- **Virtual Documents** - Separate C# and HTML projections for tooling -- **Document Mapping** - Translation between Razor and generated C# positions - ## Development Guidelines -### Code Style and Patterns - -Follow these patterns when contributing: - -```csharp -// ✅ Prefer readonly fields and properties -private readonly ILogger _logger; - -// ✅ Use explicit interface implementations for internal contracts -internal sealed class MyService : IMyService -{ - public void DoWork() { } -} - -// ✅ Use cancellation tokens in async methods -public async Task ProcessAsync(CancellationToken cancellationToken) -{ - // Implementation -} - -// ✅ Follow null-checking patterns -public void Method(string? value) -{ - if (value is null) - { - return; - } - - // Use value here -} -``` +### Coding Patterns + +- Always build and test with `build.sh -test` before submitting PRs, without specifying a project or test filter +- Write clear, concise, and maintainable code +- Always place `[WorkItem]` attributes on tests for tracking +- Prefer immutable collection types and pooled collections where possible +- Use `using` statements for disposable resources +- Ensure proper async/await patterns, avoid `Task.Wait()` ### Testing Patterns +- Add appropriate test coverage for new features - Prefer `TestCode` over plain strings for before/after test scenarios - Prefer raw string literals over verbatim strings - Ideally we test the end user scenario, not implementation details +- Consider cross-platform compatibility by testing path handling and case sensitivity where applicable ### Architecture Considerations @@ -92,55 +57,14 @@ public void Method(string? value) ### Prerequisites - .NET 8.0+ SDK (latest version specified in `global.json`) -- Visual Studio 2022 17.8+ or VS Code with C# extension +- Visual Studio 2026 (Windows) or VS Code with C# extension (Windows, macOS or Linux) - PowerShell (for Windows build scripts) ### Building - `./restore.sh` - Restore dependencies - `./build.sh` - Full build -- `./build.sh -test` - Build and run tests - -### Visual Studio Development -- `./startvs.ps1` - Open Visual Studio with correct environment -- `./build.cmd -deploy` - Build and deploy VS extension for testing - -## Project Structure Navigation - -``` -src/ -├── Compiler/ # Core Razor compilation engine -│ ├── Microsoft.AspNetCore.Razor.Language/ # Core language APIs -│ └── Microsoft.CodeAnalysis.Razor.Compiler/ # Roslyn integration -├── Razor/ # Language server and tooling -│ ├── src/Microsoft.AspNetCore.Razor.LanguageServer/ # LSP implementation -│ ├── src/Microsoft.VisualStudio.RazorExtension/ # VS package -│ └── test/ # Language server tests -└── Shared/ # Common utilities and test helpers -``` +- DO NOT USE `dotnet build` directly -## Debugging and Diagnostics - -### Language Server Debugging -- Use F5 debugging in VS with `Microsoft.VisualStudio.RazorExtension` as startup project -- Check language server logs in VS Output window (Razor Logger Output) - -### Common Issues -- **Performance**: Check document mapping efficiency and async/await usage -- **Cross-platform**: Test path handling and case sensitivity -- **Memory**: Use `using` statements for disposable resources -- **Threading**: Ensure proper async/await patterns, avoid `Task.Wait()` - -## Contributing - -- Follow the [Contributing Guidelines](CONTRIBUTING.md) -- Build and test locally before submitting PRs -- Add appropriate test coverage for new features -- Update documentation for public API changes -- Consider cross-platform compatibility in all changes - -## Useful Resources - -- [ASP.NET Core Razor documentation](https://docs.microsoft.com/aspnet/core/razor-pages) -- [Blazor documentation](https://learn.microsoft.com/en-gb/aspnet/core/blazor/?) -- [Language Server Protocol specification](https://microsoft.github.io/language-server-protocol/) -- [Build from source instructions](docs/contributing/BuildFromSource.md) \ No newline at end of file +### Testing +- `./build.sh -test` - Build and run tests +- DO NOT USE `dotnet test` directly