TagHelperCollection Part 2: Mechanical Updates by DustinCampbell · Pull Request #12505 · dotnet/razor

DustinCampbell · 2025-11-18T21:12:02Z

Warning

This pull request contains breaking changes for the RazorSdk. Once this is merged and flows to the VMR, dotnet/dotnet@9a7e708 will need to be cherry-picked to resolve build breaks in src/sdk/src/RazorSdk.

These commits represent the (mostly) mechanical changes needed to integrate TagHelperCollection across the Razor code base. Most references to ImmutableArrary<TagHelperDescriptor>, IReadOnlyList<TagHelperDescriptor>, IEnumerable<TagHelperDescriptor>, and TagHelperDescriptor[] have been replaced with TagHelperCollection. This is by far the largest of the TagHelperCollection pull requests.

While most of the commits contain mechanical changes across the code base, there are few that include more substantial work that require a bit more scrutiny:

Update RenameService to remove ImmutableArray<TagHelperDescriptor> (fa3ad2b)
This includes a fair amount of refactoring in RenameService to fix bugs found when moving to TagHelperCollection.
Update TagHelperFacts to use TagHelperCollection
Extra work was done in DirectiveAttributeComplationItemProvider to clean up a bit following Better handle parameter attribute directive completion #12473.

CI Build: https://dev.azure.com/dnceng/internal/_build/results?buildId=2842165&view=results
Toolset Run: https://dev.azure.com/dnceng/internal/_build/results?buildId=2842237&view=results

src/Razor/src/Microsoft.CodeAnalysis.Razor.Workspaces/Rename/RenameService.cs

...or/src/Microsoft.VisualStudio.LanguageServices.Razor/Discovery/OutOfProcTagHelperResolver.cs

src/Razor/src/Microsoft.CodeAnalysis.Razor.Workspaces/TagHelperFacts.cs

...or.Workspaces/Completion/DirectiveAttributeCompletionItemProvider.DefaultCommitCharacters.cs

ToddGrun · 2025-11-19T23:03:25Z

...crosoft.CodeAnalysis.Razor.Workspaces/Completion/DirectiveAttributeCompletionItemProvider.cs

+        var descriptionInfo = BoundAttributeDescriptionInfo.From(attribute, isIndexer, attribute.Parent.TypeName);

-        if (!TryAddCompletion(attributeDescriptor.Name, descriptionInfo, descriptor, context, RazorCompletionItemKind.DirectiveAttribute, attributeCompletions) && attributeDescriptor.Parameters.Length > 0)
+        var tagHelper = attribute.Parent;


var tagHelper = attribute.Parent;

This is nice, I didn't realize that was available to map back to the TagHelperDescriptor

nit: maybe move up a couple lines so it can be used when setting descriptionInfo

Yeah, I added the Parent property awhile back: #11953

I didn't do a survey of the code base to update everything that could take advantage of Parent. I've been updating code as I see opportunities though. For example...

razor/src/Compiler/Microsoft.CodeAnalysis.Razor.Compiler/src/Language/Intermediate/TagHelperDirectiveAttributeParameterIntermediateNode.cs

Lines 20 to 22 in 80cf794

public BoundAttributeParameterDescriptor BoundAttributeParameter => _match.Parameter.AssumeNotNull();

public BoundAttributeDescriptor BoundAttribute => BoundAttributeParameter.Parent;

public TagHelperDescriptor TagHelper => BoundAttribute.Parent;

...crosoft.CodeAnalysis.Razor.Workspaces/Completion/DirectiveAttributeCompletionItemProvider.cs

