TemplateBinder 3.0.0

dotnet add package TemplateBinder --version 3.0.0
                    
NuGet\Install-Package TemplateBinder -Version 3.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="TemplateBinder" Version="3.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="TemplateBinder" Version="3.0.0" />
                    
Directory.Packages.props
<PackageReference Include="TemplateBinder" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add TemplateBinder --version 3.0.0
                    
#r "nuget: TemplateBinder, 3.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package TemplateBinder@3.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=TemplateBinder&version=3.0.0
                    
Install as a Cake Addin
#tool nuget:?package=TemplateBinder&version=3.0.0
                    
Install as a Cake Tool

TemplateBinder

A lightweight, Angular-like text template binding library for C# that enables powerful string interpolation with transformation pipelines.

⚠️ Version 3.0 - Breaking Changes

If you're upgrading from v2.x, please read the MIGRATION GUIDE.

Version 3.0.0 is a complete rewrite with breaking changes:

  • Template syntax changed from {...} to {{...}}
  • API changed from IBinder to ITemplate
  • Parameter types changed from classes to structs
  • Requires .NET 8.0 (was .NET Standard 2.0)

See CHANGELOG.md for full details.

Features

  • Simple Syntax: Angular-inspired placeholder syntax {{ParameterName|pipe:param1=value1}}
  • Type-Safe Parameters: Strongly-typed parameter system (TextParameter, NumberParameter, DateTimeParameter, BooleanParameter)
  • Transformation Pipes: Built-in pipes for common formatting needs (datetime, number, boolean)
  • Extensible: Easy-to-implement custom pipes for domain-specific transformations
  • Dependency Injection: First-class support for Microsoft.Extensions.DependencyInjection
  • .NET 8.0: Modern .NET platform with latest C# features
  • High Performance: Token-based architecture with O(1) lookups and readonly structs
  • Reusable Templates: Parse once, bind multiple times for maximum performance

Installation

NuGet Package Manager

Install-Package TemplateBinder

.NET CLI

dotnet add package TemplateBinder

For Dependency Injection Support

dotnet add package TemplateBinder.Extensions.DependencyInjection

Quick Start

using Microsoft.Extensions.DependencyInjection;
using TemplateBinder.Extensions.DependencyInjection;
using TemplateBinder.Parameters;
using TemplateBinder.Services;

// Setup Dependency Injection
var services = new ServiceCollection();
services.AddTemplateBinder(); // Registers built-in pipes

var serviceProvider = services.BuildServiceProvider();

// Resolve ITemplateFactory
var templateFactory = serviceProvider.GetRequiredService<ITemplateFactory>();

// Define your template
var templateString = "Hello {{FirstName}} {{LastName}}!";

// Create a template (parsing happens once)
var template = templateFactory.Create(templateString);

// Bind parameters to the template
var parameters = new IParameter[] {
    new TextParameter("FirstName", "John"),
    new TextParameter("LastName", "Doe")
};

var result = template.Bind(parameters);
// Output: "Hello John Doe!"

Without Dependency Injection

using TemplateBinder.Parameters;
using TemplateBinder.Pipes;
using TemplateBinder.Services;

// Setup services manually
var parser = new TemplateParser();
var placeholderParser = new PlaceholderParser();
var pipeActivator = new PipeActivator([
    typeof(DateTimePipe),
    typeof(NumberPipe),
    typeof(BooleanPipe)
]);
var tokensFactory = new TemplateTokensFactory(placeholderParser, pipeActivator);
var templateFactory = new TemplateFactory(parser, tokensFactory);

// Create and use template
var template = templateFactory.Create("Hello {{FirstName}} {{LastName}}!");
var result = template.Bind([
    new TextParameter("FirstName", "John"),
    new TextParameter("LastName", "Doe")
]);

Template Syntax

Templates use placeholders with the following syntax:

