template.json

.NET template files

Type object
File match **/.template.config/template.json
Schema URL https://catalog.lintel.tools/schemas/schemastore/template-json/latest.json
Source https://www.schemastore.org/template.json

Validate with Lintel

npx @lintel/lintel check
Type: object

Properties

author string required

The author of the template.

classifications string[] required

Zero or more characteristics of the template that a user might search for it by.

identity string required

A unique name for this template.

minLength=1
name string required

The name for the template that users should see.

minLength=1
shortName string | string[] required
minLength=1
tags object required

Common information about templates, these are effectively interchangeable with choice type parameter symbols.

2 nested properties
type enum required

The type of template: project or item.

Values: "project" "item" "solution"
language string

The programming language the template primarily contains or is intended for use with.

defaultName string

The name to use during creation if no name has been specified by the user or provided from the host.

minLength=1
generatorVersions string

The semantic version range of the Microsoft.TemplateEngine.Orchestrator.RunnableProjects package that this template is usable with. In older versions of the engine, the four octet version string is used but is matched against a constant which was never changed from 1.0.0.0 - either syntax is now accepted, however the four octet string will not be changed from 1.0.0.0.

Default: "[1.0.0.0-*)"
groupIdentity string

The ID of the group this template belongs to. When combined with the "tags" section, this allows multiple templates to be displayed as one, with the the decision for which one to use being presented as a choice in each one of the pivot categories (keys).

minLength=1
guids guid[]

A list of guids which appear in the template source and should be replaced in the template output. For each guid listed, a replacement guid is generated, and replaces all occurrences of the source guid in the output.

uniqueItems=true
placeholderFilename string

A filename that will be completely ignored except to indicate that its containing directory should be copied. This allows creation of an empty directory in the created template, by having a corresponding source directory containing just the placeholder file. Completely empty directories are ignored.

Default: "-.-"
postActions object[]

Defines an ordered list of actions to perform after template generation. The post action information is provided to the creation broker, to act on as appropriate.

precedence integer | string

A value used to determine how preferred this template is among the other templates with the same groupIdentity (higher values are more preferred).

Default: 0
pattern=^([0-9]+)$
preferDefaultName boolean

Indicated which behaviour to use when no --name is specified during template creation. If true it will use the template's defaultName. If no defaultName is found, or preferDefaultName is false it uses the fallback (output folder).

preferNameDirectory boolean

Indicates whether to create a directory for the template if name is specified but an output directory is not set (instead of creating the content directly in the current directory).

primaryOutputs object[]

A list of important output paths created during template generation. These paths need to be added to the newly created project at the end of template creation.

sourceName string

The text in the source content to replace with the name the user specifies. The value of the 'sourceName' is available in built-in 'name' symbol that can be used as the source for creating other symbols and condition expressions. See important information about how to select correct 'sourceName' in https://github.com/dotnet/templating/wiki/Naming-and-default-value-forms.

sources source[]

The set of mappings in the template content to user directories.

Default:
{
  "source": "./",
  "target": "./"
}
forms Record<string, object>

Custom value forms used by the template.

symbols Record<string, object>

The symbols section defines variables and their values, the values may be the defined in terms of other symbols. When a defined symbol name is encountered anywhere in the template definition, it is replaced by the value defined in this configuration. The symbols configuration is a collection of key-value pairs. The keys are the symbol names, and the value contains key-value-pair configuration information on how to assign the symbol a value.

baselines Record<string, object>

Alternate sets of defaults for symbols.

thirdPartyNotices string

An URL for a document indicating any libraries used by the template that are not owned/provided by the template author.

description string

A description of the template's purpose or contents for use in help.

constraints Record<string, object>

The constraints section defines the restrictions when the template can be run. Available since .NET SDK 7.0.100.

Definitions

datatype enum

Indicates limitations on the valid values a symbol may be assigned. When specified, the symbol value is attempted to be converted to this type. The datatype "choice" is supported only for parameter symbols and requires providing symbols.choices configuration for the symbol.

generatorConstant
generator enum
Values: "constant"
parameters
1 nested properties
value string

The constant value to be assigned to the symbol.

generatorGuid
generator enum
Values: "guid"
parameters
2 nested properties
format string

This property is not maintained and may be removed in the future. Use defaultFormat instead, or use 'guids' section.

defaultFormat string

The format of guid to be generated. Accepts a single value from ('n', 'd', 'b', 'p', 'x') for lowercase output or ('N', 'D', 'B', 'P', 'X') for uppercase output. The formats are defined in Guid.ToString() method documentation.

generatorNow
generator enum
Values: "now"
parameters
2 nested properties
format string

The format string to use when converting the date-time to a string representation.

