Available Symbols Generators

Inside the template.json file, you can define custom symbols that will be used inside the template files. The supported symbol types are:

• Parameter - the value is typically provided by the user when creating the template. If not provided, the value is taken from host configuration, otherwise default value is used.
• Derived - defines transformation of another symbol. The value of this symbol is derived from the value of another symbol by applying the defined form.
• Computed - the boolean value is evaluated during the processing of the template based on the other symbol values.
• Generated - the value is computed by a built-in symbol value generator. There are no restrictions on symbol order: e.g. generated/computed/derived symbols can be used in any type of other symbols. The only rule is in avoiding circular dependencies such as:

"symbols": {
  "switchCheck": {
    "type": "generated",
    "generator": "switch",
    "datatype": "string",
    "parameters": {
      "evaluator": "C++",
      "cases": [
        {
          "condition": "(switchCheck2 == 'regions')",
          "value": "regions"
        }
      ]
    }
  },
  "switchCheck2": {
    "type": "generated",
    "generator": "switch",
    "datatype": "string",
    "parameters": {
      "evaluator": "C++",
      "cases": [
        {
          "condition": "(switchCheck == 'regions')",
          "value": "regions"
        }
      ]
    }
  }  

This article covers available generators for generated symbols.

To use a generated symbol inside your template.json file:

1. Add "type": "generated" to the symbol definition
2. Use the "generator": ... parameter to select the generator to use.
   This is a sample of definition of a generated symbol, the port generator, that generates a random number for an http port.

"IISExpressPortGenerated": {    
  "type": "generated",    
  "generator": "port",
  "parameters": {
    "fallback":"5000"
  }  
},   

Most of the generators need to be configured via parameters that let you select the source of the data and select among the options available. Below is a sample of a symbol that use the now generator to replace a fixed year indication present in the source files with the current year.

"copyrightYear": {
  "type": "generated",
  "generator": "now",
  "replaces": "1975",
  "parameters": {
    "format": "yyyy"
  }
},

Available built-in generators for computing generated symbols values are:

Name	Description
casing	Enables changing the casing of a string.
coalesce	Behaves like the C# ?? operator.
constant	Constant value
port	Generate a port number that can be used by web projects.
guid	Create a new guid.
now	Get the current date/time.
random	Generate random int.
regex	Process a regular expression.
regexMatch	Checks if the value matches the regex pattern.
switch	Behaves like a C# switch statement.
join	Concatenates multiple symbols or constants.

Casing

Changes the case of the text of the source value to all upper-case or all lower-case. It does not affect spaces (i.e. does not do any sort of Camel Casing).

Parameters

Name	Data Type	Description	Mandatory
source	string	The name of symbol to use as the source of data.	yes
toLower	bool	applies lower case if true, upper case otherwise	no

Samples

In this sample three symbols are defined:

• ownerName is a parameter which can be set on the command line using dotnet new It has a default value of "John Doe", that will be used if the no value is received from the host. The value will be used to replace "John Smith (a)".
• nameUpper and nameLower are the symbols that generate the upperCase and lowerCase version of ownerName that are used to replace any instance of "John Smith (U)" and "John Smith (l)".

"symbols":{
    "ownerName":{
      "type": "parameter",
      "datatype":"text",
      "replaces": "John Smith (a)",
      "defaultValue": "John Doe"
    },

    "nameUpper":{
      "type": "generated",
      "generator": "casing",
      "parameters": {
        "source":"ownerName",
        "toLower": false
      },
      "replaces":"John Smith (U)"
    },

    "nameLower":{
      "type": "generated",
      "generator": "casing",
      "parameters": {
        "source":"ownerName",
        "toLower": true
      },
      "replaces":"John Smith (l)"
    }
}

Related

Implementation class Sample

Coalesce

Behaves like the C# ?? operator. Note: the empty string value and default value of value type is treated as null. The typical use of this generator is to check if the parameter was provided by user, otherwise set fallback generated value.

Parameters

Name	Data Type	Description	Mandatory
sourceVariableName	string	the symbol name which is a primary source of data (left operand of coalesce)	yes
fallbackVariableName	string	the symbol name which is an alternate source of data(right operand of coalesce)	yes
defaultValue	string	The default value. In case it is specified, and primary source is equal to this value, the fallback value will be used.	no

Samples

In this sample three symbols are defined:

• MessageYear - is a parameter set by the user when calling dotnet new.
• ThisYear - use the now generator to calculate the current year.
• YearReplacer - ensures that any occurrence of "1234" is replaced. If MessageYear was passed in by the user that value will be used. Otherwise ThisYear will be used.

  "symbols":{
    "MessageYear":{
      "type": "parameter",
      "datatype":"int"
    },
    "ThisYear":{
      "type": "generated",
      "generator": "now",
      "parameters": {
        "format": "yyyy"
      }
    },
    "YearReplacer": {
      "type": "generated",
      "generator": "coalesce",
      "parameters": {
        "sourceVariableName": "MessageYear",
        "fallbackVariableName": "ThisYear"
      },
      "replaces": "1234"
    }
  }

Related

Implementation class

Constant

Uses constant value.

Parameters

Name	Data Type	Description	Mandatory
value	string	constant value	yes

Samples

myConstant is a symbol that replaces "1234" with "5001"

"symbols":{
  "myConstant": {
    "type": "generated",
    "generator": "constant",
    "parameters": {
      "value":"5001"
    },
    "replaces":"1234"
  }
}

Related

Implementation class Sample

Port

Gets an available port number on the machine.
During evaluation looks for a valid free port number trying to create a socket, and in case of problems, returns the value defined in the fallback parameter.

Parameters

Name	Data Type	Description	Mandatory
high	integer	defined the high bound of range to select port from. The maximum value is 65535. If greater value is specified, 65535 is used instead.	no, default: 65535
low	integer	defined the low bound of range to select port from. The minimum value is 1024. If less value is specified, 1024 is used instead.	no, default: 1024
fallback	integer	fallback value	no, default: 0

Note: if low > high, the default values for low and high are used: 1024 - 65535.

The following ports are reserved:

• 1719 - H323 (RAS)
• 1720 - H323 (Q931)
• 1723 - H323 (H245)
• 2049 - NFS
• 3659 - apple-sasl / PasswordServer [Apple addition]
• 4045 - lockd
• 4190 - ManageSieve [Apple addition]
• 5060 - SIP
• 5061 - SIPS
• 6000 - X11
• 6566 - SANE
• 6665 - Alternate IRC [Apple addition]
• 6666 - Alternate IRC [Apple addition]
• 6667 - Standard IRC [Apple addition]
• 6668 - Alternate IRC [Apple addition]
• 6669 - Alternate IRC [Apple addition]
• 6679 - Alternate IRC SSL [Apple addition]
• 6697 - IRC+SSL [Apple addition]
• 10080 - amanda

Samples

In this sample KestrelPortGenerated is a symbol that return the number of an available port or 5000.

  "KestrelPortGenerated": {
    "type": "generated",
    "generator": "port"
    "parameters": {
      "fallback":"5000"
    }
  },

Related

Implementation class

Guid

Note: Guids section in template.json can be used to achieve same goals with easier configuration

Creates a formatted guid for a replacement. To configure the output format of the macro you can use the defaultFormat parameter that 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

Parameters

Name	Data Type	Description	Mandatory
defaultFormat	string	format descriptor	no, default: D

Samples

This sample creates different symbols showing the different formatting available for the generated guid.

"symbols":{
  "id01":{
    "type": "generated",
    "generator": "guid",
    "replaces": "myid01",
    "parameters": {
      "defaultFormat":"N"
    }
  },
  "id02":{
    "type": "generated",
    "generator": "guid",
    "replaces": "myid02",
    "parameters": {
      "defaultFormat":"D"
    }
  },
  "id03":{
    "type": "generated",
    "generator": "guid",
    "replaces": "myid03",
    "parameters": {
      "defaultFormat":"B"
    }
  },
  "id04":{
    "type": "generated",
    "generator": "guid",
    "replaces": "myid04",
    "parameters": {
      "defaultFormat":"P"
    }
  },
  "id05":{
    "type": "generated",
    "generator": "guid",
    "replaces": "myid05",
    "parameters": {
      "defaultFormat":"X"
    }
  }
}

Related

Implementation class Guid Format Documentation Guids section in template.json

Now

Creates a symbol from the current date/time.

Parameters

Name	Data Type	Description	Mandatory
format	string	DateTime.ToString() format	no
utc	bool	UTC time if true, local time otherwise	no

Samples

In this sample a symbol is created showing the current data, and replacing any instance of "01/01/1999"

"symbols":{
  "createdDate": {
    "type": "generated",
    "generator": "now",
    "parameters": {
    "format": "MM/dd/yyyy"
    },
    "replaces":"01/01/1999"
  }
}

Related

Implementation class
DateTime.ToString documentation
Sample

Random

Creates a random integer value in a specified range.

Parameters

Name	Data Type	Description	Mandatory
low	integer	lower inclusive bound	yes
high	integer	upper exclusive bound	no, default:int.MaxValue

Samples

This sample shows a symbol that generates a value from 0 to 10000 excluded, and replace any instance of 4321

"symbols":{
  "myRandomNumber":{
    "type": "generated",
    "generator": "random",
    "parameters": {
    "low": 0,
    "high": 10000
    },
    "replaces": "4321"
  }
}

Related

Implementation class
Sample

Regex

Defines a list of data manipulation steps based on regex expressions.

Parameters

Name	Data Type	Description	Mandatory
source	string	the symbol to transform	yes
steps	array	replacement steps	yes

steps element definition:

Name	Data Type	Description	Mandatory
regex	string, regex pattern	selection pattern	yes
replacement	string	the replacement value for matched pattern	yes

Samples

"symbols": {
  "regexExample": {
    "type": "generated",
    "generator": "regex",
    "dataType": "string",
    "replaces": "A different message",  //The value to replace in the output
    "parameters": {
      "source": "message",              //The name of the symbol whose value should be operated on
      "steps": [
        {
          "regex": "^test",             //The regular expression whose matches will be replaced with '[Replaced]`
          "replacement": "[Replaced]"   //The value to replace matches of the expression '^test' with
        },
        {
          "regex": "test$",
          "replacement": "[/Replaced]"
        }
      ]
    }
  }
}

Related

Implementation class RegEx.Replace Documentation

RegexMatch

Tries to match regex pattern against value of source symbol and returns true if matched, otherwise false.

Parameters

Name	Data Type	Description	Mandatory
source	string	the symbol to attempt to match value	yes
pattern	string, regex pattern	the regex match pattern	yes

Samples

"symbols": {
  "isMatch": {
    "type": "generated",
    "generator": "regexMatch",
    "dataType": "bool",
    "replaces": "test.value1",
    "parameters": {
    "source": "name",
    "pattern": "^hello$"
    }
  }
}

Related

Implementation class Regex.IsMatch Documentation

Switch

Defines a set of conditions to be evaluated, and the value to return if the condition is met. The first condition to evaluate to true is used. To include a default case, add a condition that always evaluates to true as the last entry in cases.

Parameters

Name	Data Type	Description	Mandatory
cases	array	choices to evaluate	yes
evaluator	enum: C++2, C++, MSBuild, VB	expression evaluation engine	no, default: C++2

cases definition

Name	Data Type	Description	Mandatory
condition	string	the condition to evaluate, keep empty for default clause.	no
value	string	the value to return, if condition evaluates to true	yes

Samples

This sample shows how to change the replacement value based on evaluating conditions using other symbols:

"symbols": {
  "test": {
    "type": "parameter",
    "datatype": "string"
  },
  "example": {
    "type": "generated",
    "generator": "switch",
    "replaces": "abc",
    "parameters": {
      "evaluator": "C++",
      "datatype": "string",
      "cases": [
        {
          "condition": "(test == '123')",
          "value": "456"
        },
        {
          "condition": "(test == '789')",
          "value": "012"
        }
      ]
    }
  }
}

In this case, if the user enters the value 123 as the value of the parameter test, abc in the content will be replaced with 456, if the user enters 789, abc is replaced with 012 instead.

Related

Implementation class

Join

Concatenates multiple symbols or constants with the defined separator into a new symbol.

Parameters

Name	Data Type	Description	Mandatory
symbols	array	defines the values to concatenate	yes
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 \	no
removeEmptyValues	bool	indicates whether the empty values should be skipped or honored. By default this switch is off - leading to multiple consecutive separators in output string in case that same input values are null or empty	no

symbols definition

Name	Data Type	Description	Mandatory
type	enum: ref, const	ref indicates that the value is referenced from another symbol const - the value is a string constant	no, default: const
value	string	either a name of another symbol or string constant	yes, should be not empty or whitespace when type is ref

Samples

This sample shows how to change the replacement value based on evaluating conditions using other symbols:

"symbols": {
  "company": {
    "type": "parameter",
    "dataType": "string",
    "defaultValue": "Microsoft"
  },
  "product": {
    "type": "parameter",
    "dataType": "string",
    "defaultValue": "Visual Studio"
  },
  "joinedRename": {
    "type": "generated",
    "generator": "join",
    "fileRename": "Api",
    "parameters": {
      "symbols": [
        {
          "type": "const",
          "value": "Source"
        },
        {
          "type": "const",
          "value": "Api"
        },
        {
          "type": "ref",
          "value": "company"
        },
        {
          "type": "ref",
          "value": "product"
        }
      ],
      "separator": "/",
      "removeEmptyValues": true
    }
  }
}

This sample will rename folder called Api into Source/Api/Microsoft/Visual Studio. Notice that File API will automatically change / into \ on Windows.

Joining multi-choice symbol values:

template.json:

"symbols": {
  "Platform": {
    "type": "parameter",
    "description": "The target framework for the project.",
    "datatype": "choice",
    "allowMultipleValues": true,
    "choices": [
      {
        "choice": "Windows",
        "description": "Windows Desktop"
      },
      {
        "choice": "WindowsPhone",
        "description": "Windows Phone"
      },
      {
        "choice": "MacOS",
        "description": "Macintosh computers"
      },
      {
        "choice": "iOS",
        "description": "iOS mobile"
      },
      {
        "choice": "android",
        "description": "android mobile"
      },
      {
        "choice": "nix",
        "description": "Linux distributions"
      }
    ],
    "defaultValue": "MacOS|iOS"
  },
  "joinedRename": {
    "type": "generated",
    "generator": "join",
    "replaces": "SupportedPlatforms",
    "parameters": {
      "symbols": [
        {
          "type": "ref",
          "value": "Platform"
        }
      ],
      "separator": ", ",
      "removeEmptyValues": true,
    }
  }
}

Program.cs:

// This file is generated for platfrom: SupportedPlatforms

This sample will expand and join values of Platform argument and replace SupportedPlatforms string with MacOS, iOS:

Program.cs:

// This file is generated for platfrom: MacOS, iOS

Related

Implementation class