Add C# Source Generator

[valchetski]

What's in this PR

This change aims to add a C# Source generator that automatically creates classes based on JSON schema. The idea is to make code generation more straightforward for generic scenarios. I've tried that approach on my project and it worked quite well. I thought it'd be good to make it a part of the library. This Source Generator has few configurable properties and can be extended in the future if needed.

Current approach

To generate C# classes you need to create a separate console project that will generate a .cs file and put it somewhere in your Solution. Then you need to manually run that console application to generate/regenerate the models. Here's example

New (additional) approach

Add the following elements in the .csproj file of your project where the generated .cs file will exist:

  <ItemGroup>
    <PackageReference Include="NJsonSchema.SourceGenerators.CSharp" />
  </ItemGroup>

  <ItemGroup>
    <AdditionalFiles 
        Include="schema.json" 
        NJsonSchema_GenerateOptionalPropertiesAsNullable="true" 
        NJsonSchema_Namespace="NJsonSchema.Demo.Generated" 
        NJsonSchema_TypeNameHint="PersonGenerated" 
        NJsonSchema_FileName="Person.g.cs" />
  </ItemGroup>

After that Source Generator will automatically create a .cs file during compilation. No additional console project or manual job is needed.

Concerns

I have some questions/concerns regarding the implementation and have put them in the comments. We can start from this main one.

Also added some explanatory comments about why something was implemented that way. As tooling for the Source Generators is not the best for now and there is a lot of msbuild magic in the .csproj files.

[valchetski]

Source generators do not support transient dependencies: dotnet/sdk#17775
Because of that need to explicitly install some transient packages.
For example, it'll be used here to include Parlot into NuGet package https://github.com/RicoSuter/NJsonSchema/pull/1726/files#diff-ead3877feb09b2619c61d0feb8b85e0c85c627756febe0dda0829dafe13d5325R39

[valchetski]

In this project you can see how Source Generator actually works

[valchetski]

With PrivateAssets="All" it will not add NJsonSchema.CodeGeneration.CSharp as a dependency of NJsonSchema.SourceGenerators.CSharp NuGet package as I assume it's not needed. Code from NJsonSchema.SourceGenerators.CSharp should be enough to generate C# classes. For more advanced scenarios NJsonSchema.CodeGeneration.CSharp can be installed explicitly in client's projects.

[valchetski]

Deliberately didn't add PrivateAssets="all" for Newtonsoft.Json so it will be included as NuGet dependency. In the generated code Newtonsoft attributes will be used. That way client don't need to install Newtonsoft.Json in their project explicitly.

[valchetski]

My main concern is whether we should create a separate project for the source generator or add them to the existing NJsonSchema.CodeGeneration.CSharp. Frankly speaking, I didn't try the second approach at all, but in theory, it should work.
Below are my thoughts.

Add Source Generator to new NJsonSchema.SourceGenerators.CSharp

Pros:

• Clients will install that package only if they know they need to use a source generator.
• Easier to maintain as source generator projects require additional configuration (IsRoslynComponent, exclude NU5128 warning, etc.)

Cons:

• The names of the NuGet packages could be confusing. NJsonSchema.CodeGeneration.CSharp and NJsonSchema.SourceGenerators.CSharp may sound a bit synonimical.

Add Source Generator to existing NJsonSchema.CodeGeneration.CSharp

Pros:

• We don't introduce a new NuGet package.
• By installing NJsonSchema.CodeGeneration.CSharp client can use either classes from the library or/and Source Generator.

Cons:

• It'll automatically install the source generator when the client does a package upgrade. (However, the source generator will not do much without additional configuration. Not sure if this is an issue).
• The size of the NuGet package will slightly increase as it'll include DLLs for the source generator.
• The project might be harder to maintain as it will be a mix of regular code and code that will go to the source generator.

[HavenDV]

You can check my implementation of Source Generator for NSwag to see how to support transient packages automatically https://github.com/HavenDV/H.NSwag.Generator

[valchetski]

You can check my implementation of Source Generator for NSwag to see how to support transient packages automatically https://github.com/HavenDV/H.NSwag.Generator

Thank you @HavenDV. Amazing library 🙂 However, I have some issues with project references. I asked about them here: HavenDV/H.Generators.Extensions#15

[valchetski]

This is how dependencies are added to the NuGet package. More details here https://github.com/dotnet/roslyn/blob/main/docs/features/incremental-generators.cookbook.md#use-functionality-from-nuget-packages

[valchetski]

In case if Source Generator needs to be added as a project reference (in NJsonSchema.Demo) it needs additional configuration. More details here https://www.thinktecture.com/en/net/roslyn-source-generators-using-3rd-party-libraries/

[valchetski]

Without that change build of NJsonSchema.SourceGenerators.CSharp.Tests was failing. Here suggests to make it internal if code is a part of a library