Razor foundation: Blazor components, Razor Pages and MVC views in the host, the sidecar, VS Code and Zed

[MelbourneDeveloper]

TLDR

.razor and .cshtml files become first-class: the C# inside them answers through the SDK generator's projection, markup structure comes from the bundled Razor compiler, editors get an HTML projection, and VS Code and Zed attach to Razor. The branch also carries the website's video search pages and playable social previews.

Details

Spec and plan

• docs/specs/RAZOR-SPEC.md (new): how the Razor toolchain works; host routing; Razor files as additional documents; the C# projection and its span map; the bundled engine, its three IR capture passes and the markup facts model (typeDiagram); the HTML projection; every feature at Razor positions; Blazor and MVC coverage; F#; editors; degradation; tests.
• docs/plans/RAZOR-PLAN.md (new): Phase 1 (foundation) and Phase 5 (editors) are complete. Phase 2 is partly done; Phases 3, 4 and 6 are next.

Rust host

• LangId::Razor for .razor and .cshtml. It has no tree-sitter grammar, and the C# sidecar owns it.
• For Razor, documentSymbol, foldingRange and linkedEditingRange go to the sidecar (razor.rs, document_symbols::handle_via_sidecar), and selectionRange answers [].
• < and @ are completion triggers. In C# and F# documents they answer null without reaching a sidecar.
• Postfix templates (.if, .foreach, …) never expand in Razor files, where the same text can be markup.
• Razor diagnostics publish under the source sharplsp-razor.
• sharplsp/razor/htmlProjection takes { textDocument } and answers { text }, or null for a file no project lists.

C# sidecar

• Razor files are additional documents. Their text syncs in every framework context, including edits replayed after load.
• The C# projection is the generated document whose #pragma checksum names the file. A verified span map translates positions both ways (RazorProjection, RazorSpanMap).
• Position queries run in the projection and map back (RazorLocations, RazorResults, RazorRenameEdits, RazorCompletionEdits, which turns using into @using). This covers hover, definition, type definition, declaration, references, highlights, completion, signature help, rename, semantic tokens and diagnostics. Hidden scaffolding is dropped.
• The Razor compiler is bundled from the build SDK (RazorCompiler.props, MIT, listed in THIRD-PARTY-NOTICES.md). Each project gets its own engine (RazorEngineSettings, WorkspaceRazorFileSystem, RazorTagHelpers).
• IR capture passes (RazorMarkupCapture, RazorIr) produce the markup facts (RazorMarkup). RazorMarkupSymbols finds the C# symbols behind them.
• The outline, folds and linked tag names come from the facts (RazorStructure).
• The HTML projection is built from the IR (RazorHtmlProjection). Component HTML comments are restored from a second parse (RazorHtmlComments). A WHATWG-state tokenizer finds the markup context at a caret (HtmlMarkupContext).
• RunQueryAsync is one query skeleton shared by documents, projections and markup facts.
• A Razor file never reports a using as unnecessary (CS8019, IDE0005). Markup resolves components through usings that the generated C# never needs, and an import file's usings serve the files below it.
• C#-only solutions pay nothing extra. Rename's Razor reference search runs only when a project lists a Razor file. Mapping a location outside the workspace's documents, such as decompiled source, searches only Razor projects for a projection, so no other project compiles to run its generators.

Editors

• VS Code: syncs razor and aspnetcorerazor files and activates on onLanguage:razor. Markup completion and hover go to the built-in HTML service over the projection (razor-html.ts): the server's items come first, and an HTML hover is used only when the server has none. A new razor end-to-end chunk runs on Ubuntu and Windows.
• Zed: the server attaches to Razor with language id razor.