utc boolean

If true, use UTC time. If false, use local time.

generatorRandom
generator enum
Values: "random"
parameters object
2 nested properties
low integer required

An integer value indicating the low-end of the range to generate the random number in.

high integer

An integer value indicating the high-end of the range to generate the random number in. If not explicitly provided, defaults to int.MaxValue.

generatorRegex
generator enum
Values: "regex"
parameters
2 nested properties
source string

The name of a different parameter in the template configuration. A copy of its value will be used by this generator's regex to generate the value for this parameter. The value of the source parameter is not modified.

steps object[]

An ordered list of key-value pairs indicating the regex replacement actions. Each element of the list must contain exactly the keys 'regex' and 'replacement' - along with their values. These replacements will be applied to the result of the previous replacement (except the first, which acts on the original value from the source).

generatorRegexMatch
generator enum
Values: "regexMatch"
datatype enum
Values: "bool"
parameters
2 nested properties
source string

The symbol to search for a match. Its value will be used by this generator's regex to evaluate if there is a match. The value of the source parameter is not modified.

pattern string

The regular expression to use to match.

generatorCoalesce
generator enum
Values: "coalesce"
parameters object
3 nested properties
sourceVariableName string required

The name of the symbol whose value will be inspected - if the value is effectively equal to the default value, the value of the symbol referred to by fallbackVariableName is used, otherwise the value of this symbol.

fallbackVariableName string required

The name of the symbol to return the value of if the symbol referred to by sourceVariableName has a value equal to the value of defaultValue.

defaultValue string

The value to consider as being the default - if the value of the symbol referred to by sourceVariableName is equal to this, the value of the symbol referred to in fallbackVariableName is used instead.

Default: ""
generatorCasing
generator enum
Values: "casing"
parameters object
2 nested properties
source string required

The name of the symbol whose value should have its case changed.

toLower boolean

Whether the case changed to should be lower case, if false, the value is made to be uppercase instead.

Default: true
generatorPort
generator enum
Values: "port"
parameters
3 nested properties
low integer

The lower bound of acceptable port numbers.

Default: 1024
high integer

The upper bound of acceptable port numbers.

Default: 65535
fallback integer

The port number to use if no free ports could be found.

Default: 0
generatorSwitch
generator enum
Values: "switch"
parameters
3 nested properties
evaluator enum

The style of evaluator to use.

Default: "C++"
Values: "C++" "C++2" "MSBUILD" "VB"
datatype enum

Indicates limitations on the valid values a symbol may be assigned. When specified, the symbol value is attempted to be converted to this type. The datatype "choice" is supported only for parameter symbols and requires providing symbols.choices configuration for the symbol.

cases object[]

The set of cases to test for. The first one, in document order, to return true's value is used, if none return true, empty string is returned.

generatorJoin
generator enum
Values: "join"
parameters
3 nested properties
separator string

The value used as the separator between the values to be concatenated, notice that you can use "/" as folder separator also on Windows since File API will convert it into "".

Default: ""
removeEmptyValues boolean

Indication whether null and empty strings should be removed from joining to prevent repetitive separators.

Default: "false"
symbols object[]

All values to concatenate.

guid string

A guid string to be replaced in source files. Format and casing is not significant in the config as format and casing is preserved based on the particular guid in processed file(s).

ice string[] | string
modifier object
condition string

Boolean condition to indicate if the sources configuration should be included or ignored. If the condition evaluates to true or is not provided, the sources config will be used for creating the template. If it evaluates to false, the sources config will be ignored.

exclude

The set of globbing patterns indicating the content that was included by sources.include that should not be processed.

Default:
[
  "**/[Bb]in/**",
  "**/[Oo]bj/**",
  ".template.config/**/*",
  "**/*.filelist",
  "**/*.user",
  "**/*.lock.json"
]
All of: ice string[] | string
include

The set of globbing patterns indicating the content to process in the path referred to by the source.

Default:
[
  "**/*"
]
All of: ice string[] | string
copyOnly

The set of globbing patterns indicating the content that was included by sources.include, that hasn't been excluded by sources.exclude that should be placed in the user's directory without modification.

Default:
[
  "**/node_modules/**/*"
]
All of: ice string[] | string
rename Record<string, string>

The set of explicit renames to perform. Each key is a path to a file in the source, each value is a path to the target location.

source object
modifiers modifier[]

A list of additional source information which gets added to the top-level source information, based on evaluation the corresponding source.modifiers.condition.

source string

The path in the template content (relative to the directory containing the .template.config folder) that should be processed.

Default: "./"
target string

The path (relative to the directory the user has specified) that content should be written to.

Default: "./"