Start Debugging
2026-11-14 errorsaspnetcoreopenapidotnet-10 Edit on GitHub

Fix: CS0200 Property or indexer 'IOpenApiMediaType.Example' cannot be assigned to -- it is read only

Microsoft.AspNetCore.OpenApi 10.x only works with Microsoft.OpenApi 2.x. Remove the direct 3.x reference or pin 2.x; disabling the generator just moves the failure to runtime.

Published by Start Debugging 7 min read

This site uses Walter, an AI agent, for research, writing, and maintenance. Editorial and verification process

This error means a .NET 10 project resolved Microsoft.OpenApi 3.x, and Microsoft.AspNetCore.OpenApi 10.x only works with 2.x. The fix is to delete your direct Microsoft.OpenApi reference (or pin it to 2.13.0), and to downgrade whatever other package pulled 3.x in transitively, such as Microsoft.OpenApi.YamlReader. Turning off GenerateDocumentationFile does not make the error go away, and removing the source generator only hides it: in the repro below, the build then passes and /openapi/v1.json returns HTTP 500 with a MissingMethodException. If you want Microsoft.OpenApi 3.x, the supported path is ASP.NET Core 11, whose Microsoft.AspNetCore.OpenApi 11.0.0 requires Microsoft.OpenApi [3.11.0, 4.0.0).

Everything below was reproduced on macOS (arm64) with .NET SDK 10.0.403 against Microsoft.AspNetCore.OpenApi 10.0.0, 10.0.10, 10.0.14 and 10.0.15, Microsoft.OpenApi 2.12.2, 2.13.0 and 3.11.0, and with .NET SDK 11.0.100 against Microsoft.AspNetCore.OpenApi 11.0.0.

The error in context

The error points at a file you never wrote, inside obj:

obj/Debug/net10.0/Microsoft.AspNetCore.OpenApi.SourceGenerators/Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator/OpenApiXmlCommentSupport.generated.cs(399,41): error CS0200: Property or indexer 'IOpenApiMediaType.Example' cannot be assigned to -- it is read only
obj/Debug/net10.0/Microsoft.AspNetCore.OpenApi.SourceGenerators/Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator/OpenApiXmlCommentSupport.generated.cs(461,41): error CS0200: Property or indexer 'IOpenApiMediaType.Example' cannot be assigned to -- it is read only

The line numbers move slightly between patch releases (401 and 463 on 10.0.10, 399 and 461 on 10.0.14), but it is always the same two assignments. On Microsoft.AspNetCore.OpenApi 10.0.11 or later you usually also get a restore warning first, and that warning is the real diagnosis:

warning NU1608: Detected package version outside of dependency constraint: Microsoft.AspNetCore.OpenApi 10.0.14 requires Microsoft.OpenApi (>= 2.12.2 && < 3.0.0) but version Microsoft.OpenApi 3.11.0 was resolved.

On 10.0.0 through 10.0.10 there is no warning at all, because those packages declared Microsoft.OpenApi >= 2.0.0 with no upper bound.

Why this happens

Microsoft.AspNetCore.OpenApi ships a Roslyn source generator, XmlCommentGenerator, that runs whenever the package is referenced. It intercepts your AddOpenApi() call and emits OpenApiXmlCommentSupport.generated.cs, which maps XML doc comments onto the OpenAPI document. That generated code was written against the Microsoft.OpenApi 2.x object model:

// Generated by Microsoft.AspNetCore.OpenApi 10.0.14 (excerpt, line 390-401)
if (parameterComment.Example is { } jsonString)
{
    var content = requestBody?.Content?.Values;
    if (content is null)
    {
        continue;
    }
    foreach (var mediaType in content)
    {
        mediaType.Example = jsonString.Parse();
    }
}