Fixture: src/sharplsp/tests/fixtures/razor/ is a real solution with four projects: BlazorApp, Widgets (a Razor class library), PagesApp (Razor Pages and MVC) and Domain (F#). Its own Directory.Build.props and .editorconfig keep the repository's build settings and analyzers out. The end-to-end suites copy it to a temp folder together with the repository's global.json. Without that pin, a newer installed SDK's Razor generator needs a newer Roslyn than the sidecar bundles; #399 tracks that limitation, and [RAZOR-ERRORS] describes it.

Website

• Every docs film gets a watch page in each language, an embed page, a 1200x630 social card, a video sitemap entry and robots.txt access, per [WEB-DESIGN-MEDIA-DISCOVERY] in DESIGN-SYSTEM.md.
• Every docs page gets its own description.

lspkit: the pointer moves to main, which ignores the local Deslop index.

Refs #397

How Do The Automated Tests Prove It Works?

Rust end-to-end: razor::test_full_stack_razor_routing_session runs the real host and sidecars over the fixture. It checks that:

• the server advertises ., < and @ as triggers;
• hover on caption inside @bind arrives through the projection;
• the outline of Board.razor reads @page … @code, with Panel as Class nesting Badge, and Add as Method;
• the folds are (6,9) (7,8) (14,24);
• linked editing on <Panel returns both tag names, and a self-closing tag returns none;
• selectionRange answers [];
• the HTML projection keeps every line's width, blanks @Id, @page and @code {, and keeps <Panel and </Panel>;
• the projection is null for Program.cs, and < and @ in Program.cs answer null;
• an edit to Idd publishes CS0103 under sharplsp-razor on line 22, and reverting the edit clears it;
• the session shuts down cleanly.

Rust unit:

• razor::tests::*: markup triggers short-circuit only outside Razor; projections answer text or null; without the sidecar, the projection, linked editing and folding requests fail and name themselves.
• postfix_completion::tests::razor_documents_get_no_postfix_templates: postfix templates never expand in Razor, while the same text in C# offers them.
• diagnostics::tests::razor_files_publish_under_the_razor_source, tree_sitter_parse::tests::razor_and_cshtml_files_are_razor_without_a_grammar, and the Method and Key kinds in document_symbols.

C# sidecar: these run against the built fixture solution in a real MSBuildWorkspace.

• RazorCSharpFeatureTests:
  • Hover_answers_csharp_fragments_with_ranges_in_the_razor_file
  • Definition_lands_in_razor_files_from_razor_and_from_csharp
  • References_and_highlights_cover_every_razor_use_and_drop_scaffolding
  • Signature_help_answers_inside_a_razor_call
  • Diagnostics_map_csharp_errors_into_the_razor_file_and_the_solution_scan
  • Completion_in_an_expression_offers_members_with_edits_in_the_razor_file
  • Rename_of_a_code_block_field_edits_every_razor_use_and_prepares_its_range
  • Semantic_tokens_classify_csharp_fragments_at_their_razor_positions
• Import_files_never_report_their_usings_as_unnecessary and Components_never_report_a_using_their_markup_may_need_as_unnecessary: _Imports.razor, _ViewImports.cshtml and a component using <Virtualize> report no unnecessary using, in the file and in the solution scan. The tag binds through its using, and a C# code-behind file still reports an unused using.
• RazorStructureTests: folds keep their last line, the outline nests components and members, and start and end tag names edit together.
• RazorMarkupEngineTests: components bind from the app and its library; attributes and directive parameters carry their descriptors; RZ10012 appears after an edit; names are found at an offset; an edit made before the workspace loads is replayed into both the facts and the projection.
• RazorCompletionEditsTests: an edit inside a fragment maps back to it; an added using becomes one @using line after the file's own, keeping static and alias spellings and the file's line break; an edit that cannot be placed is dropped.
• RazorMarkupSymbolsTests: component types, parameter and @bind-X properties, and child content resolve, and @onclick, HTML attributes and the generic @bind set nothing.
• RazorLocationsTests: a solution without Razor files compiles nothing to look for a projection.
• RazorHtmlProjectionTests (20 cases) and HtmlMarkupContextTests (36 cases). The tokenizer cases include malformed HTML: after a stray /, a doubled < or a bad </ opening, the next character is reconsumed as the HTML tokenizer does.

These run against in-memory projects (AdhocRazorProject): Razor files as additional documents, MSBuild properties and file metadata in a global analyzer config, and hand-written generator output.

• RazorProjectionTests:
  • the checksum lookup;
  • hidden, fileless, foreign and out-of-range mappings, which never map;
  • carets at a fragment's end;
  • rename edits only listed Razor files whose span holds the old name.
• RazorEngineSettingsTests:
  • settings fallbacks and TargetPath metadata;
  • the engine's file system, including missing files;
  • projects and documents without a path;
  • cancellation;
  • an unreadable file answers null and later requests still work.
• RazorSidecarTests, over the sidecar's real socket: the projection round-trips unsaved text and is null for an unlisted file; the structure requests keep their wire shapes; a malformed payload answers an error and leaves the socket healthy.

VS Code: razor-lsp.test.ts runs on both platforms with these tests:

• a Razor file opens as Razor, and its unsaved edits reach the server;
• the server projects Razor as HTML of the same shape;
• markup completes from the HTML service, and C# from the server;
• markup hovers come from the HTML service when the server has none;
• references to a field in Razor land in its Razor file, never in generated code;
• markup without a projection keeps only the server's answers: an unlisted file gets no HTML items or hover, its projection address reads as empty HTML, and a projection the server refuses is logged and answers nothing.

The lsp chunk (210 tests), the fsharp chunk (122 tests) and the workspace chunk (446 tests) pass with the new middleware.

Zed: the_server_attaches_to_the_csharp_fsharp_and_razor_languages.

Website (desktop and phone): video-discovery.spec.js checks that every docs page shares its film as a playable preview in every language, with unique descriptions. video-watch-pages.spec.js covers the watch pages, embed pages, sitemap and robots.txt.

Coverage of new code: every line the branch adds is hit by a test.

• C# sidecar and Common: 1530 of 1530 added lines. C# coverage rises to 96.39% over 671 tests, and its threshold ratchets to 95.39%.
• razor-html.ts: 160 of 160 lines.
• Rust host: 244 of 244 added lines, from CI's shard coverage.

Real-app check: the host and sidecars were run over a fresh dotnet new blazor app (.NET 10). Every file reports no errors and keeps its shape in the HTML projection. Hover, definition, references, member completion and signature help answer on the template's own code.