Dartk.ScribanGen 0.3.2

ScribanGen

A C# source generator that renders Scriban templates.

• Installation
• Source generation
• Saving generated files
• Limitations
• Example

Installation

dotnet add package Dartk.ScribanGen

To avoid propagating dependency on the package set the option PrivateAssets="all" in the project file:

<ItemGroup>
    <PackageReference Include="Dartk.ScribanGen" Version="0.3.2" PrivateAssets="All" />
</ItemGroup>

Source generation

Include scriban template files with .scriban extension to the project as AdditionalFiles. For example, to render all scriban templates in the ScribanTemplates folder add this to the project file:

<ItemGroup>
    <AdditionalFiles Include="ScribanTemplates/**" />
</ItemGroup>

A complete example is presented below.

Templates that have file names starting with an underscore will not be rendered. But they can be included in other templates using include statement. For instance

• _template.scriban - will not be rendered, can be included in other templates
• other-template.scriban - will be rendered

Warning: Microsoft Visual Studio 22 (tested on version 17.4.3 on Windows OS) will call a source generator on every edit of the files that are being cached by the generator. Thus, every character insertion or deletion in a .scriban template will cause the template rendering. Therefore, edit those files in an external editor for better performance.

Saving generated files

To save the generated source files set properties EmitCompilerGeneratedFiles and CompilerGeneratedFilesOutputPath in the project file:

<PropertyGroup>
    <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
    
    <CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)\GeneratedFiles</CompilerGeneratedFilesOutputPath>
</PropertyGroup>

Limitations

Passing parameters to scriban templates is not supported.

Example

Create a new console C# project:

dotnet new console Example

Install the package Dartk.ScribanGen and set the property PrivateAssets="All" by editing the project file Example.csproj:

<ItemGroup>
    <PackageReference Include="Dartk.ScribanGen" Version="0.3.2" PrivateAssets="All"/>
</ItemGroup>

Create a ScribanTemplates folder in the project directory and include it's content as AdditionalFiles:

<ItemGroup>
    <AdditionalFiles Include="ScribanTemplates/**" />
</ItemGroup>

Add the following files to the ScribanTemplates folder:

_numbers.scriban

{{

# File name starts with an underscore, therefore will not be rendered.
# But it can be included in other templates.

numbers = [ "one", "two", "three" ]

}}

Number.scriban

{{- include '_numbers.scriban'    # include statement is supported -}}

namespace Generated;

public record Number(int Int, string String) {
    {{- i = 0 }}
    {{- for number in numbers    # using variable 'numbers' from '_numbers.scriban' }}
    public static readonly Number {{ string.capitalize number }} = new ({{ ++i }}, "{{ number }}");
    {{- end }}
}

The generator will skip _numbers.scriban but render Number.scriban:

// Generated by Dartk.SourceGen.Scriban from 'Number.scriban'
namespace Generated;

public record Number(int Int, string String) {
    public static readonly Number One = new (1, "one");
    public static readonly Number Two = new (2, "two");
    public static readonly Number Three = new (3, "three");
}

Now Generated.Number class can be used in your code.

Put this in the Program.cs:

using static System.Console;

WriteLine(Generated.Number.One);
WriteLine(Generated.Number.Two);
WriteLine(Generated.Number.Three);

Code above will write the following:

Number { Int = 1, String = one }
Number { Int = 2, String = two }
Number { Int = 3, String = three }