dotnet / dotnet/docfx

[Bug] Metadata extraction fails with .NET SDK 10.0.2xx — Razor compiler requires Roslyn 5.3.0

Open
#11,046 3 comments 2 reactions 0 assignees View on GitHub
Dominant language
C#
Stars
4.4k
Forks
890
Avg merge
2h 11m
Merged PRs (30d)
10

Description

## DocFx Version

2.78.5

## .NET SDK Versions Tested

| SDK Version | Result |
|-------------|--------|
| 10.0.103 (100-band) | Works |
| 10.0.201 (200-band) | Fails |

## Describe the Bug

`docfx metadata` fails for projects containing Blazor components when running with .NET SDK 10.0.2xx (200-band). The issue does not occur with SDK 10.0.1xx (100-band).

### Root Cause

The Razor compiler analyzer shipped with the 200-band SDK requires Roslyn 5.3.0, but DocFx bundles an older version that cannot load it:

```
warning: FailedToLoadAnalyzer: Failed to load .NET Analyzer.
AnalyzerName: Microsoft.CodeAnalysis.Razor.Compiler
ErrorCode: ReferencesNewerCompiler
ReferencedCompilerVersion: 5.3.0.0
```

Because the Razor source generator fails to load, it does not produce the generated partial classes for `.razor` files. Code-behind files (`.razor.cs`) that override virtual methods from their base class then fail with **CS0115** ("no suitable method found to override"), because the generated partial class — which establishes the inheritance chain via `@inherits` — is missing.

### Affected Components

The failure affects Blazor components that:

1. Declare their base class via `@inherits` in the `.razor` file (standard Blazor pattern)
2. Override virtual or abstract methods from that base class in the `.razor.cs` code-behind

Common overridden methods that trigger CS0115 include `OnInitialized()`, `OnInitializedAsync()`, `SetParametersAsync(ParameterView)`, and custom virtual methods from the component's base class hierarchy.

## To Reproduce

1. Install .NET SDK 10.0.2xx (e.g., 10.0.201)
2. Have a Blazor component library targeting `net10.0`
3. Include components with code-behind files where the `.razor` file uses `@inherits SomeBase` and the `.razor.cs` file overrides virtual methods from that base
4. Run `docfx metadata` on a DocFx config that includes this project

### Example Component Structure

**MyComponent.razor:**
```razor
@namespace MyApp.Components
@inherits MyComponentBase

@ChildContent

```

**MyComponent.razor.cs:**
```csharp
namespace MyApp.Components;

public partial class MyComponent
{
protected override void OnInitialized()
{
// CS0115 because Razor generator didn't run,
// so this partial class has no base class
base.OnInitialized();
}
}
```

### Error Output

```
warning: FailedToLoadAnalyzer: Failed to load .NET Analyzer.
AnalyzerName: Microsoft.CodeAnalysis.Razor.Compiler
ErrorCode: ReferencesNewerCompiler
ReferencedCompilerVersion: 5.3.0.0

error CS0115: 'MyComponent.OnInitialized()': no suitable method found to override
```

### Workaround

Pin the .NET SDK to the 100-band (e.g., `10.0.103`) via `global.json` or CI configuration. The 100-band SDK ships with a Roslyn version that DocFx can still load.

## Expected Behavior

`docfx metadata` should work with all current .NET SDK 10 versions, including the 200-band. DocFx should be updated to support the Roslyn version shipped with the 200-band SDK.

## Related Issues

- #10901 — CS8652 triggered for .NET 10 (DocFx's Roslyn doesn't support C# 14 `field` keyword)
- #10192 — Metadata extraction fails when projects use a newer compiler than DocFx ships with
- dotnet/runtime#120815 — Runtime analyzers target Roslyn 4.14.0 but DocFx bundles 4.12.0

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.