Documentation and Unit Test to show how to break into debugger (debugging templates)

Author: Drizin

README.md

@@ -1053,6 +1053,16 @@ class MyTemplate
 }
 ```
 
+## Debugging Support
+
+It's possible to debug templates using Visual Studio.  
+To break into the debugger inside markup mode (interpolated string) you just have to interpolate `BREAKIF(true)`.  
+To break into the debugger inside programmatic mode (method) you just have to call `System.Diagnostics.Debugger.Break()` and disable `Tools - Debugging - General - Enable Just My Code`.  
+See example in
+[Debugging.cs Unit Test](https://github.com/CodegenCS/CodegenCS/tree/master/src/Tools/Tests/Templates/0090-Debugging.cs).
+
+
+
 # Learn More
 
 - [CodegenTextWriter documentation](https://github.com/CodegenCS/CodegenCS/tree/master/docs/CodegenTextWriter.md)

src/Core/CodegenCS/Symbols.cs

@@ -88,7 +88,15 @@ public static Func<FormattableString> IIF(bool condition, Func<FormattableString
         //https://ttl255.com/jinja2-tutorial-part-3-whitespace-control/
 
         #region Debugging
+        // If you're debugging through visual studio (e.g. Unit Tests, or any other code going through CodegenTextWriter)
+        // it can be difficult to debug through CodegenTextWriter because it writes interpolated strings element-by-element
+        // If you want to brea in the debugger at any specific point inside an interpolated string (markup mode)
+        // all you have to do is interpolate BREAKIF(true)
         public static Action BREAKIF(bool condition) => () => { if (condition) { System.Diagnostics.Debugger.Break(); } };
+        
+        // If you want to break from inside a method in your template (programmatic mode)
+        // then you can just use System.Diagnostics.Debugger.Break() and make sure you
+        // disable "Tools - Debugging - General - Enable Just My Code", in order to break and see the template source code
         #endregion
     }
 }

src/Tools/TemplateBuilder/RoslynCompiler.cs

@@ -230,7 +230,7 @@ public async Task<CompileResult> CompileAsync(string[] sources, string targetFil
             using (var dllStream = new MemoryStream())
             using (var pdbStream = new MemoryStream())
             {
-                var emitResult = compilation.Emit(dllStream, pdbStream);
+                var emitResult = compilation.Emit(dllStream, pdbStream); // roslyn throws a lot of exceptions, so "break on all exceptions" is not nice at this line
 
                 //TODO: combine all errors into a single statement, 
                 // since Powershell ISE stops at first stderr message when $ErrorActionPreference = "Stop"
@@ -343,7 +343,13 @@ void AddMissingUsings(List<SyntaxTree> trees)
                 if (Regex.IsMatch(templateSource, @"(?<!\.)\bInvocationContext\b"))
                     AddMissingUsing(ref rootNode, "System.CommandLine.Invocation");
 
-                if (Regex.IsMatch(templateSource, @"(?<!\.)\bIF\(\b") || Regex.IsMatch(templateSource, @"(?<!\.)\bIIF\(\b"))
+                if (Regex.IsMatch(templateSource, @"(?<!\.)\bIF\(\b") || 
+                    Regex.IsMatch(templateSource, @"(?<!\.)\bIIF\(\b") || 
+                    Regex.IsMatch(templateSource, @"(?<!\.)\bBREAKIF\(\b") ||
+                    Regex.IsMatch(templateSource, @"(?<!\.)\bTLW\(\b") ||
+                    Regex.IsMatch(templateSource, @"(?<!\.)\bTTW\(\b") ||
+                    Regex.IsMatch(templateSource, @"(?<!\.)\bCOMMENT\(\b") ||
+                    Regex.IsMatch(templateSource, @"(?<!\.)\bRAW\(\b"))
                     AddMissingUsing(ref rootNode, "CodegenCS.Symbols", true);
 
                 if (Regex.IsMatch(templateSource, @"(?<!\.)\bPREVIOUS_COLOR\b") || Regex.IsMatch(templateSource, @"(?<!\.)\bPREVIOUS_BACKGROUND_COLOR\b"))

src/Tools/Tests/Templates/0090-Debugging.cs

@@ -0,0 +1,25 @@
+// If you run TemplateBuildTests this is the only unit test that should break into the debugger
+// It's possible to break both inside MARKUP mode (interpolating a symbol) or in PROGRAMMATIC mode
+class MyTemplate
+{
+    string[] groceries = new string[] { "Milk", "Eggs", "Diet Coke" };
+
+    // If you run this template using Visual Studio Unit Tests 
+    // it will break into the debugger when it reaches the BREAKIF(true)
+    FormattableString Main() => $$"""
+        I have to buy:
+            {{BREAKIF(true)}}{{groceries}}
+            Will write some more stuff
+            {{MethodWithBreak}}
+        """;
+
+    // If you want to break from inside a method in your template (programmatic mode)
+    // then you can just use System.Diagnostics.Debugger.Break() and make sure you
+    // disable "Tools - Debugging - General - Enable Just My Code", in order to break and see the template source code (because it's invoked using reflection so it's considered external code)
+    void MethodWithBreak(ICodegenOutputFile file)
+    {
+        file.WriteLine("writing something here");
+        System.Diagnostics.Debugger.Break();
+        file.WriteLine("last part");
+    }
+}

src/Tools/Tests/Templates/0090-Debugging.generated.cs

@@ -0,0 +1,7 @@
+I have to buy:
+    Milk
+    Eggs
+    Diet Coke
+    Will write some more stuff
+    writing something here
+    last part