Table of Contents

Quickstart

The cstemplate extension for VSCode provides functionality that is similar to T4 templates in Visual Studio, but without the need to learn a separate templating language or to edit complex syntax containing a mix of C# code and embedded template instructions. Template files (*.template.cs) are written in pure C#, so can use any C# language features (StringBuilder, interpolated strings, etc) to generate and format output. If required, templates can also reference NuGet packages and custom DLLs at design time. Standard C# Dev Kit functionality and intellisense provides full support for editing, compiling and debugging templates, while the extension provides context menu, keyboard shortcuts and command palette options to generate code directly within VSCode.

Configuration files placed alongside the templates can be used to define template inputs (argument values, .json or .xml models, database connections, etc). The same template can be reused in multiple projects to generate output specific to each project.

Template output is simply one or more text files, written to a target location relative to the current project / solution. An individual template can be used to generate a single C# class, produce boilerplate code for data access objects, or to scaffold an entire project.

Prerequisites

  • .NET 10 runtime
  • VS Code with the C# Dev Kit extension

1. Install the CLI tool

dotnet tool install --global HoofMark.CSharpTemplating.Cli

2. Install the VS Code extension

Install cstemplate from the VS Code Marketplace.

3. Add the abstractions package

In your project's .csproj, add a reference to HoofMark.CSharpTemplating.Abstractions:

<ItemGroup>
  <PackageReference Include="HoofMark.CSharpTemplating.Abstractions" Version="0.1.0" />
</ItemGroup>

4. Write a template

Create a .template.cs file anywhere in your project. Each template is a class that implements ITemplate with a static void Run(ITemplateContext) method. Give each template a unique class name and namespace:

using HoofMark.CSharpTemplating.Abstractions;

namespace MyProject.Templates;

public class OrderServiceTemplate : ITemplate
{
    public static void Run(ITemplateContext context)
    {
        var ns = context.Config.Get("Namespace");

        context.WriteFile("OrderService.cs", w => w
            .WriteLine($"namespace {ns};")
            .Block("public class OrderService", body => body
                .WriteLine("// Generated by cstemplate")
            ));
    }
}

This example uses the built-in IOutputWriter syntax, which enables features to assist with code formatting and indentation. However, any valid C# construct can be used to generate the output string. Refer to the examples for a selection of alternative options; choose the approach that best fits your coding style and standards.

5. Add a config file

Place a sibling .json file with the same base name to supply config values:

{
  "Namespace": "MyApp.Generated"
}

So for OrderServiceTemplate.template.cs, create OrderServiceTemplate.template.json (or just OrderServiceTemplate.json - both formats are supported).

6. Run the template

From VS Code: right-click OrderServiceTemplate.template.cs in the Explorer and choose Run Template.

From the terminal:

cstemplate run src/templates/OrderServiceTemplate.template.cs

The generated OrderService.cs will appear in a generated/ folder next to the template, or in the outputRoot specified in cstemplate.config.json.

Next steps

Edit this page