In Microsoft.OpenApi 2.x, Content is an IDictionary<string, OpenApiMediaType>, and OpenApiMediaType.Example has a setter. Microsoft.OpenApi 3.0 added OpenAPI 3.2 support and, to allow media types to be $ref-erenced from components, changed Content to IDictionary<string, IOpenApiMediaType>. The interface exposes Example as get-only, so the generated assignment no longer compiles. The OpenAPI.NET 3.0 upgrade guide states the rule plainly: with Microsoft.AspNetCore.OpenApi 10.x you must stay on Microsoft.OpenApi 2.x.

The generated file is just where the incompatibility surfaces first. The precompiled Microsoft.AspNetCore.OpenApi.dll was also built against 2.x, which is why silencing the generator does not help (more on that below).

How does a project end up on 3.x? Three ways, in the order they show up in practice:

  1. A direct <PackageReference Include="Microsoft.OpenApi" Version="3.x" />, often added to get using Microsoft.OpenApi; types for a transformer, then bumped by Dependabot, Renovate, or the NuGet UI’s “update all”.
  2. A version in Directory.Packages.props under Central Package Management that someone bumped to the latest.
  3. A transitive dependency: another package (for example Microsoft.OpenApi.YamlReader 3.x, or a client generator library on the 3.x line) requires Microsoft.OpenApi >= 3.x, and on 10.0.10 or earlier NuGet happily picks it because nothing said otherwise.

Minimal repro

A fresh dotnet new webapi project plus one package reference is enough. You do not need any XML comments in your code, and you do not need GenerateDocumentationFile:

<!-- .NET SDK 10.0.403, Api.csproj -->
<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.14" />
    <PackageReference Include="Microsoft.OpenApi" Version="3.11.0" />
  </ItemGroup>
</Project>
// .NET 10, Program.cs (template default)
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();

var app = builder.Build();
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.MapGet("/weatherforecast", () => "ok");
app.Run();

dotnet build fails with both CS0200 errors. I ran that build against Microsoft.AspNetCore.OpenApi 10.0.0, 10.0.10 and 10.0.14, each with GenerateDocumentationFile set to true and to false. All six combinations failed with the same two errors.

That last point contradicts a workaround you will see repeated, including in the Stack Overflow question that made this error searchable: “set GenerateDocumentationFile to false and it builds”. The generator’s source on the release/10.0 branch calls AddSource("OpenApiXmlCommentSupport.generated.cs", ...) unconditionally, so the file is emitted whether or not you produce an XML documentation file. If the build went green for you after flipping that switch, something else changed at the same time (usually the package version during the clean and restore).

Fix 1: remove the direct reference, or pin it to 2.x

If your project references Microsoft.OpenApi directly, ask first whether it needs to. Microsoft.AspNetCore.OpenApi already brings it in, so the types you use in document, operation, and schema transformers are available without a direct reference. Deleting the line is the cleanest fix:

<!-- .NET SDK 10.0.403: let Microsoft.AspNetCore.OpenApi choose the version -->
<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.14" />
</ItemGroup>

With 10.0.14 that resolves Microsoft.OpenApi 2.12.2, the lower bound of its [2.12.2, 3.0.0) range. The build passes and GET /openapi/v1.json returns 200 with an "openapi": "3.1.1" document.

If you keep a direct reference (for example to pick up a 2.x bug fix sooner), pin it to the newest 2.x, which is 2.13.0 at the time of writing:

<!-- .NET SDK 10.0.403 -->
<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.15" />
  <PackageReference Include="Microsoft.OpenApi" Version="2.13.0" />
</ItemGroup>

Under Central Package Management the same fix goes in Directory.Packages.props. Note that 10.0.15 requires at least 2.13.0, so a CPM pin to an older 2.x such as 2.12.2 becomes its own downgrade error the day you bump the ASP.NET Core package:

<!-- Directory.Packages.props, .NET SDK 10.0.403 -->
<ItemGroup>
  <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.15" />
  <PackageVersion Include="Microsoft.OpenApi" Version="2.13.0" />
</ItemGroup>

Fix 2: find and downgrade the package that pulls in 3.x

