Skip to content

Commit

Permalink
fixes dotnet#2126 fixes dotnet#2513
Browse files Browse the repository at this point in the history 
Reference for template.json - updates the symbols description
Runnable Project Templates: replaces duplicated symbols description with link to 'Reference for template.json'
  • Loading branch information
@vlada-shubina
vlada-shubina committed Oct 19, 2020
1 parent 8786ab3 commit cfca986
Show file tree
Hide file tree
Showing 2 changed files with 265 additions and 98 deletions.
284 changes: 264 additions & 20 deletions docs/Reference-for-template.json.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,31 +51,275 @@ the `template.json` file. This requires that a few changes have to be done on th
|exclude|Exclude configuration specific to this sources.modifiers instance, contingent on the corresponding sources.modifiers.condition. See sources.exclude for more info|
|copyOnly|CopyOnly configuration specific to this sources.modifiers instance, contingent on the corresponding sources.modifiers.condition. See sources.copyonly for more info|

#### Symbols Introduction
### Symbols
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.

|Name|Description|Applies to|
|--|--|--|
|type|Defines the high level configuration of symbol. The valid types are: `parameter`, `computed`, and `generated`. The type indicates how the configuration is processed to generate the symbol value:||
||`Parameter`: A symbol for which the config provides literal and/or default values||
||`Computed`: A symbol for which the config provides a Boolean predicate whose evaluation result is the computed symbol result||
||`Generated`: A symbol whose value gets computed by a built-in symbol value generator. See [Details](https://github.com/dotnet/templating/wiki/Reference-for-available-macros)||
|dataType |Indicates limitations on the valid values a symbol may be assigned. At this point, the only valid datatype is "choice", which also requires providing symbols.choices configuration for the symbol|`type=parameter`|
|defaultValue|The value assigned to the symbol if no value for it is provided by the user or host|`type=parameter`|
|binding|||
|replaces|Text value that will be replaced||
|fileRename|The fileRename element defines the filenames which will be replaced|`type=parameter`|
|description|Human readable text describing the meaning of the symbol. This has no effect on template generation||
|isRequired|Indicates if the parameter is required or not.|Only used when `type` is set to `parameter`|
|choices|List of available choices.|Only used when `type` is `choice`|
|value |Value for replacement|`type=computed`|
There are the following symbol types:
- Parameter
- Derived
- Computed
- Generated
- Bind

There are 3 places from which a symbol can acquire its value:
- Template configuration (this).
- Host provided values, which override template configuration values. For example, the host may provide the operating system kind as "Linux", overriding a template default value of "Windows".
- User provided values, which override host & template values. The way these are provided to the template generation broker is specific to the broker. This may be via additional configuration files, command line parameters, inputs to a UI, etc.

#### Parameter symbol

A symbol for which the config provides literal and/or default values.

|Name|Description|
|---|---|
|`type`|`parameter`|
|`dataType`| Supported values: <br />- `bool`: boolean type, possible values: `true`/`false`. <br />- `choice`: enumeration, possible values are defined in `choices` property.<br />- `float`: double-precision floating format number. Accepts any value that can be parsed by `double.TryParse()`.<br />- `int`/`integer`: 64-bit signed integer. Accepts any value that can be parsed by `long.TryParse()`.<br />- `hex`: hex number. Accepts any value that can be parsed by `long.TryParse(value.Substring(2), NumberStyles.HexNumber, CultureInfo.InvariantCulture, out long convertedHex)`.<br />- `text`/`string`: string type.<br />- `<any other>`: treated as string.
|`defaultValue`|The value assigned to the symbol if no value for it is provided by the user or host.|
|`binding`|The name of the host property to take the value from.|
|`replaces`|The text to replace with the value of this symbol.|
|`fileRename`|The fileRename element defines the filenames which will be replaced by symbol value.|
|`description`|Human readable text describing the meaning of the symbol. This has no effect on template generation.|
|`isRequired`|Indicates if the parameter is required or not.|
|`choices`|List of available choices. Applicable only when `datatype=choice.` Contains array of the elements: <br />- `choice`: possible value of the symbol.<br />- `description`: human readable text describing the meaning of the choice. This has no effect on template generation. <br /> If not provided, there are no valid choices for the symbol, so it can never be assigned a value.|
|`onlyIf`| |
|`forms`|Defines the set of transforms that can be referenced by symbol definitions. Forms allow the specification of a "replaces"/"replacement" pair to also apply to other ways the "replaces" value may have been specified in the source by specifying a transform from the original value of "replaces" in configuration to the one that may be found in the source. [Details](https://github.com/dotnet/templating/wiki/Runnable-Project-Templates---Value-Forms)|

##### Examples
Boolean optional parameter with default value `false`:
```json
"symbols": {
"TestProject": {
"type": "parameter",
"dataType": "bool",
"defaultValue": "false"
}
},
```

Choice optional parameter with 3 possible values:
```json
"symbols": {
"Framework": {
"type": "parameter",
"description": "The target framework for the project.",
"datatype": "choice",
"choices": [
{
"choice": "netcoreapp3.1",
"description": "Target netcoreapp3.1"
},
{
"choice": "netstandard2.1",
"description": "Target netstandard2.1"
},
{
"choice": "netstandard2.0",
"description": "Target netstandard2.0"
}
],
"replaces": "netstandard2.0",
"defaultValue": "netstandard2.0"
}
}
```

String optional parameter, replaces TargetFrameworkOverride:
```json
"symbols": {
"TargetFrameworkOverride": {
"type": "parameter",
"description": "Overrides the target framework",
"replaces": "TargetFrameworkOverride",
"datatype": "string",
"defaultValue": ""
}
}
```

#### Derived symbol

A symbol that defines transformation of another symbol. The value of this symbol is derived from the value of another symbol by the application of form defined in `valueTransform`.

|Name|Description|
|---|---|
|`type`|`derived`|
|`valueSource`|The name of the other symbol whose value will be used to derive this value.|
|`valueTransform`|The name of the value form to apply to the source value.|
|`replaces`|The text to replace with the value of this symbol.|
|`fileRename`|The fileRename element defines the filenames which will be replaced by symbol value.|
|`description`|Human readable text describing the meaning of the symbol. This has no effect on template generation.|

##### Examples
Renames `Application1` file to value of `name` symbol after last dot
```json
{
...
"symbols": {
"app1Rename": {
"type": "derived",
"valueSource": "name",
"valueTransform": "ValueAfterLastDot",
"fileRename": "Application1",
"description": "A value derived from the 'name' param, used to rename Application1.cs"
}
}
...
"forms": {
"ValueAfterLastDot": {
"identifier": "replace",
"pattern": "^.*\\.(?=[^\\.]+$)", // regex to match everything up to and including the final "."
"replacement": "" // replace it with empty string
}
}
...
}
```

#### Generated symbol

A symbol whose value gets computed by a built-in symbol value generator. [Details](https://github.com/dotnet/templating/wiki/Reference-for-available-macros)

|Name|Description|
|---|---|
|`type`|`generated`|
|`generator`|Generator to use:<br />- [casing](https://github.com/dotnet/templating/wiki/Reference-for-available-macros#casing) - enables changing the casing of a string.<br />- [coalesce](https://github.com/dotnet/templating/wiki/Reference-for-available-macros#coalesce) - behaves like the C# ?? operator.<br />- [constant](https://github.com/dotnet/templating/wiki/Reference-for-available-macros#constant) - constant value.<br />- [evaluate](https://github.com/dotnet/templating/wiki/Reference-for-available-macros#evaluate) - evaluates a code expression (using C style syntax).<br />- [port](https://github.com/dotnet/templating/wiki/Reference-for-available-macros#port) - generates a port number that can be used by web projects.<br />- [guid](https://github.com/dotnet/templating/wiki/Reference-for-available-macros#guid) creates a new guid.<br />- [now](https://github.com/dotnet/templating/wiki/Reference-for-available-macros#now) - get the current date/time.<br />- [random](https://github.com/dotnet/templating/wiki/Reference-for-available-macros#random) - generate random integer value.<br />- [regex](https://github.com/dotnet/templating/wiki/Reference-for-available-macros#regex) - processes a regular expression.<br />- [switch](https://github.com/dotnet/templating/wiki/Reference-for-available-macros#switch) - behaves like a C# switch statement.|
|`parameters`|The parameters for generator. See [description](https://github.com/dotnet/templating/wiki/Reference-for-available-macros) for each generator for details.|
|`description`|Human readable text describing the meaning of the symbol. This has no effect on template generation.|

##### Example

- `myconstant`: replaces `1234` with `5001`
- `ownername`: replaces `John Smith (a)` with value of `ownername` parameter
- `nameUpper`: replaces `John Smith (U)` with value of `ownername` parameter in upper case
- `nameLower`: replaces `John Smith (l)` with value of `ownername` parameter in lower case

```json
"symbols":{
"myconstant": {
"type": "generated",
"generator": "constant",
"parameters": {
"value":"5001"
},
"replaces":"1234"
},
"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)"
}
}
```

#### Computed symbol

A symbol for which the config provides a Boolean predicate whose evaluation result is the computed symbol result.

|Name|Description|
|---|---|
|`type`|`computed`|
|`value`| Boolean expresion to be computed.|
|`evaluator`|Language to be used for evaluation of expression: <br />- `C++2` - default<br />- `C++`<br />- `MSBUILD`<br />- `VB`|

##### Example

Values of `OrganizationalAuth`, `WindowsAuth`, `MultiOrgAuth`, `SingleOrgAuth`, `IndividualAuth`, `NoAuth`, `RequiresHttps` symbols are computed based on `auth` symbol.

```json
"symbols": {
"auth": {
"type": "parameter",
"datatype": "choice",
"choices": [
{
"choice": "None",
"description": "No authentication"
},
{
"choice": "Individual",
"description": "Individual authentication"
},
{
"choice": "SingleOrg",
"description": "Organizational authentication for a single tenant"
},
{
"choice": "MultiOrg",
"description": "Organizational authentication for multiple tenants"
},
{
"choice": "Windows",
"description": "Windows authentication"
}
],
"defaultValue": "Individual",
"description": "The type of authentication to use"
},
"OrganizationalAuth": {
"type": "computed",
"value": "(auth == \"SingleOrg\" || auth == \"MultiOrg\")"
},
"WindowsAuth": {
"type": "computed",
"value": "(auth == \"Windows\")"
},
"MultiOrgAuth": {
"type": "computed",
"value": "(auth == \"MultiOrg\")"
},
"SingleOrgAuth": {
"type": "computed",
"value": "(auth == \"SingleOrg\")"
},
"IndividualAuth": {
"type": "computed",
"value": "(auth == \"Individual\")"
},
"NoAuth": {
"type": "computed",
"value": "(!(IndividualAuth || MultiOrgAuth || SingleOrgAuth || WindowsAuth))"
},
"RequiresHttps": {
"type": "computed",
"value": "(OrganizationalAuth)"
},
```

#### Bind symbol

|Name|Description|
|---|---|
|`type`|`bind`|
|`binding`|The name of the host property to take the value from.|
|`replaces`|The text to replace with the value of this symbol.|

* Template configuration (this).
* Host provided values, which override template configuration values. For example, the host may provide the operating system kind as "Linux", overriding a template default value of "Windows".
* User provided values, which override host & template values. The manner in which these are provided to the template generation broker is specific to the broker. This may be via additional configuration files, command line parameters, inputs to a UI, etc.

##### Example

```json
"HostIdentifier": {
"type": "bind",
"binding": "HostIdentifier"
},
```

### Output Management
|Name|Description|Default|
Expand Down
79 changes: 1 addition & 78 deletions docs/Runnable-Project-Templates.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -356,84 +356,7 @@ CopyOnly configuration specific to this sources.modifiers instance, contingent o
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.

### symbols (optional)
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.

There are 3 places from which a symbol can acquire its value:
* Template configuration (this).
* Host provided values, which override template configuration values. For example, the host may provide the operating system kind as "Linux", overriding a template default value of "Windows".
* User provided values, which override host & template values. The manner in which these are provided to the template generation broker is specific to the broker. This may be via additional configuration files, command line parameters, inputs to a UI, etc.

See the symbols.X subsections for details on defining symbol values in template configuration.

### symbols.type (required)
Defines the high level configuration of symbol. The valid types are: parameter, computed, and generated. The type indicates how the configuration is processed to generate the symbol value:
- Parameter: A symbol for which the config provides literal and/or default values.
- Computed: A symbol for which the config provides a Boolean predicate whose evaluation result is the computed symbol result.
- Generated: A symbol whose value gets computed by a built-in symbol value generator. See symbols.parameters for details.

### symbols.dataType (optional) (applies to `type=parameter`)
Indicates limitations on the valid values a symbol may be assigned.
At this point, the only valid datatype is "choice", which also requires providing symbols.choices configuration for the symbol.

### symbols.defaultValue (optional) (applies to `type=parameter`)
The value assigned to the symbol if no value for it is provided by the user or host.

### symbols.binding (optional)

### symbols.replaces (optional)
The replaces element defines the text which will be replaced.

### symbols.fileRename (optional)
The fileRename element defines the filenames which will be replaced

### symbols.description (optional)
Human readable text describing the meaning of the symbol. This has no effect on template generation.

### symbols.isRequired (optional) (applies to `type=parameter`)

### symbols.choices (optional) (applies to `type=choice`)
An array listing the valid choices for a symbol whose datatype = choice. If not provided, there are no valid choices for the symbol, so it can never be assigned a value.

### symbols.value (optional) (applies to `type=computed`)
An evaluate-able condition whose result defines the value of the symbol.

### symbols.generator (optional) (applies to `type=generated`)
A string indicating the built-in generator for determining the symbol value. The valid generator values are:
* constant: An explicit value is provided for the symbol.
* evaluate: The evaluation result of a Boolean predicate becomes the symbol value.
* guid
* now
* random
* regex

### symbols.parameters (optional) (applies to `type=generated`)
Each generator requires its own specific set of parameters to correctly configure itself, as follows:

#### generator = constant - parameters:
- action: The value to be assigned to the symbol

#### generator = evaluate - parameters:
- action: The Boolean predicate whose evaluation result becomes the symbol value.
- evaluator: A string indicating the predicate evaluator to evaluate the action against.

#### generator = guid - parameters:
- action: Must be the string literal "new".
- format: When a string representation of the guid is needed, this is used as the format string in Guid.ToString()

#### generator = now - parameters:
- action: The format string to use when converting the date-time to a string representation.
- Utc: A Boolean. If true, use UTC time. If false, use local time.

#### generator = random - parameters:
- action: Must be the string literal "new".
- low: Required. An integer value indicating the low-end of the range to generate the random number in.
- high: Optional: An integer value indicating the high-end of the range to generate the random number in. If not explicitly provided, defaults to int.MaxValue.

#### generator = regex - parameters:
- action: Must be the string literal "replace"
- source: 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: 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).

The `symbols` section defines variables and their values, the values may be the defined in terms of other symbols. See more information on symbols in [this](https://github.com/dotnet/templating/wiki/Reference-for-template.json#symbols) article.

### CustomOperations (optional) and SpecialCustomOperations (optional)
This configuration allows the template author to define custom actions for the template creation process. CustomOperations are scoped globally unless overridden by a more restrictive custom configuration.
Expand Down

0 comments on commit cfca986

Please sign in to comment.