Documentation improved, code generation using Scriban added and implemented a way to use custom Scriban templates in consuming projects

Author: IqualityRobin

Directory.Build.props

@@ -3,12 +3,6 @@
     <LangVersion>9.0</LangVersion>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
     <Nullable>enable</Nullable>
-    <Version>0.3.0</Version>
+    <Version>0.4.0</Version>
   </PropertyGroup>
-  <ItemGroup>
-    <PackageReference Include="Microsoft.CodeAnalysis.FxCopAnalyzers" Version="3.3.1">
-      <PrivateAssets>all</PrivateAssets>
-      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
-    </PackageReference>
-  </ItemGroup>
 </Project>

JsonByExampleGenerator.Example/JsonByExampleGenerator.Example.csproj

@@ -3,13 +3,14 @@
   <PropertyGroup>
     <TargetFramework>net5.0</TargetFramework>
     <OutputType>Exe</OutputType>
+    <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
+    <CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)\GeneratedFiles</CompilerGeneratedFilesOutputPath>
   </PropertyGroup>
 
   <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
     <NoWarn>1701;1702;CA2227;</NoWarn>
   </PropertyGroup>
 
-
   <!-- Add this as a new ItemGroup, replacing paths and names appropriately -->
     <ItemGroup>
         <!-- Note that this is not a "normal" ProjectReference.

JsonByExampleGenerator.Example/Program.cs

