template-authoring

Template Authoring

This skill helps an agent create and validate custom dotnet new templates. It guides bootstrapping templates from existing projects and validates template.json files for authoring issues before publishing.

When to Use

• User wants to create a reusable template from an existing .csproj
• User wants to validate a template.json for correctness
• User is setting up .template.config/template.json from scratch
• User wants to package a template for NuGet distribution

When Not to Use

• User wants to find or use existing templates — route to template-discovery or template-instantiation
• User has MSBuild issues unrelated to template authoring — route to dotnet-msbuild plugin

Inputs

Workflow

Step 1: Bootstrap from existing project

Analyze the source .csproj and create a .template.config/template.json that preserves the project's conventions:

1. Create the .template.config directory next to the project
2. Generate template.json with:
   • identity in reverse-DNS format (e.g., MyOrg.Templates.MyLib)
   • name as the human-readable template name
   • shortName for dotnet new <shortname> usage
   • sourceName set to the project name (enables name replacement)
   • classifications for discoverability (e.g., ["Library"])
   • tags with language and type

Example generated template.json:

{
  "$schema": "http://json.schemastore.org/template",
  "author": "MyOrg",
  "classifications": ["Library"],
  "identity": "MyOrg.Templates.MyLib",
  "name": "My Library Template",
  "shortName": "mylib",
  "sourceName": "MyLib",
  "tags": {
    "language": "C#",
    "type": "project"
  },
  "symbols": {
    "Framework": {
      "type": "parameter",
      "datatype": "choice",
      "defaultValue": "net9.0",
      "choices": [
        { "choice": "net9.0" },
        { "choice": "net10.0" }
      ],
      "replaces": "net9.0"
    }
  }
}

Preserve from the source project:

• SDK type, package references with metadata (PrivateAssets, IncludeAssets)
• Properties (OutputType, TreatWarningsAsErrors)
• Central Package Management and shared compile patterns

Step 2: Validate template.json

Read and review the template.json for common authoring issues:

Validation checks to perform:

• Required fields — verify identity, name, and shortName are present
• Identity format — use reverse-DNS format (e.g., MyOrg.Templates.WebApi)
• Parameter issues — check datatypes are valid (string, bool, choice, int, float), choices have defaults, descriptions are present
• ShortName conflicts — avoid names that collide with built-in CLI commands (build, run, test, publish). Check with dotnet new list to see if the name is already taken
• Post-action completeness — verify post-actions have all required configuration
• Tags — ensure language, type, and classification tags are set for discoverability

Step 3: Refine the template

Based on validation results and user requirements:

1. Add parameters with appropriate types (string, bool, choice), defaults, and descriptions
2. Add conditional content using #if preprocessor directives for optional features
3. Configure post-actions for solution add, restore, or custom scripts
4. Set constraints to restrict which SDKs or workloads the template supports
5. Add classifications and tags for discoverability

Step 4: Test the template locally

1. Install the template from the local directory:

   dotnet new install ./path/to/template/root
   

2. Run a dry-run to verify the output:

   dotnet new mylib --name TestProject --dry-run
   

3. Create a test project and verify it builds:

   dotnet new mylib --name TestProject --output ./test-output
   dotnet build ./test-output/TestProject
   

4. Verify all parameters produce the expected output

Step 5: Package for distribution

1. Create a .nuspec or use <PackAsTool> in a packaging .csproj
2. Include the template directory with .template.config/template.json
3. Run dotnet pack to create the .nupkg
4. Test installation from the .nupkg:

   dotnet new install ./path/to/package.nupkg
   

Validation

• template.json passes manual validation with zero errors
• Template identity and shortName are unique and meaningful
• All parameters have descriptions and appropriate defaults
• Template can be installed, dry-run, and instantiated successfully
• Created projects build cleanly with dotnet build
• Conditional content produces correct output for all parameter combinations

Common Pitfalls

More Info

• Custom templates for dotnet new — official authoring guide
• template.json reference — full schema reference
• Template Engine Wiki — template engine internals