CS warnings appear in Resources.Designer.cs when a resource file excerpt line starts with `/`

[jnm2]

Due to a bug in CodeDom's generation of C# code comments that the StronglyTypedResourceBuilder class in this repo does nothing to avoid, any project with <GenerateDocumentationFile>true</GenerateDocumentationFile> that embeds a file that contains a line that starts with / gets invalid C# documentation syntax in .Designer.cs, resulting in warnings:

I asked first at https://github.com/dotnet/roslyn/issues/53729 in case the compiler team thought that documentation warnings should be skipped in generated code, and they decided that the current behavior is by design.

Steps to Reproduce

Full repro: Repro.zip

Resource file being included (real-life example was a SQL file that was truncated by the resource code generator when included in the XML comment):

/

Problematic excerpt from Resources.Designer.cs:

/// <summary>
///   Looks up a localized string similar to 
////.
/// </summary>
internal static string SomeResourceFile {
    get {
        return ResourceManager.GetString("SomeResourceFile", resourceCulture);
    }
}

Project file:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net5.0</TargetFramework>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>

  <ItemGroup>
    <Compile Update="Properties\Resources.Designer.cs">
      <DesignTime>True</DesignTime>
      <AutoGen>True</AutoGen>
      <DependentUpon>Resources.resx</DependentUpon>
    </Compile>
  </ItemGroup>

  <ItemGroup>
    <EmbeddedResource Update="Properties\Resources.resx">
      <Generator>ResXFileCodeGenerator</Generator>
      <LastGenOutput>Resources.Designer.cs</LastGenOutput>
    </EmbeddedResource>
  </ItemGroup>

</Project>

Specific errors:

Analysis

This is where CodeDom creates the invalid //// XML doc comment line: https://github.com/dotnet/runtime/blob/v5.0.6/src/libraries/System.CodeDom/src/Microsoft/CSharp/CSharpCodeGenerator.cs#L879 .NET Framework's CodeDom has the same bug: https://referencesource.microsoft.com/#System/compmod/microsoft/csharp/csharpcodeprovider.cs,e0b125d92a26ca23

On that line it outputs /// because of string commentLineStart = e.DocComment ? "///" : "//"; outside that loop. Then the next character of value that will be written after that is a single /. This causes invalid C# any time a forward slash follows a newline in CodeComment.Text.

There does not appear to be a way to work around this by instructing the Resources.Designer.cs generator to stop putting file content in XML comments: https://github.com/dotnet/msbuild/blob/v16.10.0/src/Tasks/system.design/stronglytypedresourcebuilder.cs#L562-L593

A workaround is to put this in .editorconfig:

[*.Designer.cs] # Workaround for https://github.com/dotnet/roslyn/issues/53729
dotnet_diagnostic.CS1570.severity = none
dotnet_diagnostic.CS1587.severity = none

Versions & Configurations

Visual Studio 16.10.0

This also afflicts the StronglyTypedResourceBuilder in .NET Framework's Microsoft.Build.Tasks.v4.0.dll assembly, file version 4.8.4084.0.

[benvillalobos]

It sounds like the main issue is in the runtime. Is there a canonical issue for this bug?

[jnm2]

@BenVillalobos Not yet. Would you like me to create it? Either way, MSBuild might want to work properly on .NET Framework and on past versions of .NET Core.

[benvillalobos]

@jnm2 That'd be great. We're interested in seeing where this ranks for them

[jnm2]

@BenVillalobos Here's the runtime issue: https://github.com/dotnet/runtime/issues/56267

[danmoseley]

It's going to be low priority unless perhaps a community member offers a change. I assume you have to work around this anyway for .NET Framework

[KalleOlaviNiemitalo]

ResXFileCodeGenerator can also generate a different kind of XML syntax error:

Properties\Resources.Designer.cs(604,12,604,12): warning CS1570: XML comment has badly formed XML -- ''', hexadecimal value 0x1B, is an invalid character.'

I suggest that CodeDom be left alone and StronglyTypedResourceBuilder omit the text sample from the XML when the string resource needs special cases like this. Either use a constant comment:

/// <summary>
///   Looks up a localized string.
/// </summary>

Or omit the whole XML comment. Roslyn will detect Resources.Designer.cs as a generated file and not report warning CS1591, even if the class and the properties are public.

If it is difficult to make StronglyTypedResourceBuilder recognize the problematic syntax, it could instead take a parameter that suppresses the text samples or XML comments of all string resources. This would be easy to implement for classes that are generated at build time with the GenerateResource task, but harder to implement for classes that are generated at design time with Visual Studio.

[jnm2]

Roslyn will detect Resources.Designer.cs as a generated file and not report warning CS1591, even if the class and the properties are public.

Is this the case? If so, then Roslyn also shouldn't be reporting the CS warnings that motivated filing this issue in the first place.

[jnm2]

This is now fixed in the main branch in dotnet/runtime, so I assume the fix will be in .NET 6. However, it still affects MSBuild running on .NET Framework and older .NET Core.

The nature of the .NET 6 fix is that it only comes into play when absolutely necessary to avoid invalid C#. This makes it easy for StronglyTypedResourceBuilder to fix the bug without affecting behavior on .NET 6. This can be done in a number of ways. If StronglyTypedResourceBuilder provides a string to CodeDOM that doesn't trigger the problem on older versions of .NET, .NET 6 behaves just like all other versions of .NET.

One of my favorite ways would be for StronglyTypedResourceBuilder to stop causing updates in the designer file when resource file content changes. Embedded files are usually edited directly and changed frequently without triggering the IDE to regenerate the .Designer.cs file, making the sudden update to the file excerpt in the doc comment in the .Designer.cs file feel arbitrary and unpredictable when something does trigger the IDE to regenerate it.