Rewrite "custom templates" to an overview article. - #55189
Open
adegeo wants to merge 11 commits into
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR replaces the older “custom templates” article with a new overview article that explains how .NET templates work and updates navigation, cross-links, and redirects so readers land on the new content.
Changes:
- Adds a new
.NET templates overviewarticle (templates.md) covering template types, structure, packages, installation, localization, and Visual Studio integration. - Updates TOC entries and “See also/Next steps” links across
dotnet newdocs and the template packaging tutorial to point to the new overview. - Deletes
custom-templates.mdand adds a redirect from/docs/core/tools/custom-templates.mdto/dotnet/core/tools/templates.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| docs/navigate/tools-diagnostics/toc.yml | Updates navigation entry to point from the removed custom-templates page to the new templates overview. |
| docs/core/tutorials/cli-templates-create-template-package.md | Repoints references to the new overview article and its “Template packages” section. |
| docs/core/tools/templates.md | Introduces the new templates overview article that replaces the removed custom-templates page. |
| docs/core/tools/dotnet-new.md | Updates related links to reference the new templates overview article. |
| docs/core/tools/dotnet-new-update.md | Updates related links to reference the new templates overview article. |
| docs/core/tools/dotnet-new-uninstall.md | Updates related links to reference the new templates overview article. |
| docs/core/tools/dotnet-new-search.md | Updates related links to reference the new templates overview article. |
| docs/core/tools/dotnet-new-sdk-templates.md | Updates related links to reference the new templates overview article. |
| docs/core/tools/dotnet-new-list.md | Updates related links to reference the new templates overview article. |
| docs/core/tools/dotnet-new-install.md | Updates related links to reference the new templates overview article. |
| docs/core/tools/dotnet-new-details.md | Updates related links to reference the new templates overview article. |
| docs/core/tools/custom-templates.md | Removes the outdated custom-templates article in favor of the new overview + redirect. |
| .openpublishing.redirection.core.json | Adds a redirect so existing links to custom-templates.md resolve to the new templates overview page. |
Comments suppressed due to low confidence (1)
docs/core/tools/templates.md:278
- The style guide requires no spaces around em dashes. Remove the spaces around the em dash in this sentence.
**Project and solution templates** appear in the **Create a new project** dialog alongside the built-in SDK templates. Users can find your template by name, language, or by the tags from the `classifications` field in `template.json`. Accurate classifications help your template surface in the right filter categories, so choose them carefully. To give your template a polished appearance in the dialog, add an `icon.png` to the `.template.config` folder — Visual Studio displays it next to your template's name.
gewarren
approved these changes
Jul 30, 2026
gewarren
left a comment
gewarren
left a comment
Collaborator
There was a problem hiding this comment.
To me the new templates article is a bit confused about its audience - a lot of it seems written to template creators, which is probably just a small percentage of readers, so I think "Template overview" is not the best title.
| href: ../../core/tools/dotnet-new-sdk-templates.md | ||
| - name: Custom templates | ||
| href: ../../core/tools/custom-templates.md | ||
| - name: .NET templates overview |
Collaborator
There was a problem hiding this comment.
Seems like the overview should come before the default templates article.
Contributor
Author
There was a problem hiding this comment.
I'm indifferent, it's reference material, as is the CLI help above it. Personally I don't much like any of these articles placed here, but I don't own the area.
Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Co-authored-by: Andy (Steve) De George <67293991+adegeo@users.noreply.github.com>
adegeo
enabled auto-merge (squash)
July 30, 2026 21:57
gewarren
approved these changes
Jul 31, 2026
| └── icon.png | ||
| ``` | ||
|
|
||
| The source files can be any type of file. The template engine doesn't require you to inject special tokens or markers into the source code. It uses the files as-is, which means you can build, run, and debug a template's source project exactly like a normal .NET project. To turn an existing project into a template, add a `.template.config/template.json` file to the project root. |
Collaborator
There was a problem hiding this comment.
I still think the audience isn't quite clear, for example in this paragraph. The article purports to help .NET developers understand templates. The paragraph on line 39 aligns with that. Then on this line, it suddenly assumes the reader is the one creating the template.
Suggested change
| The source files can be any type of file. The template engine doesn't require you to inject special tokens or markers into the source code. It uses the files as-is, which means you can build, run, and debug a template's source project exactly like a normal .NET project. To turn an existing project into a template, add a `.template.config/template.json` file to the project root. | |
| Template source files can be any type of file. If you're creating a template, the template engine doesn't require you to inject special tokens or markers into the source code. It uses the files as-is, which means you can build, run, and debug a template's source project exactly like a normal .NET project. To turn an existing project into a template, add a `.template.config/template.json` file to the project root. |
|
|
||
| The source files can be any type of file. The template engine doesn't require you to inject special tokens or markers into the source code. It uses the files as-is, which means you can build, run, and debug a template's source project exactly like a normal .NET project. To turn an existing project into a template, add a `.template.config/template.json` file to the project root. | ||
|
|
||
| You can optionally inject substitution tokens tied to template parameters (symbols) directly into template source files and file names. If the tokens aren't valid source code, you can't build, run, or debug the source project before you deploy it as a template. The tokens don't affect projects that users create from the deployed template because the template engine replaces them during project creation. |
Collaborator
There was a problem hiding this comment.
Suggested change
| You can optionally inject substitution tokens tied to template parameters (symbols) directly into template source files and file names. If the tokens aren't valid source code, you can't build, run, or debug the source project before you deploy it as a template. The tokens don't affect projects that users create from the deployed template because the template engine replaces them during project creation. | |
| If you're authoring a template, you can optionally inject substitution tokens tied to template parameters (symbols) directly into template source files and file names. If the tokens aren't valid source code, you can't build, run, or debug the source project before you deploy it as a template. The tokens don't affect projects that users create from the deployed template because the template engine replaces them during project creation. |
|
|
||
| You can optionally inject substitution tokens tied to template parameters (symbols) directly into template source files and file names. If the tokens aren't valid source code, you can't build, run, or debug the source project before you deploy it as a template. The tokens don't affect projects that users create from the deployed template because the template engine replaces them during project creation. | ||
|
|
||
| The only required file inside `.template.config` is `template.json`. That file tells the template engine everything it needs: the template's name, short name, author, classifications, and any parameters users can pass when they create from the template. You can also place an `icon.png` file in the `.template.config` folder. The terminal doesn't display icons, but Visual Studio shows the icon next to the template in the **Create a new project** dialog. A 128×128 PNG works well. |
Collaborator
There was a problem hiding this comment.
Suggested change
| The only required file inside `.template.config` is `template.json`. That file tells the template engine everything it needs: the template's name, short name, author, classifications, and any parameters users can pass when they create from the template. You can also place an `icon.png` file in the `.template.config` folder. The terminal doesn't display icons, but Visual Studio shows the icon next to the template in the **Create a new project** dialog. A 128×128 PNG works well. | |
| The only required file inside `.template.config` is `template.json`. That file tells the template engine everything it needs: the template's name, short name, author, classifications, and any parameters users can pass when they create from the template. If there's an `icon.png` file in the `.template.config` folder, Visual Studio shows the icon next to the template in the **Create a new project** dialog. (If you're creating a template, a 128×128 PNG works well.) |
|
|
||
| ### The template.json file | ||
|
|
||
| The `template.json` file is the only required piece of configuration in a template. It lives inside the `.template.config` folder and tells the template engine how to present and process your template. The following table describes common required and optional fields: |
Collaborator
There was a problem hiding this comment.
Suggested change
| The `template.json` file is the only required piece of configuration in a template. It lives inside the `.template.config` folder and tells the template engine how to present and process your template. The following table describes common required and optional fields: | |
| The `template.json` file is the only required piece of configuration in a template. It lives inside the `.template.config` folder and tells the template engine how to present and process a given template. The following table describes common required and optional fields: |
| | `identity` | string | Yes | A unique identifier for the template. | | ||
| | `name` | string | Yes | The display name of the template shown to users. | | ||
| | `shortName` | string | Yes | The short name users pass to `dotnet new` to create from the template, such as `console` or `classlib`. | | ||
| | `sourceName` | string | No | A string in your source files and file names that the template engine replaces with the name the user provides via `-n` or `--name`. If the user doesn't provide a name, the engine uses the current directory name. | |
Collaborator
There was a problem hiding this comment.
Suggested change
| | `sourceName` | string | No | A string in your source files and file names that the template engine replaces with the name the user provides via `-n` or `--name`. If the user doesn't provide a name, the engine uses the current directory name. | | |
| | `sourceName` | string | No | A string in the template source files and file names that the template engine replaces with the name the user provides via `-n` or `--name`. If the user doesn't provide a name, the engine uses the current directory name. | |
|
|
||
| ## Template localization | ||
|
|
||
| The .NET template engine supports optional localization of template metadata. When you provide localization files, hosts such as `dotnet new` and the Visual Studio **New Project** dialog display the template's name, description, and symbol information in the user's language instead of the original authored language. |
Collaborator
There was a problem hiding this comment.
Suggested change
| The .NET template engine supports optional localization of template metadata. When you provide localization files, hosts such as `dotnet new` and the Visual Studio **New Project** dialog display the template's name, description, and symbol information in the user's language instead of the original authored language. | |
| The .NET template engine supports optional localization of template metadata. When a template provides localization files, hosts such as `dotnet new` and the Visual Studio **New Project** dialog display the template's name, description, and symbol information in the user's language instead of the original authored language. |
| - Description and display name for each choice in a choice parameter | ||
| - Post action `description` and `manualInstructions` | ||
|
|
||
| To add localization, create a `localize` subfolder inside `.template.config` and add one JSON file per language. Name each file `templatestrings.<lang-code>.json`, where `<lang-code>` matches a valid <xref:System.Globalization.CultureInfo> name, such as `pt-BR`, `zh-Hans`, or `de`. Each file contains key-value pairs where the key is a path to the element in `template.json`, using `/` as a delimiter for nested fields. |
Collaborator
There was a problem hiding this comment.
Suggested change
| To add localization, create a `localize` subfolder inside `.template.config` and add one JSON file per language. Name each file `templatestrings.<lang-code>.json`, where `<lang-code>` matches a valid <xref:System.Globalization.CultureInfo> name, such as `pt-BR`, `zh-Hans`, or `de`. Each file contains key-value pairs where the key is a path to the element in `template.json`, using `/` as a delimiter for nested fields. | |
| To add localization to a template you're creating, create a `localize` subfolder inside `.template.config` and add one JSON file per language. Name each file `templatestrings.<lang-code>.json`, where `<lang-code>` matches a valid <xref:System.Globalization.CultureInfo> name, such as `pt-BR`, `zh-Hans`, or `de`. Each file contains key-value pairs where the key is a path to the element in `template.json`, using `/` as a delimiter for nested fields. |
|
|
||
| The template engine parses these files when it loads template information, and it returns localized values automatically based on the current UI culture—no extra steps are required from the user. | ||
|
|
||
| Localization is optional. If you don't include localization files, the template works normally and always displays the values from `template.json`. For more information, see the [dotnet/templating wiki localization page](https://github.com/dotnet/templating/wiki/Localization). |
Collaborator
There was a problem hiding this comment.
Suggested change
| Localization is optional. If you don't include localization files, the template works normally and always displays the values from `template.json`. For more information, see the [dotnet/templating wiki localization page](https://github.com/dotnet/templating/wiki/Localization). | |
| Localization is optional. If localization files aren't included with a template, the template works normally and always displays the values from `template.json`. For more information, see the [dotnet/templating wiki localization page](https://github.com/dotnet/templating/wiki/Localization). |
|
|
||
| Visual Studio's **Create a new project** dialog uses the .NET template engine for .NET project templates. Templates you create for `dotnet new` work in Visual Studio too, without any extra configuration. When you install a template package with `dotnet new install`, Visual Studio automatically detects and surfaces those templates in the dialog. | ||
|
|
||
| **Project and solution templates** appear in the **Create a new project** dialog alongside the built-in SDK templates. Other users can find your template by name, language, or the tags from the `classifications` field in `template.json`. Accurate classifications help your template surface in the right filter categories, so choose them carefully. To give your template a polished appearance in the dialog, add an `icon.png` to the `.template.config` folder — Visual Studio displays it next to your template's name. |
Collaborator
There was a problem hiding this comment.
Suggested change
| **Project and solution templates** appear in the **Create a new project** dialog alongside the built-in SDK templates. Other users can find your template by name, language, or the tags from the `classifications` field in `template.json`. Accurate classifications help your template surface in the right filter categories, so choose them carefully. To give your template a polished appearance in the dialog, add an `icon.png` to the `.template.config` folder — Visual Studio displays it next to your template's name. | |
| **Project and solution templates** appear in the **Create a new project** dialog alongside the built-in SDK templates. Users can find templates by name, language, or the tags from the `classifications` field in the template's `template.json` file. If you're creating a template, accurate classifications help your template surface in the right filter categories, so choose them carefully. To give your template a polished appearance in the dialog, add an `icon.png` to the `.template.config` folder — Visual Studio displays it next to your template's name. |
|
|
||
| **Item templates** don't currently appear in the **Add** > **New Item** dialog. Users can still use item templates with the `dotnet new` command in the terminal. | ||
|
|
||
| To make your template discoverable to Visual Studio users who haven't installed it yet, publish your template package to nuget.org. The **Create a new project** dialog includes an **Install more templates from the online search** option that searches nuget.org for template packages. When a user installs your package through that option, Visual Studio uses the same install mechanism as `dotnet new install`. |
Collaborator
There was a problem hiding this comment.
Suggested change
| To make your template discoverable to Visual Studio users who haven't installed it yet, publish your template package to nuget.org. The **Create a new project** dialog includes an **Install more templates from the online search** option that searches nuget.org for template packages. When a user installs your package through that option, Visual Studio uses the same install mechanism as `dotnet new install`. | |
| If you're creating a template, to make your template discoverable to Visual Studio users who haven't installed it yet, publish your template package to nuget.org. The **Create a new project** dialog includes an **Install more templates from the online search** option that searches nuget.org for template packages. When a user installs your package through that option, Visual Studio uses the same install mechanism as `dotnet new install`. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rewrote the custom templates article to be an overview about templates and about how they're structured.
Fixes #51380
Internal previews
Toggle expand/collapse