If there is no direct reference, find out who chose 3.x. dotnet nuget why (available since SDK 8.0.400) prints every path to the package:

$ dotnet nuget why Microsoft.OpenApi      # .NET SDK 10.0.403, Microsoft.AspNetCore.OpenApi 10.0.10
Project 'Api' has the following dependency graph(s) for 'Microsoft.OpenApi':

  [net10.0]
  ├── Microsoft.AspNetCore.OpenApi (v10.0.10)
  │   └── Microsoft.OpenApi (v3.11.0)
  └── Microsoft.OpenApi.YamlReader (v3.11.0)
      └── Microsoft.OpenApi (v3.11.0)

The second branch is the culprit. Microsoft.OpenApi.YamlReader is versioned in lockstep with Microsoft.OpenApi, so the fix is to move it back to the matching 2.x:

<!-- .NET SDK 10.0.403 -->
<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.15" />
  <PackageReference Include="Microsoft.OpenApi.YamlReader" Version="2.13.0" />
</ItemGroup>

That combination builds, resolves Microsoft.OpenApi 2.13.0, and serves the document with HTTP 200.

What does not work is pinning Microsoft.OpenApi to 2.x while leaving the 3.x consumer in place. NuGet treats that as a downgrade, and the SDK promotes NU1605 to an error by default:

error NU1605: Warning As Error: Detected package downgrade: Microsoft.OpenApi from 3.11.0 to 2.13.0. Reference the package directly from the project to select a different version.
error NU1605:  Api -> Microsoft.OpenApi.YamlReader 3.11.0 -> Microsoft.OpenApi (>= 3.11.0)
error NU1605:  Api -> Microsoft.OpenApi (>= 2.13.0)

Do not silence NU1605 here. The 3.x consumer would then run against a 2.x assembly and fail at runtime in the mirror image of the problem below.

Why removing the generator is not a fix

The other workaround in circulation removes the source generator from the compilation with a target like this one:

<!-- .NET SDK 10.0.403: compiles, but do not ship this with Microsoft.OpenApi 3.x -->
<Target Name="DisableCompileTimeOpenApiXmlGenerator" BeforeTargets="CoreCompile">
  <ItemGroup>
    <Analyzer Remove="@(Analyzer)"
              Condition="'%(Filename)' == 'Microsoft.AspNetCore.OpenApi.SourceGenerators'" />
  </ItemGroup>
</Target>

With Microsoft.AspNetCore.OpenApi 10.0.14 and Microsoft.OpenApi 3.11.0, that build succeeds. The app starts, regular endpoints work, and the first request for the document fails:

GET /openapi/v1.json -> 500

System.MissingMethodException: Method not found: 'System.Collections.Generic.IDictionary`2<System.String,Microsoft.OpenApi.OpenApiMediaType> Microsoft.OpenApi.OpenApiResponse.get_Content()'.
   at Microsoft.AspNetCore.OpenApi.OpenApiDocumentService.GetResponseAsync(...)
   at Microsoft.AspNetCore.OpenApi.OpenApiDocumentService.GetResponsesAsync(...)
   at Microsoft.AspNetCore.OpenApi.OpenApiDocumentService.GetOperationAsync(...)

Microsoft.AspNetCore.OpenApi.dll itself was compiled against the 2.x signature of Content, and 3.x changed the return type, so the method it binds to no longer exists. The compile error was doing you a favor. This is also worse than a build break in one specific way: if MapOpenApi() only runs in Development (the template default), production works fine until you add build-time document generation or a client generator step that fetches the document, and then it fails far from the change that caused it. An ASP.NET Core maintainer made the same point in dotnet/aspnetcore#64317, and another user in that thread reported the identical MissingMethodException on 10.0.8 with Microsoft.OpenApi 3.5.4.

Removing the generator is a legitimate option when you do not want XML comments in your document at all, but only on a supported Microsoft.OpenApi 2.x.

