Reserved Aliases

Reference for dotnetcli.host.json

In dotnet new the parameter symbols are exposed as additional template options that can be passed to the command. Generally, dotnet new uses the name of parameter symbol to generate the long and the short alias for the option:

The long alias is a parameter symbol name with -- prefix.
The short alias is a parameter symbol name first character with - prefix.

Note that the aliases are case sensitive.

With dotnetcli.host.json file we can change long alias and short alias of the template option and its visibility. dotnetcli.host.json is located at the same directory as template.json file. It has the following configuration:

symbolsInfo
It has a collection of the name of specified parameter symbol in template.json with corresponding long or short aliases to override original ones and the visibility of the template option.
- longName - overrides the long alias for the parameter symbol.
- shortName - overrides the short alias for the parameter symbol. Empty means short alias should not be used.
- isHidden - true if the parameter should be hidden in dotnet new.
usageExamples - not used; see #3262 for more details.

In case when option assignment results in duplicate options, --param: prefix is used for the long alias and short alias is generated from the beginning of the symbol's name till the one which can form a unique short name with - prefix or -p: prefix is used.

Examples

Example 1

Overrides original long alias --TargetFrameworkOverride with --targetframework and overrides short alias -T with -tf.

{
  "$schema": "http://json.schemastore.org/dotnetcli.host",
  "symbolInfo": {
    "TargetFrameworkOverride": {
      "longName": "targetframework",
      "shortName": "tf"
    }
  }
}

Part of the output of dotnet new <template shortName> --help looks like:

Template options:
  -tf, --targetframework <net7.0|net6.0|...>  Overrides the target framework.

Example 2

Parameter TargetFrameworkOverride is hidden from dotnet new help information.

{
  "$schema": "http://json.schemastore.org/dotnetcli.host",
  "symbolInfo": {
    "TargetFrameworkOverride": {
      "isHidden": "true"
    }
  }
}

Example 3

If short name is not specified, short name is the first character of overridden long name. Long alias is --targetframework and short alias is -t.

{
  "$schema": "http://json.schemastore.org/dotnetcli.host",
  "symbolInfo": {
    "TargetFrameworkOverride": {
      "longName": "targetframework"
    }
  }
}

Example 4

If short name is empty, there is no short alias for the template option. Long alias is --targetframework.

{
  "$schema": "http://json.schemastore.org/dotnetcli.host",
  "symbolInfo": {
    "TargetFrameworkOverride": {
      "longName": "targetframework",
      "shortName": ""
    }
  }
}

Part of the output of dotnet new <template shortName> --help looks like:

Template options:
  --targetframework <net7.0|net6.0|...>  Overrides the target framework.

Example 5

If long/short alias from overridden long/short name is reserved alias, long name will be prefixed with --param: and short name will be prefixed with -p: instead. Here long alias is --param:package and short alias is -p:i. See Reserved Aliases.

{
  "$schema": "http://json.schemastore.org/dotnetcli.host",
  "symbolInfo": {
    "pack": {
      "longName": "package",
      "shortName": "i"
    }
  }
}

Example 6

Assuming template.json has the symbols below.

  "symbols": {
    "TargetFrameworkOverride": {
      "type": "parameter",
      "description": "Overrides the target framework.",
      "dataType": "string",
      "defaultValue": "net7.0"
    },
    "targetframework": {
      "type": "parameter",
      "description": "The target framework for the project.",
      "dataType": "string",
      "defaultValue": "net6.0"
    }
  }

With the following dotnetcli.host.json, long alias and short alias of symbol TargetFrameworkOverride is --targetframework and -t. For symbol targetframework, since aliases --targetframework -t are already taken its long alias is prefixed with --param: to be --param:targetframework and short alias is -ta.

{
  "$schema": "http://json.schemastore.org/dotnetcli.host",
  "symbolInfo": {
    "TargetFrameworkOverride": {
      "longName": "targetframework"
    }
  }
}

Part of the output of dotnet new <template shortName> --help looks like:

Template options:
  -t, --targetframework <net7.0>  Overrides the target framework.
  -ta, --param:targetframework <net6.0>  The target framework for the project.