{{ParameterName|pipeName:param1=value1,param2=value2}}
  • ParameterName: The name of the parameter to bind (required)
  • |pipeName: Optional pipe to transform the parameter (uses parameter's default text representation if omitted)
  • :param1=value1: Optional comma-separated pipe parameters

Examples

{{FirstName}}                                            // Simple text binding
{{DateOfBirth|datetime:format=yyyy-MM-dd}}               // Date formatting
{{AccountBalance|number:format=N2}}                      // Number with 2 decimals
{{IsActive|boolean:trueValue=Yes,falseValue=No}}        // Boolean to text

Usage Examples

Complete Example with All Parameter Types

var templateString = @"
User Report
-----------
Name: {{FirstName}} {{LastName}}
Born: {{DateOfBirth|datetime:format=yyyy-MM-dd}}
Login Count: {{LoginTimes}}
Balance: ${{AccountBalance|number:format=N2}}
Active: {{IsActive|boolean:trueValue=Yes,falseValue=No}}
Locked: {{IsLockedOut|boolean:trueValue=Yes,falseValue=No}}";

var template = templateFactory.Create(templateString);

var parameters = new IParameter[] {
    new TextParameter("FirstName", "David"),
    new TextParameter("LastName", "Parker"),
    new DateTimeParameter("DateOfBirth", new DateTime(1980, 08, 15)),
    new NumberParameter("LoginTimes", 85),
    new NumberParameter("AccountBalance", 1750.45M),
    new BooleanParameter("IsActive", true),
    new BooleanParameter("IsLockedOut", false)
};

var result = template.Bind(parameters);

Output:

User Report
-----------
Name: David Parker
Born: 1980-08-15
Login Count: 85
Balance: $1,750.45
Active: Yes
Locked: No

ASP.NET Core Integration

Install the TemplateBinder.Extensions.DependencyInjection package and register services:

public void ConfigureServices(IServiceCollection services)
{
    services.AddTemplateBinder();

    // Or with custom pipes
    services.AddTemplateBinder(typeof(MyCustomPipe), typeof(AnotherCustomPipe));
}

Then inject ITemplateFactory into your services and create templates once, reuse many times:

public class EmailService
{
    private readonly ITemplate _emailTemplate;

    public EmailService(ITemplateFactory templateFactory)
    {
        // ✅ GOOD: Create template once in constructor
        _emailTemplate = templateFactory.Create(
            "Dear {{FirstName}}, your account balance is {{Balance|number:format=C}}."
        );
    }

    public string GenerateEmailBody(User user)
    {
        // ✅ GOOD: Reuse the same template with different parameters
        var parameters = new IParameter[] {
            new TextParameter("FirstName", user.FirstName),
            new NumberParameter("Balance", user.Balance)
        };

        return _emailTemplate.Bind(parameters);
    }
}

⚠️ Performance Tip: Always create templates once (in constructor or static field) and reuse them. Template parsing is expensive, binding is fast.

Microsoft Dependency Injection (Console Apps)

var serviceProvider = new ServiceCollection()
    .AddTemplateBinder()
    .BuildServiceProvider();

var templateFactory = serviceProvider.GetRequiredService<ITemplateFactory>();

Built-in Pipes

DateTime Pipe

Formats DateTime values using standard .NET format strings.

{{BirthDate|datetime:format=yyyy-MM-dd}}              // 2024-03-15
{{Timestamp|datetime:format=o}}                       // ISO 8601 format
{{EventDate|datetime:format=MMMM dd\, yyyy}}          // March 15, 2024

Number Pipe

Formats numeric values using standard .NET numeric format strings.

{{Price|number:format=N2}}         // 1,234.56 (with thousand separators)
{{Amount|number:format=C}}         // $1,234.56 (currency)
{{Percentage|number:format=P2}}    // 12.34% (percentage)

Boolean Pipe

Converts boolean values to custom text representations.

{{IsActive|boolean:trueValue=Active,falseValue=Inactive}}
{{HasAccess|boolean:trueValue=✓,falseValue=✗}}

No Pipe (Default Parameter Text)

If no pipe is specified, the parameter's GetText() method is used:

{{Name}}              // Returns TextParameter.Value
{{Count}}             // Returns NumberParameter.Value.ToString()
{{Date}}              // Returns DateTimeParameter.Value in ISO 8601 format
{{IsActive}}          // Returns "True" or "False"

Creating Custom Pipes

Implement the IPipe interface and add the [PipeName] attribute:

using TemplateBinder.Parameters;
using TemplateBinder.Pipes;

[PipeName("uppercase")]
public class UppercasePipe : IPipe
{
    // Must have exactly one public constructor
    public UppercasePipe()
    {
    }

    public IParameter Transform(IParameter parameter)
    {
        if (parameter is not TextParameter text)
            throw new ArgumentException("Uppercase pipe requires TextParameter");

        var value = text.Value?.ToUpperInvariant();
        return new TextParameter(parameter.Name, value);
    }
}

Custom Pipe with Parameters

[PipeName("truncate")]
public class TruncatePipe : IPipe
{
    private readonly int _maxLength;
    private readonly string _suffix;

    // Constructor parameters match template syntax
    // {{Text|truncate:maxLength=50,suffix=...}}
    public TruncatePipe(string? maxLength, string? suffix)
    {
        _maxLength = int.Parse(maxLength ?? "10");
        _suffix = suffix ?? "...";
    }

    public IParameter Transform(IParameter parameter)
    {
        if (parameter is not TextParameter text)
            throw new ArgumentException("Truncate pipe requires TextParameter");

        var value = text.Value;
        if (value != null && value.Length > _maxLength)
        {
            value = value.Substring(0, _maxLength) + _suffix;
        }

        return new TextParameter(parameter.Name, value);
    }
}

Usage:

{{Description|truncate:maxLength=50,suffix=...}}

Registering Custom Pipes

With Dependency Injection:

services.AddTemplateBinder(typeof(UppercasePipe), typeof(TruncatePipe));

Without Dependency Injection:

var pipeActivator = new PipeActivator([
    typeof(DateTimePipe),
    typeof(NumberPipe),
    typeof(BooleanPipe),
    typeof(UppercasePipe),      // Your custom pipe
    typeof(TruncatePipe)         // Your custom pipe
]);

Parameter Types

All parameter types are readonly structs implementing IParameter with a Name, type-specific Value, and GetText() method.

TextParameter

new TextParameter("Name", "John Doe")
new TextParameter("Description", null)  // Returns parameter name if value is null

NumberParameter

new NumberParameter("Age", 25)
new NumberParameter("Price", 99.99M)
new NumberParameter("Count", null)  // Returns parameter name if value is null

DateTimeParameter

new DateTimeParameter("BirthDate", new DateTime(1990, 1, 15))
new DateTimeParameter("Timestamp", DateTime.Now)
new DateTimeParameter("Date", null)  // Returns parameter name if value is null

BooleanParameter

new BooleanParameter("IsActive", true)
new BooleanParameter("HasAccess", false)
new BooleanParameter("Flag", null)  // Returns parameter name if value is null

Error Handling

Missing parameters will throw an ArgumentException during binding:

var template = templateFactory.Create("Hello {{Name}}!");
var result = template.Bind([]);  // Throws ArgumentException: "Parameter Name was not found"

Important: Always ensure all required parameters are provided. There is no silent fallback option.

Performance

TemplateBinder is designed for high performance:

  • Parse Once, Bind Multiple Times: Template parsing happens once during template creation. Reuse templates for maximum performance.
  • Token-Based Architecture: Uses pre-parsed token objects instead of regex replacement during binding
  • O(1) Lookups: Parameters stored in dictionary, pipe types in FrozenDictionary
  • Readonly Structs: Parameter types are readonly structs for better memory efficiency
  • No Reflection During Binding: Pipe instances created during template parsing, not during binding
// ✅ GOOD: Parse once, bind many times
var template = templateFactory.Create(emailTemplate);
foreach (var user in users)
{
    var email = template.Bind(CreateParameters(user));
    SendEmail(email);
}

// ❌ BAD: Parsing inside the loop
foreach (var user in users)
{
    var template = templateFactory.Create(emailTemplate);  // DON'T DO THIS!
    var email = template.Bind(CreateParameters(user));
    SendEmail(email);
}

Performance Tips

  1. ✅ ALWAYS create templates once, reuse many times

    // ✅ GOOD: Parse once
    private readonly ITemplate _template;
    public MyService(ITemplateFactory factory)
    {
        _template = factory.Create("Hello {{Name}}!");
    }
    public string Generate(string name) => _template.Bind([new TextParameter("Name", name)]);
    
    // ❌ BAD: Parsing on every call
    public string Generate(string name)
    {
        var template = _factory.Create("Hello {{Name}}!");  // Expensive!
        return template.Bind([new TextParameter("Name", name)]);
    }
    
  2. Use dependency injection: Services are registered as singletons

  3. For static templates: Consider static readonly fields

    public class Constants
    {
        private static readonly ITemplateFactory _factory = CreateFactory();
        public static readonly ITemplate WelcomeEmail = _factory.Create("Welcome {{Name}}!");
    }
    

Requirements

  • .NET 8.0 or higher
  • Latest C# version with nullable reference types enabled

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Alkiviadis Skoutaris

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net8.0

    • No dependencies.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on TemplateBinder:

Package Downloads
TemplateBinder.Extensions.DependencyInjection

Microsoft.Extensions.DependencyInjection integration for TemplateBinder. Provides AddTemplateBinder() extension method for easy service registration.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
3.0.0 2,206 10/19/2025
2.0.2 332 3/20/2025
2.0.1 323 3/20/2025
2.0.0 963 3/10/2022
1.0.1 2,751 12/30/2020
1.0.0 779 12/30/2020

⚠️ BREAKING CHANGES - Complete architectural rewrite. Not backward compatible with v2.x. See https://github.com/askoutaris/template-binder/blob/main/MIGRATION.md for migration guide. Major changes: Template syntax {{...}}, ITemplate API, struct parameters, .NET 8.0 required. Performance: Token-based architecture with O(1) lookups, FrozenDictionary, readonly structs.