Fix 3: move to ASP.NET Core 11 if you want Microsoft.OpenApi 3.x

Microsoft.AspNetCore.OpenApi 11.0.0, released on 2026-11-10, is built on the 3.x line and declares Microsoft.OpenApi [3.11.0, 4.0.0). With SDK 11.0.100, a fresh dotnet new webapi project targeting net11.0 with GenerateDocumentationFile enabled builds cleanly, resolves Microsoft.OpenApi 3.11.0, and serves a document that starts with "openapi": "3.2.0".

The trap flips direction after the upgrade. If you carry an old Microsoft.OpenApi 2.x pin into a .NET 11 project, restore fails:

error NU1605: Warning As Error: Detected package downgrade: Microsoft.OpenApi from 3.11.0 to 2.13.0. Reference the package directly from the project to select a different version.
error NU1605:  Api -> Microsoft.AspNetCore.OpenApi 11.0.0 -> Microsoft.OpenApi (>= 3.11.0 && < 4.0.0)
error NU1605:  Api -> Microsoft.OpenApi (>= 2.13.0)

So when you retarget to net11.0, bump or delete the Microsoft.OpenApi pin in the same commit. Transformers you wrote against 2.x may also need the IOpenApiMediaType changes listed in the upgrade guide.

Gotchas and variants

Patch versions 10.0.11 and later fail earlier, with a misleading hint. The servicing fix for #64317 (dotnet/aspnetcore#67772, first shipped in 10.0.11) capped the dependency below 3.0.0. The NuGet nuspecs show the progression: 10.0.0 to 10.0.10 declare >= 2.0.0, 10.0.11 declares [2.7.5, 3.0.0), 10.0.12 [2.12.0, 3.0.0), 10.0.13 and 10.0.14 [2.12.2, 3.0.0), and 10.0.15 [2.13.0, 3.0.0). With the cap in place, a transitive 3.x consumer now fails restore instead of compile:

error NU1107: Version conflict detected for Microsoft.OpenApi. Install/reference Microsoft.OpenApi 3.11.0 directly to project Api to resolve this issue.
error NU1107:  Api -> Microsoft.AspNetCore.OpenApi 10.0.15 -> Microsoft.OpenApi (>= 2.13.0 && < 3.0.0).
error NU1107:  Api -> Microsoft.OpenApi.YamlReader 3.11.0 -> Microsoft.OpenApi (>= 3.11.0)

NuGet’s suggested fix, “reference Microsoft.OpenApi 3.11.0 directly”, is exactly the change that produces CS0200. Follow Fix 2 instead. The same NU1107-then-NU1608 pattern shows up with other packages that cap a dependency, as in the Pomelo and EF Core 10 version conflict.

Keep bots from re-breaking it. Dependabot and Renovate see 3.x as a normal major update. For Dependabot, an ignore rule in .github/dependabot.yml keeps the Microsoft.OpenApi packages on 2.x until you move to .NET 11 (remove it as part of that upgrade):

# .github/dependabot.yml (until the project targets net11.0)
version: 2
updates:
  - package-ecosystem: "nuget"
    directory: "/"
    schedule:
      interval: "weekly"
    ignore:
      - dependency-name: "Microsoft.OpenApi*"
        update-types: ["version-update:semver-major"]

Swashbuckle has the same rule. Swashbuckle.AspNetCore 10.x is also built on Microsoft.OpenApi 2.x, and the upgrade guide gives it the same “stay on 2.x” instruction. A project that uses both Swashbuckle and the built-in generator needs both to agree.

Lookalike error, different cause. If you see CS0246: The type or namespace name 'OpenApiReference' could not be found or CS0234 ... 'Models' does not exist in the namespace 'Microsoft.OpenApi', that is the 1.x to 2.x break, not this one. It is covered in fixing the missing OpenApiReference type.

Sources

Comments

Sign in with GitHub to comment. Reactions and replies thread back to the comments repo.

< Back