From 2e6484ed1a4d64434e9f387790dd581b29c7553a Mon Sep 17 00:00:00 2001 From: licon4812 Date: Wed, 16 Aug 2023 18:52:16 +1000 Subject: [PATCH 1/5] added sourceName info: create-item & project tuts --- docs/core/tutorials/cli-templates-create-item-template.md | 3 +++ docs/core/tutorials/cli-templates-create-project-template.md | 3 +++ 2 files changed, 6 insertions(+) diff --git a/docs/core/tutorials/cli-templates-create-item-template.md b/docs/core/tutorials/cli-templates-create-item-template.md index 7fb0884e4d0a4..40d3ccac244a5 100644 --- a/docs/core/tutorials/cli-templates-create-item-template.md +++ b/docs/core/tutorials/cli-templates-create-item-template.md @@ -110,6 +110,7 @@ Open the _template.json_ with your favorite text editor and paste in the followi "identity": "ExampleTemplate.StringExtensions", "name": "Example templates: string extensions", "shortName": "stringext", + "sourceName":"ExampleTemplate.StringExtensions", "tags": { "language": "C#", "type": "item" @@ -119,6 +120,8 @@ Open the _template.json_ with your favorite text editor and paste in the followi This config file contains all the settings for your template. You can see the basic settings, such as `name` and `shortName`, but there's also a `tags/type` value that is set to `item`. This categorizes your template as an item template. There's no restriction on the type of template you create. The `item` and `project` values are common names that .NET recommends so that users can easily filter the type of template they're searching for. +The `sourceName` item is what is replaced when the user creates a new item from the template. In this case, the user will run `dotnet new stringext -n test` and the `sourceName` will be replaced with the name the user sets on item creation. The `sourceName` must match the csproj file and the namespace. In this case test will replace `ExampleTemplate.StringExtensions` in the csproj file and the namespace. + The `classifications` item represents the **tags** column you see when you run `dotnet new` and get a list of templates. Users can also search based on classification tags. Don't confuse the `tags` property in the \*.json file with the `classifications` tags list. They're two different things unfortunately named similarly. The full schema for the *template.json* file is found at the [JSON Schema Store](http://json.schemastore.org/template). For more information about the *template.json* file, see the [dotnet templating wiki](https://github.com/dotnet/templating/wiki). Now that you have a valid _.template.config/template.json_ file, your template is ready to be installed. In your terminal, navigate to the _extensions_ folder and run the following command to install the template located at the current folder: diff --git a/docs/core/tutorials/cli-templates-create-project-template.md b/docs/core/tutorials/cli-templates-create-project-template.md index 26f9572047633..1143daf873005 100644 --- a/docs/core/tutorials/cli-templates-create-project-template.md +++ b/docs/core/tutorials/cli-templates-create-project-template.md @@ -112,6 +112,7 @@ Open the _template.json_ with your favorite text editor and paste in the followi "identity": "ExampleTemplate.AsyncProject", "name": "Example templates: async project", "shortName": "consoleasync", + "sourceName":"ExampleTemplate.AsyncProject", "tags": { "language": "C#", "type": "project" @@ -121,6 +122,8 @@ Open the _template.json_ with your favorite text editor and paste in the followi This config file contains all of the settings for your template. You can see the basic settings such as `name` and `shortName` but also there's a `tags/type` value that's set to `project`. This designates your template as a project template. There's no restriction on the type of template you create. The `item` and `project` values are common names that .NET recommends so that users can easily filter the type of template they're searching for. +The `sourceName` item is what is replaced when the user creates a new item from the template. In this case, the user will run `dotnet new stringext -n test` and the `sourceName` will be replaced with the name the user sets on item creation. The `sourceName` must match the csproj file and the namespace. In this case test will replace `ExampleTemplate.StringExtensions` in the csproj file and the namespace. + The `classifications` item represents the **tags** column you see when you run `dotnet new` and get a list of templates. Users can also search based on classification tags. Don't confuse the `tags` property in the json file with the `classifications` tags list. They're two different things unfortunately named similarly. The full schema for the *template.json* file is found at the [JSON Schema Store](http://json.schemastore.org/template). For more information about the *template.json* file, see the [dotnet templating wiki](https://github.com/dotnet/templating/wiki). Now that you have a valid _.template.config/template.json_ file, your template is ready to be installed. Before you install the template, make sure that you delete any extra folders and files you don't want included in your template, like the _bin_ or _obj_ folders. In your terminal, navigate to the _consoleasync_ folder and run `dotnet new install .\` to install the template located at the current folder. If you're using a Linux or macOS operating system, use a forward slash: `dotnet new install ./`. From 8cab006e42f792d7e02afdd1e1630ccb346705ea Mon Sep 17 00:00:00 2001 From: James Alickolli <32421608+licon4812@users.noreply.github.com> Date: Thu, 7 Sep 2023 07:10:25 +1000 Subject: [PATCH 2/5] Update docs/core/tutorials/cli-templates-create-project-template.md Co-authored-by: Andy (Steve) De George <67293991+adegeo@users.noreply.github.com> --- docs/core/tutorials/cli-templates-create-project-template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/tutorials/cli-templates-create-project-template.md b/docs/core/tutorials/cli-templates-create-project-template.md index 1143daf873005..a7c8784bbb2f6 100644 --- a/docs/core/tutorials/cli-templates-create-project-template.md +++ b/docs/core/tutorials/cli-templates-create-project-template.md @@ -122,7 +122,7 @@ Open the _template.json_ with your favorite text editor and paste in the followi This config file contains all of the settings for your template. You can see the basic settings such as `name` and `shortName` but also there's a `tags/type` value that's set to `project`. This designates your template as a project template. There's no restriction on the type of template you create. The `item` and `project` values are common names that .NET recommends so that users can easily filter the type of template they're searching for. -The `sourceName` item is what is replaced when the user creates a new item from the template. In this case, the user will run `dotnet new stringext -n test` and the `sourceName` will be replaced with the name the user sets on item creation. The `sourceName` must match the csproj file and the namespace. In this case test will replace `ExampleTemplate.StringExtensions` in the csproj file and the namespace. +The `sourceName` item is what is replaced when the user uses the template. The value of `sourceName` in the config file, is searched for in any file name and file content. In this case test will replace `consoleasync` in the name of the .csproj file. By default, this value uses the name of the current folder. When the `-n` or `--name` parameter is passed with the `dotnet new` command, the value provided is used instead of the current folder. The `classifications` item represents the **tags** column you see when you run `dotnet new` and get a list of templates. Users can also search based on classification tags. Don't confuse the `tags` property in the json file with the `classifications` tags list. They're two different things unfortunately named similarly. The full schema for the *template.json* file is found at the [JSON Schema Store](http://json.schemastore.org/template). For more information about the *template.json* file, see the [dotnet templating wiki](https://github.com/dotnet/templating/wiki). From 0e84cafd1144df8c7bed1c1f5bf184a614c5a2a0 Mon Sep 17 00:00:00 2001 From: licon4812 Date: Thu, 7 Sep 2023 07:15:41 +1000 Subject: [PATCH 3/5] Updated cli-templates-create-item-template.md --- docs/core/tutorials/cli-templates-create-item-template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/tutorials/cli-templates-create-item-template.md b/docs/core/tutorials/cli-templates-create-item-template.md index 40d3ccac244a5..e6802614173b2 100644 --- a/docs/core/tutorials/cli-templates-create-item-template.md +++ b/docs/core/tutorials/cli-templates-create-item-template.md @@ -120,7 +120,7 @@ Open the _template.json_ with your favorite text editor and paste in the followi This config file contains all the settings for your template. You can see the basic settings, such as `name` and `shortName`, but there's also a `tags/type` value that is set to `item`. This categorizes your template as an item template. There's no restriction on the type of template you create. The `item` and `project` values are common names that .NET recommends so that users can easily filter the type of template they're searching for. -The `sourceName` item is what is replaced when the user creates a new item from the template. In this case, the user will run `dotnet new stringext -n test` and the `sourceName` will be replaced with the name the user sets on item creation. The `sourceName` must match the csproj file and the namespace. In this case test will replace `ExampleTemplate.StringExtensions` in the csproj file and the namespace. +The `sourceName` item is what is replaced when the user creates a new item from the template. In this case, the user will run `dotnet new stringext -n test` and the `sourceName` will be replaced with the name the user sets on item creation. The `sourceName` must match the class file and the namespace. In this case test will replace `ExampleTemplate.StringExtensions` in the c# file and the namespace. The `classifications` item represents the **tags** column you see when you run `dotnet new` and get a list of templates. Users can also search based on classification tags. Don't confuse the `tags` property in the \*.json file with the `classifications` tags list. They're two different things unfortunately named similarly. The full schema for the *template.json* file is found at the [JSON Schema Store](http://json.schemastore.org/template). For more information about the *template.json* file, see the [dotnet templating wiki](https://github.com/dotnet/templating/wiki). From 9b30eebb2d7db1fb44dbb4d08b2ed1b83d5df6f8 Mon Sep 17 00:00:00 2001 From: licon4812 Date: Thu, 7 Sep 2023 07:20:10 +1000 Subject: [PATCH 4/5] Updated cli-temlates-create-item-template.md --- docs/core/tutorials/cli-templates-create-item-template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/tutorials/cli-templates-create-item-template.md b/docs/core/tutorials/cli-templates-create-item-template.md index e6802614173b2..10e5c611ea1d2 100644 --- a/docs/core/tutorials/cli-templates-create-item-template.md +++ b/docs/core/tutorials/cli-templates-create-item-template.md @@ -120,7 +120,7 @@ Open the _template.json_ with your favorite text editor and paste in the followi This config file contains all the settings for your template. You can see the basic settings, such as `name` and `shortName`, but there's also a `tags/type` value that is set to `item`. This categorizes your template as an item template. There's no restriction on the type of template you create. The `item` and `project` values are common names that .NET recommends so that users can easily filter the type of template they're searching for. -The `sourceName` item is what is replaced when the user creates a new item from the template. In this case, the user will run `dotnet new stringext -n test` and the `sourceName` will be replaced with the name the user sets on item creation. The `sourceName` must match the class file and the namespace. In this case test will replace `ExampleTemplate.StringExtensions` in the c# file and the namespace. +The `sourceName` item is what is replaced when the user uses the template. The value of `sourceName` in the config file, is searched for in any file name and file content. In this case test will replace `consoleasync` in the name of the class file. By default, this value uses the name of the current folder. When the `-n` or `--name` parameter is passed with the `dotnet new` command, the value provided is used instead of the current folder. The `classifications` item represents the **tags** column you see when you run `dotnet new` and get a list of templates. Users can also search based on classification tags. Don't confuse the `tags` property in the \*.json file with the `classifications` tags list. They're two different things unfortunately named similarly. The full schema for the *template.json* file is found at the [JSON Schema Store](http://json.schemastore.org/template). For more information about the *template.json* file, see the [dotnet templating wiki](https://github.com/dotnet/templating/wiki). From 83b41f369e5d8ca1d509e2aff34a7560487ead28 Mon Sep 17 00:00:00 2001 From: licon4812 Date: Fri, 8 Sep 2023 09:21:32 +1000 Subject: [PATCH 5/5] updated create-item-template to have ClassName optional --- .../cli-templates-create-item-template.md | 58 +++++++++++++++---- 1 file changed, 46 insertions(+), 12 deletions(-) diff --git a/docs/core/tutorials/cli-templates-create-item-template.md b/docs/core/tutorials/cli-templates-create-item-template.md index 10e5c611ea1d2..a022e606d7f09 100644 --- a/docs/core/tutorials/cli-templates-create-item-template.md +++ b/docs/core/tutorials/cli-templates-create-item-template.md @@ -104,23 +104,57 @@ Open the _template.json_ with your favorite text editor and paste in the followi ```json { - "$schema": "http://json.schemastore.org/template", - "author": "Me", - "classifications": [ "Common", "Code" ], - "identity": "ExampleTemplate.StringExtensions", - "name": "Example templates: string extensions", - "shortName": "stringext", - "sourceName":"ExampleTemplate.StringExtensions", - "tags": { - "language": "C#", - "type": "item" + "$schema": "http://json.schemastore.org/template", + "author": "Me", + "classifications": [ "Common", "Code" ], + "identity": "ExampleTemplate.StringExtensions", + "name": "Example templates: string extensions", + "shortName": "stringext", + "tags": { + "language": "C#", + "type": "item" + }, + "symbols": { + "ClassName":{ + "type": "parameter", + "description": "The name of the code file and class.", + "datatype": "text", + "replaces": "StringExtensions", + "fileRename": "StringExtensions", + "defaultValue": "StringExtensions" + } + } } -} ``` This config file contains all the settings for your template. You can see the basic settings, such as `name` and `shortName`, but there's also a `tags/type` value that is set to `item`. This categorizes your template as an item template. There's no restriction on the type of template you create. The `item` and `project` values are common names that .NET recommends so that users can easily filter the type of template they're searching for. -The `sourceName` item is what is replaced when the user uses the template. The value of `sourceName` in the config file, is searched for in any file name and file content. In this case test will replace `consoleasync` in the name of the class file. By default, this value uses the name of the current folder. When the `-n` or `--name` parameter is passed with the `dotnet new` command, the value provided is used instead of the current folder. +The `symbols` part of this JSON object is used to define the parameters that can be used in the template. In this case, there is one parameter defined, `ClassName`, which has several properties. The `type` property specifies that this is a parameter, the `description` property provides a description of the parameter, the `datatype` property specifies that the value of this parameter should be text, the `replaces` property specifies the text that should be replaced by the value of this parameter, the `fileRename` property specifies that the file should be renamed using the value of this parameter, and the `defaultValue` property specifies the default value for this parameter. This means that when this template is used, the user can provide a value for the `ClassName` parameter, and this value will be used to replace all occurrences of `StringExtensions` in the template and to rename the file. If no value is provided, then `StringExtensions` will be used as the default value. To see what parameters are avalible for the item template the user can run `dotnet new stringext -?` to see the avalible parameters. + +```console +dotnet new stringext -? +Example templates: string extensions (C#) +Author: Me + +Usage: + dotnet new stringext [options] [template options] + +Options: + -n, --name The name for the output being created. If no name is specified, the name of the output directory is used. + -o, --output Location to place the generated output. + --dry-run Displays a summary of what would happen if the given command line were run if it would result in a template creation. + --force Forces content to be generated even if it would change existing files. + --no-update-check Disables checking for the template package updates when instantiating a template. + --project The project that should be used for context evaluation. + -lang, --language Specifies the template language to instantiate. + --type Specifies the template type to instantiate. + +Template options: + -C, --ClassName The name of the code file and class. + Type: text + Default: StringExtensions + +``` The `classifications` item represents the **tags** column you see when you run `dotnet new` and get a list of templates. Users can also search based on classification tags. Don't confuse the `tags` property in the \*.json file with the `classifications` tags list. They're two different things unfortunately named similarly. The full schema for the *template.json* file is found at the [JSON Schema Store](http://json.schemastore.org/template). For more information about the *template.json* file, see the [dotnet templating wiki](https://github.com/dotnet/templating/wiki).