Integration for TemplR with System.Text.Json.
$ dotnet add package TemplR.System.Text.JsonSerializable, Type-safe Payload Enrichment for .NET
TemplR is a .NET library designed to facilitate API payload and event payload templating. It allows developers to define strongly typed, serializable templates where certain properties can be replaced with variables. This enables dynamic payload generation while maintaining type safety.
TemplR can be installed from NuGet:
Install-Package TemplR
or using the .NET CLI:
dotnet add package TemplR
TemplR supports two different approaches for creating templates:
TemplR.Generator (Code Generation, Recommended)
[Template] attributes on partial classes.From.Expression (Runtime Reflection, Alternative Approach)
If you don't mind using code generation, the [Template] approach is generally easier to use than From.Expression.
TemplR can auto-generate proxies from your existing data objects, allowing properties to be replaced by strongly typed variables. To create a proxy from an existing record or class, you first need to install TemplR's code generator library:
Install-Package TemplR.Generator
Next, define a new proxy by creating a partial class decorated with the [Template] attribute:
[Template(typeof(Person))]
public partial class PersonTemplate {}
The TemplateAttribute takes a single argument equal to the type being proxied. After defining this, you can create a new PersonTemplate instance with properties that support variable substitution:
var person = new PersonTemplate
{
Name = "Santa Claus",
Age = From.Variable("yearsSinceFirstChristmas"),
IsImaginary = From.Variable(),
Sleighs = From.Collection<string>([
"V8 TurboSleigh 5000",
From.Variable("backupSleigh")
]),
Reindeers = From.Variable("reindeers")
};
If no name is passed to From.Variable, the variable will take the same name as the property it is assigned to.
This proxy can be passed to any method that accepts either Template or Template<Person> as a parameter.
If reusable, type-safe variables are needed, it is often useful to define them in a static class:
public static class PersonVariables
{
public static Variable<int> YearsSinceFirstChristmas => From.Variable<int>("yearsSinceFirstChristmas");
public static Variable<bool> IsImaginary => From.Variable<bool>("isImaginary");
public static Variable<IEnumerable<string>> Reindeers => From.Variable<IEnumerable<string>>("reindeers");
public static Variable<string> BackupSleigh => From.Variable<string>("backupSleigh");
} var person = new PersonTemplate
{
Name = "Santa Claus",
Age = PersonVariables.YearsSinceFirstChristmas,
IsImaginary = PersonVariables.IsImaginary,
Reindeers = PersonVariables.Reindeers,
Sleighs = From.Collection([
"V8 TurboSleigh 5000",
PersonVariables.BackupSleigh
])
};If you want to avoid using code generation, you can use runtime reflection instead by utilizing the From.Expression method.
To use this approach, define a record or class that describes the variables you wish to use:
public record PersonVariables(int Age, bool Imaginary);By default, variable names will be camel case versions of the property names. You can customize this behavior using attributes:
public record PersonVariables(bool Imaginary)
{
[TemplateVariable("Age")]
public required int Age { get; init; }
} [TemplateVariableSet(UseCamelCase = false)]
public record PersonVariables(int Age, bool Imaginary);Now, you can call From.Expression to produce a new template:
var template = From.Expression<Person, PersonVariables>((vars) => new()
{
Name = "Santa Claus",
Age = vars.Age,
IsImaginary = vars.Imaginary
});Any call to vars will be replaced with a placeholder when serialized.
TemplR supports both serialization and deserialization using System.Text.Json. To enable this functionality, install the required library:
Install-Package TemplR.System.Text.Json
To add the necessary converters, create an instance of JsonSerializerOptions and call the UseTemplR() extension method:
JsonSerializerOptions serializerOptions = new()
{
WriteIndented = true,
PropertyNamingPolicy = JsonNamingPolicy.CamelCase
};
serializerOptions.UseTemplR();From that point on, these options should be used for all calls to JsonSerializer.
To serialize a template with replacement values, first deserialize it into the Template type, call SetVariables, and then re-serialize it:
var template = JsonSerializer.Deserialize<Template>(json, serializerOptions);
template.SetVariables(new()
{
{ "yearsSinceFirstChristmas", 42 },
{ "isImaginary", false }
});
var jsonWithVariables = JsonSerializer.Serialize(template, serializerOptions);This replaces any placeholders in the template with the actual values during serialization.
By default TemplR serializes variables using the format ${myVariable}. This can be customised by passing a configuration object to the UseTemplR method. For example the code below configures TemplR to use the format $myVariable...
serializerOptions.UseTemplR(new() { VariableNamingStrategy = VariableNamingStrategy.DollarOnly });To implement a custom variable naming strategy, implement the abstract class VariableNamingStrategy and pass an instance as shown above.