Added the syntax highlighting for template messages in generic Log* and BeginScope overloads for Jetbrains tools (#27)

Author: stbychkov

docs/ADR/ADR-08_Message_template_syntax-highlighting.md

@@ -0,0 +1,57 @@
+### Title: ADR-08 Message Template Syntax Highlighting
+
+### Status: Accepted
+
+### Context:
+
+When writing log messages using structured templates (like `"User {UserId} logged in"`), it's good to have some syntax highlighting to see if it's a raw string literal or a template parameter. IDE support could help a lot here by offering syntax highlighting out of the box.
+
+There are two main options we looked at:
+
+1. **`[SyntaxAttribute]` from Microsoft** — this is supported in Visual Studio and JetBrains Rider.
+2. **`[StructuredMessageTemplate]` from `JetBrains.Annotations`** — works only in JetBrains tools, like Rider and ReSharper.
+
+`SyntaxAttribute` seemed promising at first, but we hit a few issues:
+
+* It’s only available starting from **.NET 7**, and even though our target app is .NET 8+ (because we're using interceptors), source generators themselves still need to be compiled against `netstandard2.0` for Visual Studio compatibility. So, we’d have to wrap every usage in `#if NET8_0_OR_GREATER`, which would make the code messy.
+* The only `SyntaxAttribute` that somewhat matches our case is `SyntaxAttribute(SyntaxKind.CompositeFormat)`, which was designed for `string.Format`-style messages. That doesn't map well to structured logging templates, which can use named placeholders like `{UserId}` — not just `{0}`, `{1}`, etc.
+
+Then we looked at `StructuredMessageTemplate` from `JetBrains.Annotations`. It's not built into the .NET SDK, but:
+
+* It’s a tiny library with **no extra dependencies**.
+* It targets **.NET Standard 1.0**, so it works fine with our source generator build setup.
+
+The downside is that it’s **only useful in Rider/ReSharper** — Visual Studio (Code) won’t recognize it. But that’s fine: it’s better than nothing, and we shouldn't introduce any breakage.
+
+### Decision:
+
+We’re going to add `[StructuredMessageTemplate]` from the `JetBrains.Annotations` package to mark message template parameters in the generated logging code.
+
+Specifically:
+
+* Add the `[StructuredMessageTemplate]` attribute to all generated `message` parameters in `Log*` and `BeginScope` generic overloads.
+* Pull in the latest version of `JetBrains.Annotations` as a compile-time-only dependency.
+
+### Consequences:
+
+* **Short-term**:
+    * Improved developer experience in Rider/ReSharper.
+    * Helps catch common mistakes in message templates at design time.
+
+* **Long-term**:
+    * No negative impact for Visual Studio users, but they won’t benefit from it either.
+    * Keeps the generic overloads clean and tidy.
+
+* **Risks**:
+    * Adds a soft dependency (though very minimal and safe).
+
+* **Maintenance**:
+    * Easy to keep up — JetBrains.Annotations is stable and tiny.
+    * If Microsoft adds a better-suited `SyntaxAttribute` in future versions, we can revisit this.
+
+### Alternatives Considered:
+
+* **Use `SyntaxAttribute(SyntaxKind.CompositeFormat)`**:
+  Clean and native, but doesn’t fit well in our use case at this moment.
+* **Do nothing**:
+  Simple, but leaves developers without any IDE help for message templates, which is a missed opportunity.

src/AutoLoggerMessageGenerator.BuildOutput/AutoLoggerMessageGenerator.BuildOutput.csproj

@@ -5,6 +5,7 @@
   </PropertyGroup>
 
   <ItemGroup>
+    <PackageReference Include="JetBrains.Annotations" Version="2024.3.0" />
     <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="8.0.0" PrivateAssets="all"/>
   </ItemGroup>
 </Project>

src/AutoLoggerMessageGenerator.BuildOutput/GenericLoggerExtensions.g.cs

@@ -2,41 +2,42 @@
 #nullable enable
 
 using System;
+using JetBrains.Annotations;
 
 namespace Microsoft.Extensions.Logging
 {
-    [global::System.CodeDom.Compiler.GeneratedCodeAttribute("AutoLoggerMessageGenerator", "1.0.10.0")]
+    [global::System.CodeDom.Compiler.GeneratedCodeAttribute("AutoLoggerMessageGenerator", "1.0.12.0")]
     [global::System.ComponentModel.EditorBrowsableAttribute(global::System.ComponentModel.EditorBrowsableState.Never)]
     [System.Diagnostics.DebuggerStepThrough]
     [System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
     public static class GenericLoggerScopeExtensions
     {
-        public static IDisposable? BeginScope<T0>(this ILogger @logger, string @message, T0 @arg0)
+        public static IDisposable? BeginScope<T0>(this ILogger @logger, [StructuredMessageTemplate] string @message, T0 @arg0)
         {
             return Microsoft.Extensions.Logging.LoggerExtensions.BeginScope(@logger, @message, new object?[] { @arg0 });
         }
 
-        public static IDisposable? BeginScope<T0, T1>(this ILogger @logger, string @message, T0 @arg0, T1 @arg1)
+        public static IDisposable? BeginScope<T0, T1>(this ILogger @logger, [StructuredMessageTemplate] string @message, T0 @arg0, T1 @arg1)
         {
             return Microsoft.Extensions.Logging.LoggerExtensions.BeginScope(@logger, @message, new object?[] { @arg0, @arg1 });
         }
 
-        public static IDisposable? BeginScope<T0, T1, T2>(this ILogger @logger, string @message, T0 @arg0, T1 @arg1, T2 @arg2)
+        public static IDisposable? BeginScope<T0, T1, T2>(this ILogger @logger, [StructuredMessageTemplate] string @message, T0 @arg0, T1 @arg1, T2 @arg2)
         {
             return Microsoft.Extensions.Logging.LoggerExtensions.BeginScope(@logger, @message, new object?[] { @arg0, @arg1, @arg2 });
         }
 
-        public static IDisposable? BeginScope<T0, T1, T2, T3>(this ILogger @logger, string @message, T0 @arg0, T1 @arg1, T2 @arg2, T3 @arg3)
+        public static IDisposable? BeginScope<T0, T1, T2, T3>(this ILogger @logger, [StructuredMessageTemplate] string @message, T0 @arg0, T1 @arg1, T2 @arg2, T3 @arg3)
         {
             return Microsoft.Extensions.Logging.LoggerExtensions.BeginScope(@logger, @message, new object?[] { @arg0, @arg1, @arg2, @arg3 });
         }
 
-        public static IDisposable? BeginScope<T0, T1, T2, T3, T4>(this ILogger @logger, string @message, T0 @arg0, T1 @arg1, T2 @arg2, T3 @arg3, T4 @arg4)
+        public static IDisposable? BeginScope<T0, T1, T2, T3, T4>(this ILogger @logger, [StructuredMessageTemplate] string @message, T0 @arg0, T1 @arg1, T2 @arg2, T3 @arg3, T4 @arg4)
         {
             return Microsoft.Extensions.Logging.LoggerExtensions.BeginScope(@logger, @message, new object?[] { @arg0, @arg1, @arg2, @arg3, @arg4 });
         }
 
-        public static IDisposable? BeginScope<T0, T1, T2, T3, T4, T5>(this ILogger @logger, string @message, T0 @arg0, T1 @arg1, T2 @arg2, T3 @arg3, T4 @arg4, T5 @arg5)
+        public static IDisposable? BeginScope<T0, T1, T2, T3, T4, T5>(this ILogger @logger, [StructuredMessageTemplate] string @message, T0 @arg0, T1 @arg1, T2 @arg2, T3 @arg3, T4 @arg4, T5 @arg5)
         {
             return Microsoft.Extensions.Logging.LoggerExtensions.BeginScope(@logger, @message, new object?[] { @arg0, @arg1, @arg2, @arg3, @arg4, @arg5 });
         }

src/AutoLoggerMessageGenerator.BuildOutput/GenericLoggerScopeExtensions.g.cs

@@ -51,11 +51,12 @@ internal static class Constants
         $"\"{typeof(Generators.AutoLoggerMessageGenerator).Assembly.GetName().Version}\")]";
     public const string EditorNotBrowsableAttribute = "[global::System.ComponentModel.EditorBrowsableAttribute(global::System.ComponentModel.EditorBrowsableState.Never)]";
 
-    public static string GeneratedFileHeader => """
+    public const string GeneratedFileHeader = """
                                                 // <auto-generated/>
                                                 #nullable enable
 
                                                 using System;
-
                                                 """;
+    public const string JetBrainsAnnotationsImport = "using JetBrains.Annotations;";
+    public const string MessageTemplateDecorator = "[StructuredMessageTemplate]";
 }

src/AutoLoggerMessageGenerator/Constants.cs

@@ -18,6 +18,8 @@ public static string Emit()
         using var sb = new IndentedTextWriter(new StringWriter());
 
         sb.WriteLine(GeneratedFileHeader);
+        sb.WriteLine(JetBrainsAnnotationsImport);
+        sb.WriteLine();
 
         sb.WriteLine($"namespace {DefaultLoggingNamespace}");
         sb.WriteLine('{');
@@ -33,9 +35,9 @@ public static string Emit()
 
         string[] logLevels = ["Trace", "Debug", "Information", "Warning", "Error", "Critical"];
 
-        var messageParameter = ("string", MessageArgumentName: MessageParameterName);
-        var exceptionParameter = ("Exception?", ExceptionArgumentName: ExceptionParameterName);
-        var eventIdParameter = ("EventId", EventIdArgumentName: EventIdParameterName);
+        var messageParameter = ($"{MessageTemplateDecorator} string", MessageParameterName);
+        var exceptionParameter = ("Exception?", ExceptionParameterName);
+        var eventIdParameter = ("EventId", EventIdParameterName);
 
         (string Type, string Name)[][] fixedParametersOverloads =
         [

src/AutoLoggerMessageGenerator/Emitters/GenericLoggerExtensionsEmitter.cs

@@ -18,6 +18,8 @@ public static string Emit()
         using var sb = new IndentedTextWriter(new StringWriter());
 
         sb.WriteLine(GeneratedFileHeader);
+        sb.WriteLine(JetBrainsAnnotationsImport);
+        sb.WriteLine();
 
         sb.WriteLine($"namespace {DefaultLoggingNamespace}");
         sb.WriteLine('{');
@@ -51,7 +53,7 @@ public static string Emit()
                 ? string.Empty
                 : $", new object?[] {{ {objectParameters} }}";
 
-            sb.WriteLine($"public static IDisposable? BeginScope{genericTypesDefinition}(this ILogger {LoggerParameterName}, string {MessageParameterName}{genericParametersDefinition})");
+            sb.WriteLine($"public static IDisposable? BeginScope{genericTypesDefinition}(this ILogger {LoggerParameterName}, {MessageTemplateDecorator} string {MessageParameterName}{genericParametersDefinition})");
             sb.WriteLine('{');
             sb.Indent++;
 

src/AutoLoggerMessageGenerator/Emitters/GenericLoggerScopeExtensionsEmitter.cs

@@ -9,6 +9,7 @@ public static string Emit()
         using var sb = new IndentedTextWriter(new StringWriter());
 
         sb.WriteLine(Constants.GeneratedFileHeader);
+        sb.WriteLine();
 
         sb.WriteLine($"namespace {Constants.InterceptorNamespace}");
         sb.WriteLine('{');

src/AutoLoggerMessageGenerator/Emitters/InterceptorAttributeEmitter.cs

@@ -10,6 +10,7 @@ public static string Emit(IEnumerable<LogMessageCall> logCalls)
         using var sb = new IndentedTextWriter(new StringWriter());
 
         sb.WriteLine(Constants.GeneratedFileHeader);
+        sb.WriteLine();
 
         sb.WriteLine($"namespace {Constants.GeneratorNamespace}");
         sb.WriteLine('{');

src/AutoLoggerMessageGenerator/Emitters/LoggerInterceptorsEmitter.cs

@@ -10,6 +10,7 @@ public static string Emit(IEnumerable<LoggerScopeCall> loggerScopes)
         using var sb = new IndentedTextWriter(new StringWriter());
 
         sb.WriteLine(Constants.GeneratedFileHeader);
+        sb.WriteLine();
 
         sb.WriteLine($"namespace {Constants.GeneratorNamespace}");
         sb.WriteLine('{');