Xml Doc comments in c# embedded resources on .NET (Core)

Question

I've got a c# project migrated from .NET framework to .NET Core (and then .NET 5).

We haven't touched our .resx files at all in a couple of years, but now that I updated a .resx file, the Resources.Designer.cs files got re-generated (good), dropping all the previously-included Xml Doc (bad, produces large diff, also losing information).

How do I instruct my Resx build step to retain/generate XML Doc like in the old times?

Originally this code was written and generated with Visual Studio on Windows, and we now use Rider on Macs

EDIT: looks like it's not specific to .NET 5, but rather to Windows+VS vs. Mac+Rider pairing, as a Windows dev on my team regenerated those comments on top of my changes.

How do I get this on Mac/Linux without Visual Studio?

Old file portion:

//------------------------------------------------------------------------------
// <auto-generated>
//     This code was generated by a tool.
//     Runtime Version:4.0.30319.42000
//
//     Changes to this file may cause incorrect behavior and will be lost if
//     the code is regenerated.
// </auto-generated>
//------------------------------------------------------------------------------

namespace Resources {
    using System;
    
    
    /// <summary>
    ///   A strongly-typed resource class, for looking up localized strings, etc.
    /// </summary>
    // This class was auto-generated by the StronglyTypedResourceBuilder
    // class via a tool like ResGen or Visual Studio.
    // To add or remove a member, edit your .ResX file then rerun ResGen
    // with the /str option, or rebuild your VS project.
    [global::System.CodeDom.Compiler.GeneratedCodeAttribute("System.Resources.Tools.StronglyTypedResourceBuilder", "16.0.0.0")]
    [global::System.Diagnostics.DebuggerNonUserCodeAttribute()]
    [global::System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
    public class Resources {

...

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

NEW file portion:

//------------------------------------------------------------------------------
// <auto-generated>
//     This code was generated by a tool.
//
//     Changes to this file may cause incorrect behavior and will be lost if
//     the code is regenerated.
// </auto-generated>
//------------------------------------------------------------------------------

namespace Resources {
    using System;
    
    
    [System.CodeDom.Compiler.GeneratedCodeAttribute("System.Resources.Tools.StronglyTypedResourceBuilder", "16.0.0.0")]
    [System.Diagnostics.DebuggerNonUserCodeAttribute()]
    [System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
    public class Resources {

...

        public static string About {
            get {
                return ResourceManager.GetString("About", resourceCulture);
            }
        }

The file in question goes down from 12k LOC to 8k LOC, which is a lot of comments lost, and makes things harder to work with.

Answer 1

I don't know if this will work for you as a solve, but my suggestion would be that when there is an OS / Tooling issue, fire up Docker and execute the MSBUILD command manually from a Windows Docker image. I suggest this since your WinDev coworker is regenerating the missing comments.

MSBUILD Commands

The only gotcha that came to mind that wouldn't work is like the one linked below, where they are still needing to specify the Configuration type and that the Project (.CSPROJ file) was set to "building" documentation on that configuration. Document generation was "build" and Visual Studio "Configuration" specific.

For example, if Docs were built when the Project build was initiated with "Debug" and "Any CPU" set as the configuration then that is the same one you need to invoke in the MSBUILD CLI with the necessary parameters like

That would look sort of like this (going by sketchy memory).

msbuild.exe MyProject.csproj `
/p:Configuration=Debug `
/p:Platform="Any CPU" `
/p:GenerateDocumentation `
/p:DocumentationFile="MyProject.xml"

Stackoverflow - MSBUILD XML Docs

This can all be scripted so its pretty much start a Docker image, POSH script the build document generation, then copy document to local host. A bit clunky, but you only have to do it when you are all finished and ready to push it up.