cstemplate for VS Code

Run C# template files (.template.cs) directly from VS Code.

For full documentation, see hoofmark.github.io/cstemplate.

Requirements

• .NET 10 runtime or later — required to run the cstemplate CLI tool
• Template projects may target .NET 8 or later; the tool resolves NuGet packages and local assemblies for net8.0, net9.0, and net10.0 projects automatically

Install the cstemplate CLI as a global dotnet tool:

dotnet tool install --global HoofMark.CSharpTemplating.Cli

Or point the extension at a local build via the cstemplate.cliPath setting.

Usage

• Right-click any .template.cs file in the Explorer → Run Template
• Command Palette → cstemplate: Run Template
• Keyboard shortcut Ctrl+Shift+T / Cmd+Shift+T when a template is open
• Templates are checked on save automatically — compile errors appear as squiggles

Template Structure

A template is a .template.cs file containing a class that implements ITemplate. Each template must have a unique class name and its own namespace so that multiple templates can coexist in the same project without conflicts:

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("Output.cs", w => w
            .WriteLine($"namespace {ns}")
            .Block("public class GeneratedClass", body => body
                .WriteLine("// Generated by cstemplate")
            ));
    }
}

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

{
  "Namespace": "MyApp.Generated"
}

Project Setup

Add a reference to HoofMark.CSharpTemplating.Abstractions in your template project's .csproj. Template files are included in the project as normal C# files, giving you full IntelliSense, go-to-definition, and error squiggles via C# Dev Kit:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="HoofMark.CSharpTemplating.Abstractions" Version="0.1.0" />
    <!-- Add any NuGet packages your templates reference here -->
    <PackageReference Include="Humanizer.Core" Version="2.14.1" />
  </ItemGroup>
</Project>

The template classes will be included in the project's compiled output, but this is harmless — cstemplate compiles each template independently at runtime in its own isolated context and never invokes the copies in the project assembly.

Note on local assembly references: Any local .dll files referenced in cstemplate.config.json must target .NET 10 or earlier. Assemblies built for a newer runtime than the tool itself cannot be loaded.

Workspace Configuration

Place a cstemplate.config.json file in your project folder (or any parent folder) to configure output locations, local assembly references, and NuGet packages:

{
  "outputRoot": "../generated",
  "project": "./Samples.csproj",
  "nugetPackages": [
    "Humanizer.Core"
  ],
  "references": [
    "path/to/LocalAssembly.dll"
  ]
}

Field	Description
outputRoot	Output root for generated files, relative to this config file. Overridden by --output CLI argument.
project	Path to the template project's .csproj, relative to this config file. Required when using nugetPackages.
nugetPackages	NuGet package IDs to make available to templates. Versions and transitive dependencies are resolved automatically from the project's restored assets.
references	Paths to local .dll files, relative to this config file.

NuGet Package Resolution

cstemplate resolves NuGet packages from the project's obj/project.assets.json file, which is generated by dotnet restore. This means:

• No separate package download — packages are resolved from the standard NuGet global packages cache, the same one used by dotnet build
• Transitive dependencies handled automatically — if Humanizer.Core depends on other packages, those are included too
• Versions come from the project — no need to specify versions in cstemplate.config.json, they are taken from whatever the project has restored
• Framework compatibility — the tool targets net10.0 and resolves packages for net10.0, net9.0, and net8.0 projects automatically

Important: Run dotnet restore on the project before running cstemplate if you have added or changed NuGet package references. cstemplate will report a clear error if the assets file is missing or out of date.

Settings

Setting	Default	Description
cstemplate.cliPath	cstemplate	Path to the cstemplate CLI executable
cstemplate.outputRoot	(empty)	Default output root; if empty, uses generated/ next to each template
cstemplate.checkOnSave	true	Run compile check on save
cstemplate.showOutputOnRun	true	Show output panel when running a template
cstemplate.templateFilePattern	**/*.template.cs	Glob pattern to identify template files

Further Reading

• Full documentation
• CLI reference
• API reference
• Source on GitHub