[OpenApi] SourceGen error using xml docs for Static methods taking generic parameters.

[jasonswearingen]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

it seems that a static class with Generic methods causes errors with the OpenApi sourcegen.

If I change the library's .csproj to include: <GenerateDocumentationFile>false</GenerateDocumentationFile> the error disappears.

a library referenced by my aspnetcore api has:

/// <summary>
///    helpers to allocate a WriteMem instance
/// </summary>
public static class Mem
{
   /// <summary>
   ///    Create a temporary (no-pooled) mem using your own backing data object
   /// </summary>
   public static Mem<T> CreateUsing<T>(T[] array)
   {
      return Mem<T>.CreateUsing(array);
   }
}

causes the following line to be generated in .Generated\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs

_cache.Add(new MemberKey(typeof(global::NotNot.Mem), MemberType.Method, "CreateUsing", typeof(global::NotNot.Mem<>), [typeof(T[])]), new XmlComment(@"Create a temporary (no-pooled) mem using your own backing data object.", null, null, null, null, false, null, null, null));

which triggers the following error in build output:

1>V:\project\path\.Generated\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(599,138,599,139): error CS0246: The type or namespace name 'T' could not be found (are you missing a using directive or an assembly reference?)

Expected Behavior

see above

Steps To Reproduce

see above

Exceptions (if any)

see above

.NET Version

10.0.0-preview.3.25172.1

Anything else?

Microsoft.AspNetCore.OpenApi v10.0.0-preview.3.25172.1

[jasonswearingen]

also, related workaround: if there is some way I can remove the problematic assembly from openapi doc gen (so I don't have to stop generating xml docs for it), or even better, remove problematic types individually, it would be great to hear. I found the doc pages on this openapi feature to be very good ( https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/openapi-tools?view=aspnetcore-10.0 ), but they don't go over the .AddOpenApi() options, and I couldn't figure out a graceful way to configure options for this either.

[martincostello]

@jasonswearingen See here for how to disable the source generator (about half way down the section): https://github.com/dotnet/core/blob/main/release-notes/10.0/preview/preview2/aspnetcore.md#populate-xml-doc-comments-into-openapi-document

[jasonswearingen]

Thanks, @martincostello. I saw that, but don't think it's exactly what I want. I think it's for disabling the sourcegen entirely? To clarify, I don't want to disable the source generation or use of xml docs, just disable use of certain docs or certain types in the docs.

[martincostello]

Oh I see, sorry I misunderstood. At this point I'd maybe wait until preview.4 which has a bunch of fixes for various issues, and then see if the problem you're having that makes you want to suppress some things persists.

[jasonswearingen]

it's alright, i will just disable the problematic assembly's xml doc for now. I just wanted to bring this to your attention. The OpenApi solution you all are making is so much better than the legacy choices.

Thank you.

[captainsafia]

@jasonswearingen .NET 10 Preview 4 is out as of an hour ago (see https://devblogs.microsoft.com/dotnet/dotnet-10-preview-4/) which includes this PR I opened a while back (#61145).

It contains a bug fix that moves to string-based keys instead of using typeof() which should reduce the chance of build errors being introduced by the source generator.

Can you try it and report back?

[jasonswearingen]

@captainsafia I'm sorry I was required to move back to net9 due to azure compatibility issues.

you all should include this in your test cases, it is very straight forward (see the first post in this issue for a snippet)

[captainsafia]

We included test cases as part of the Preview 4. Closing this as resolved for now.