@@ -5,6 +5,10 @@
 
 namespace JsonByExampleGenerator.Example
 {
+    /// <summary>
+    /// This program just shows an example of how you can use the JsonByExampleGenerator.
+    /// It's not required for testing, as there are unit tests in JsonByExampleGenerator.Tests.
+    /// </summary>
     class Program
     {
         static void Main()

JsonByExampleGenerator.Generator/JsonByExampleGenerator.Generator.csproj

@@ -20,17 +20,17 @@
     <PackFolder>analyzers\cs</PackFolder>
     <DebugType>embedded</DebugType>
     <DebugSymbols>true</DebugSymbols>
+    <PackageScribanIncludeSource>true</PackageScribanIncludeSource>
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.CodeAnalysis.Analyzers" Version="3.3.1">
-      <PrivateAssets>all</PrivateAssets>
-      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
-    </PackageReference>
+    <PackageReference Include="Microsoft.CSharp" Version="4.7.0" />
+    <PackageReference Include="System.Threading.Tasks.Extensions" Version="4.5.4" />
     <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="3.8.0" />
     <PackageReference Include="NuGetizer" Version="0.4.11" />
     <PackageReference Include="Pluralize.NET" Version="1.0.2" GeneratePathProperty="true" PrivateAssets="all" />
-    <PackageReference Include="System.Text.Json" Version="5.0.0" GeneratePathProperty="true" PrivateAssets="all"/>
+    <PackageReference Include="Scriban" Version="3.4.0" GeneratePathProperty="true" IncludeAssets="Build" PrivateAssets="all" />
+    <PackageReference Include="System.Text.Json" Version="5.0.0" GeneratePathProperty="true" PrivateAssets="all" />
   </ItemGroup>
 
   <PropertyGroup>
@@ -41,7 +41,12 @@
     <ItemGroup>
       <TargetPathWithTargetPlatformMoniker Include="$(PKGPluralize_NET)\lib\netstandard2.0\Pluralize.NET.dll" IncludeRuntimeDependency="false" />
       <TargetPathWithTargetPlatformMoniker Include="$(PKGSystem_Text_Json)\lib\netstandard2.0\System.Text.Json.dll" IncludeRuntimeDependency="false" />
+      <TargetPathWithTargetPlatformMoniker Include="$(PKGScriban)\lib\netstandard2.0\Scriban.dll" IncludeRuntimeDependency="false" />
     </ItemGroup>
   </Target>
 
+  <ItemGroup>
+    <EmbeddedResource Include="@(None -&gt; WithMetadataValue('Extension', '.sbntxt'))" />
+  </ItemGroup>
+
 </Project>

JsonByExampleGenerator.Generator/JsonByExampleTemplate.sbntxt

@@ -0,0 +1,21 @@
+#nullable disable
+using System.Collections.Generic;
+using System.Text.Json.Serialization;{{ for OptionalDependency in OptionalDependencies}}
+using {{ OptionalDependency }};
+{{ end }}
+namespace {{ NamespaceName }}.Json
+{
+{{ for ClassModel in ClassModels }}
+    public partial class {{ ClassModel.ClassName }}
+    {
+        {{ for Property in ClassModel.Properties }}[JsonPropertyName("{{ Property.PropertyNameOriginal }}")]
+        public {{ Property.PropertyType }} {{ Property.PropertyName }} { get; set; }{{ if Property.Init }} = {{ Property.Init }};{{ end }}
+        {{ end }}{{ if ConfigEnabled }}
+        public static {{ ClassModel.ClassName }} FromConfig([System.Diagnostics.CodeAnalysis.NotNull] IConfiguration config)
+        {
+            return config.Get<{{ ClassModel.ClassName }}>();
+        }{{ end }}
+    }
+{{ end }}
+}
+#nullable enable

JsonByExampleGenerator.Generator/JsonGenerator.cs

@@ -13,86 +13,97 @@
 using Pluralize.NET;
 using JsonByExampleGenerator.Generator.Models;
 using System.Globalization;
+using Scriban;
+using JsonByExampleGenerator.Generator.Utils;
 
 namespace JsonByExampleGenerator.Generator
 {
+    /// <summary>
+    /// Source generator that generates C# code based on an example json file.
+    /// </summary>
     [Generator]
     public class JsonGenerator : ISourceGenerator
     {
         private static readonly IPluralize _pluralizer = new Pluralizer();
 
+        /// <summary>
+        /// Executes the generator logic during compilation
+        /// </summary>
+        /// <param name="context">Generator context that contains info about the compilation</param>
         public void Execute(GeneratorExecutionContext context)
         {
             try
             {
+                // Resolve all json files that are added to the AdditionalFiles in the compilation
                 foreach (var jsonFile in context.AdditionalFiles.Where(f => f.Path.EndsWith(".json", StringComparison.InvariantCultureIgnoreCase)))
                 {
                     var jsonFileText = jsonFile.GetText(context.CancellationToken);
-                    if(jsonFileText == null)
+                    if (jsonFileText == null)
                     {
                         continue;
                     }
 
-                    bool configEnabled = context.Compilation?.ReferencedAssemblyNames
-                        .Any(r => string.Equals("Microsoft.Extensions.Configuration.Json", r.Name, StringComparison.InvariantCulture))
-                        ?? false;
-                    configEnabled = configEnabled
-                        && (context.Compilation?.ReferencedAssemblyNames
-                        .Any(r => string.Equals("Microsoft.Extensions.Configuration.Binder", r.Name, StringComparison.InvariantCulture)) ?? false);
+                    // Determine if the functionality for easy access to configuration should be enabled
+                    bool configEnabled = IsConfigurationEnabled(context);
 
                     var json = JsonDocument.Parse(jsonFileText.ToString());
 
+                    // The namespace of the code is determined by the assembly name of the compilation
                     string namespaceName = context.Compilation?.AssemblyName ?? "JsonByExample";
 
+                    // Read the json and build a list of models that can be used to generate classes
                     var classModels = new List<ClassModel>();
                     var jsonElement = json.RootElement;
                     string rootTypeName = GetValidName(Path.GetFileNameWithoutExtension(jsonFile.Path).Replace(" ", string.Empty), true);
-                    RenderType(context, classModels, jsonElement, namespaceName, rootTypeName);
+                    ResolveTypeRecursive(context, classModels, jsonElement, rootTypeName);
 
-                    var generatedClasses = classModels.Select(c =>
-                        {
-                            string extensionMethod = string.Empty;
-                            string configReadMethod = string.Empty;
-
-                            if (configEnabled)
-                            {
-
-                                configReadMethod = $@"
-        public static {c.ClassName} FromConfig([System.Diagnostics.CodeAnalysis.NotNull] IConfiguration config)
-        {{
-            return config.Get<{c.ClassName}>();
-        }}";
-                            }
-
-                            string result = $@"
-{extensionMethod}
-    public partial class {c.ClassName}
-    {{
-{string.Join("\r\n", c.Properties.Select(p => RenderProperty(p)))}
-{configReadMethod}
-    }}";
+                    // A list of dependencies to be added to the using statements in the code generation
+                    var optionalDependencies = new List<string>();
+                    if (configEnabled)
+                    {
+                        optionalDependencies.Add("Microsoft.Extensions.Configuration");
+                    }
 
-                            return result;
-    });
+                    // Attempt to find a Scriban template in the AdditionalFiles that has the same name as the json
+                    string templateFileName = $"{Path.GetFileNameWithoutExtension(jsonFile.Path)}.sbntxt";
+                    string? templateContent = context
+                        .AdditionalFiles
+                        .FirstOrDefault(f => Path
+                            .GetFileName(f.Path)
+                            .Equals(templateFileName, StringComparison.InvariantCultureIgnoreCase))
+                        ?.GetText(context.CancellationToken)
+                        ?.ToString();
 
-                    var optionalDependencies = configEnabled ? "\r\nusing Microsoft.Extensions.Configuration;" : string.Empty;
+                    Template template;
+                    if (templateContent != null)
+                    {
+                        // Parse the template that is in the compilation
+                        template = Template.Parse(templateContent, templateFileName);
+                    }
+                    else
+                    {
+                        // Fallback to the default template
+                        const string defaultTemplatePath = "JsonByExampleTemplate.sbntxt";
+                        template = Template.Parse(EmbeddedResource.GetContent(defaultTemplatePath), defaultTemplatePath);
+                    }
 
-                    string generatedCode = $@"#nullable disable
-using System.Collections.Generic;
-using System.Text.Json.Serialization;{optionalDependencies}
+                    // Use Scriban to render the code using the model that was built
+                    string generatedCode = template.Render(new
+                    {
+                        OptionalDependencies = optionalDependencies,
+                        NamespaceName = namespaceName,
+                        ConfigEnabled = configEnabled,
+                        ClassModels = classModels
+                    }, member => member.Name);
 
-namespace {namespaceName}.Json
-{{{string.Join("\r\n", generatedClasses)}
-}}
-#nullable enable";
+                    // Add the generated code to the compilation
                     context.AddSource($"{namespaceName}_{rootTypeName}.gen.cs",
                         SourceText.From(generatedCode, Encoding.UTF8));
                 }
             }
-#pragma warning disable CA1031 // Do not catch general exception types
             catch (Exception ex)
-#pragma warning restore CA1031 // Do not catch general exception types
             {
+                // Report a diagnostic if an exception occurs while generating code; allows consumers to know what is going on
                 string message = $"Exception: {ex.Message} - {ex.StackTrace}";
                 context.ReportDiagnostic(Diagnostic.Create(
                     new DiagnosticDescriptor(
@@ -106,40 +117,61 @@ namespace {namespaceName}.Json
             }
         }
 
-        private static string RenderProperty(PropertyModel propertyModel)
+        /// <summary>
+        /// Find out if Microsoft.Extensions.Configuration.Json is used.
+        /// </summary>
+        /// <param name="context">The generator execution context</param>
+        /// <returns>True if Microsoft.Extensions.Configuration.Json is referenced from the assembly</returns>
+        private static bool IsConfigurationEnabled(GeneratorExecutionContext context)
         {
-            string init = propertyModel.Init != null ? $" = {propertyModel.Init};" : string.Empty;
-            return $"[JsonPropertyName(\"{propertyModel.PropertyNameOriginal}\")]\r\n        public {propertyModel.PropertyType} {propertyModel.PropertyName} {{ get; set; }}{init}";
+            bool configEnabled = context.Compilation?.ReferencedAssemblyNames
+                .Any(r => string.Equals("Microsoft.Extensions.Configuration.Json", r.Name, StringComparison.InvariantCulture))
+                ?? false;
+            configEnabled = configEnabled
+                && (context.Compilation?.ReferencedAssemblyNames
+                .Any(r => string.Equals("Microsoft.Extensions.Configuration.Binder", r.Name, StringComparison.InvariantCulture)) ?? false);
+            return configEnabled;
         }
 
-        private static void RenderType(GeneratorExecutionContext context, List<ClassModel> classModels, JsonElement jsonElement, string namespaceName, string typeName)
+        /// <summary>
+        /// Reads json and fills the classModels list with relevant type definitions.
+        /// </summary>
+        /// <param name="context">The source generator context</param>
+        /// <param name="classModels">A list that needs to be populated with resolved types</param>
+        /// <param name="jsonElement">The current json element that is being read</param>
+        /// <param name="typeName">The current type name that is being read</param>
+        private static void ResolveTypeRecursive(GeneratorExecutionContext context, List<ClassModel> classModels, JsonElement jsonElement, string typeName)
         {
             var classModel = new ClassModel(typeName);
 
+            // Arrays should be enumerated and handled individually
             if (jsonElement.ValueKind == JsonValueKind.Array)
             {
                 var jsonArrayEnumerator = jsonElement.EnumerateArray();
                 while (jsonArrayEnumerator.MoveNext())
                 {
-                    RenderType(context, classModels, jsonArrayEnumerator.Current, namespaceName, typeName);
+                    ResolveTypeRecursive(context, classModels, jsonArrayEnumerator.Current, typeName);
                 }
 
                 return;
             }
 
+            // Iterate the properties of the json element, they will become model properties
             foreach (JsonProperty prop in jsonElement.EnumerateObject())
             {
                 string propName = GetValidName(prop.Name);
                 if (propName.Length > 0)
                 {
                     PropertyModel propertyModel;
 
+                    // The json value kind of the property determines how to map it to a C# type
                     switch (prop.Value.ValueKind)
                     {
                         case JsonValueKind.Array:
                             {
                                 string arrPropName = GetValidName(prop.Name, true);
 
+                                // Look at the first element in the array to determine the type of the array
                                 var arrEnumerator = prop.Value.EnumerateArray();
                                 if(arrEnumerator.MoveNext())
                                 {
@@ -157,7 +189,7 @@ private static void RenderType(GeneratorExecutionContext context, List<ClassMode
                                     }
                                     else
                                     {
-                                        RenderType(context, classModels, prop.Value, namespaceName, arrPropName);
+                                        ResolveTypeRecursive(context, classModels, prop.Value, arrPropName);
                                     }
 
                                     propertyModel = new PropertyModel(prop.Name, $"IList<{arrPropName}>", propName)
@@ -182,7 +214,9 @@ private static void RenderType(GeneratorExecutionContext context, List<ClassMode
                         case JsonValueKind.Object:
                             {
                                 string objectPropName = GetValidName(prop.Name, true);
-                                RenderType(context, classModels, prop.Value, namespaceName, objectPropName);
+
+                                // Create a separate type for objects
+                                ResolveTypeRecursive(context, classModels, prop.Value, objectPropName);
 
                                 propertyModel = new PropertyModel(prop.Name, objectPropName, propName);
                                 break;
@@ -196,19 +230,30 @@ private static void RenderType(GeneratorExecutionContext context, List<ClassMode
                 }
             }
 
+            // If there is already a model defined that matches by name, then we add any new properties by merging the models
             var matchingClassModel = classModels.FirstOrDefault(c => string.Equals(c.ClassName, classModel.ClassName, StringComparison.InvariantCulture));
             if (matchingClassModel != null)
             {
                 matchingClassModel.Merge(classModel);
             }
             else
             {
+                // No need to merge, just add the new class model
                 classModels.Add(classModel);
             }
         }
 
+        /// <summary>
+        /// Gets a name that is valid in C# and makes it Pascal-case.
+        /// Optionally, it can singularize the name, so that a list property has a proper model class.
+        /// E.g. Cars will have a model type of Car.
+        /// </summary>
+        /// <param name="typeName">The type name that is possibly not valid in C#</param>
+        /// <param name="singularize">If true, the name will be singularized if it is plural</param>
+        /// <returns>A valid C# Pascal-case name</returns>
         private static string GetValidName(string typeName, bool singularize = false)
         {
+            // Make a plural form singular using Pluralize.NET
             if (singularize && _pluralizer.IsPlural(typeName))
             {
                 typeName = _pluralizer.Singularize(typeName);
@@ -218,12 +263,14 @@ private static string GetValidName(string typeName, bool singularize = false)
             bool nextCharUpper = true;
             for(int i = 0; i < typeName.Length; i++)
             {
+                // Strip spaces
                 if (typeName[i] == ' ')
                 {
                     nextCharUpper = true;
                     continue;
                 }
 
+                // Pascal casing
                 if (nextCharUpper)
                 {
                     nextCharUpper = false;
@@ -240,8 +287,13 @@ private static string GetValidName(string typeName, bool singularize = false)
             return new string(newTypeName.ToArray());
         }
 
+        /// <summary>
+        /// Initialization of the generator; allows to setup visitors for syntax.
+        /// </summary>
+        /// <param name="context">Code generator context</param>
         public void Initialize(GeneratorInitializationContext context)
         {
+            // No implementation needed here; the generator is entirely driven by use of AdditionalFiles
         }
     }
 }