| Prelude | [Part 1](#12504) | [Part 2](#12505) | [Part 3](#12506) | [Part 4](#12507) | [Part 5](#12509) | This is a set of support utilities and helpers added as part of the `TagHelperCollection` changes: - Added `InterlockedOperations.Initialize(...)` overloads for lock free initialization with a factory method. (f3686aa) - Added two `LazyValue` structs that use the new `InterlockedOperations.Initialize(...)` overloads. These are useful for lazily initializing a value without extra allocations or locks. (81795f5) - Added `OverloadResolutionPriorityAttribute` polyfill type. (27ab174) - Refactored `TagHelperCache` to extract `CleanableWeakCache<TKey, TValue>`. This caches items as weak references. When the number of items added reaches a configurable threshold, the cache is cleaned up, and any dead weak references are removed. (673a9b5) ---- CI Build: https://dev.azure.com/dnceng/internal/_build/results?buildId=2842136&view=results Toolset Run: https://dev.azure.com/dnceng/internal/_build/results?buildId=2842197&view=results

ToddGrun

| [Prelude](#12503) | Part 1 | [Part 2](#12505) | [Part 3](#12506) | [Part 4](#12507) | [Part 5](#12509) | This pull request represents all new code! It introduces a new immutable collection type, `TagHelperCollection`, that is designed to contain `TagHelperDescriptors`. It is built with the following principles: 1. Guarantee that collections never contain duplicate tag helpers. 2. Collections can be compared efficiently via checksums. 3. Multiple collections can be merged into a single collection efficiently, with minimal array copying. 4. Determining whether a collection contains a tag helper is efficient. > [!TIP] > Since this is all new code, I recommend reviewing commit-by-commit. Each commit represents a cohesive portion of new code. ---- CI Build: https://dev.azure.com/dnceng/internal/_build/results?buildId=2842145&view=results Toolset Run: https://dev.azure.com/dnceng/internal/_build/results?buildId=2842216&view=results

Note: Because ProjectWorkspaceState.TagHelpers now returns a TagHelperCollection, the serialization format needs to be updated.

Note: This fixes a couple of significant rename bugs: 1. TagHelperDescriptor comparison was done be reference ('==') rather than by checksum ('Equals'). So, it was possible for a tag helper not to be found when locating the "associated" tag helper from the "primary". 2. Edits could be produced with duplicate ranges. In addition, refactoring has been performed to avoid unnecessary async state machines and simplify code.

The previous commit added an overload for TagHelperDocumentContext.Create(...) that removes the prefix parameter. Callers that we're previously null or string.Empty should call the new overload.

…c in source generator (#12506) | [Prelude](#12503) | [Part 1](#12504) | [Part 2](#12505) | Part 3 | [Part 4](#12507) | [Part 5](#12509) | This is a relatively small change to remove LINQ from the Razor source generator and use `TagHelperCollection` when checking for added/removed tag helpers. ---- CI Build: https://dev.azure.com/dnceng/internal/_build/results?buildId=2842169&view=results Toolset Run: https://dev.azure.com/dnceng/internal/_build/results?buildId=2842240&view=results

| [Prelude](#12503) | [Part 1](#12504) | [Part 2](#12505) | [Part 3](#12506) | Part 4 | [Part 5](#12509) | > [!WARNING] > This pull request contains breaking changes for the RazorSdk. Once this is merged and flows to the VMR, dotnet/dotnet@dc17a09 will need to be cherry-picked to resolve build breaks in `src/sdk/src/RazorSdk`. Previously, tag helpers were discovered by `ITagHelperDescriptorProvider`. Each provider was responsible for walking a compilation's assemblies and producing `TagHelperDescriptors` from the types within. This change inverts the tag helper discovery process by introducing `ITagHelperDiscoveryService` and moving the tag helper construction logic into a set of `TagHelperProducers`. The `ITagHelperDiscoveryService` performs a single walk of the compilation or assembly and calls the producers as needed. Importantly, the new process allows a more expansive cache to be maintained. There is now a per-assembly cache that holds onto `TagHelperCollection` instances. The old cache that was owned by providers via `TagHelperCollector` has been removed. To complete this change, `ITagHelperDescriptorProvider` and related types have been _deleted_. ---- CI Build: https://dev.azure.com/dnceng/internal/_build/results?buildId=2842196&view=results Toolset Run: https://dev.azure.com/dnceng/internal/_build/results?buildId=2842249&view=results

…xt (#12509) | [Prelude](#12503) | [Part 1](#12504) | [Part 2](#12505) | [Part 3](#12506) | [Part 4](#12507) | Part 5 | This change introduces a weak cache for `TagHelperDocumentContext` keyed by the tag helper prefix string and `TagHelperCollection` checksum. This helps avoid creating new `TagHelperBinders` for the same set of tag helpers, since `TagHelperBinder` is expensive to create. ---- CI Build: https://dev.azure.com/dnceng/internal/_build/results?buildId=2842228&view=results Toolset Run: https://dev.azure.com/dnceng/internal/_build/results?buildId=2842250&view=results

DustinCampbell requested a review from a team as a code owner November 18, 2025 21:12

davidwengier approved these changes Nov 19, 2025

View reviewed changes

chsienki approved these changes Nov 19, 2025

View reviewed changes