Rewrite "custom templates" to an overview article. - #55189
Open
adegeo wants to merge 10 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.
|
|
||
| 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. 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. |
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. 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. | |
| **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 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. | ||
|
|
||
| **Item templates** don't currently appear in the **Add** > **New Item** dialog. Users can still create from item templates using `dotnet new <shortName>` in the terminal, but Visual Studio doesn't surface them in its item-creation UI. |
Collaborator
There was a problem hiding this comment.
Create what from item templates? That sentence doesn't read well.
| - [Tutorial: Create a template package](../tutorials/cli-templates-create-template-package.md) | ||
| - [dotnet new command](dotnet-new.md) | ||
| - [dotnet/templating GitHub repo wiki](https://github.com/dotnet/templating/wiki) | ||
| - [Template samples](https://aka.ms/template-samples) |
Collaborator
There was a problem hiding this comment.
Why not just use https://github.com/dotnet/templating/tree/main/dotnet-template-samples? See https://learn.microsoft.com/en-us/help/platform/links-how-to?toc=%2Fhelp%2Fplatform%2Ftoc.json&bc=%2Fhelp%2Fplatform%2Fbreadcrumb%2Ftoc.json#fwlinks-and-akams-links which discourages use of AKA links.
|
|
||
| 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://aka.ms/templating-localization). |
Collaborator
There was a problem hiding this comment.
Don't use AKA link - see other comment.
|
|
||
| ## Template structure | ||
|
|
||
| A template is a folder on disk that contains two things: your source files and a special `.template.config` subfolder. When you run `dotnet new <shortName>`, the template engine copies your source files to the output location and applies any configuration you've defined. |
Collaborator
There was a problem hiding this comment.
Suggested change
| A template is a folder on disk that contains two things: your source files and a special `.template.config` subfolder. When you run `dotnet new <shortName>`, the template engine copies your source files to the output location and applies any configuration you've defined. | |
| A template is a folder on disk that contains two things: the template source files and a special `.template.config` subfolder. When you run `dotnet new <shortName>`, the template engine copies the source files to the output location and applies any configuration that's defined for the template. |
| └── 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 your source code. It uses your 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.
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 your source code. It uses your 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. |
|
|
||
| The source files can be any type of file. The template engine doesn't require you to inject special tokens or markers into your source code. It uses your 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 your 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 your 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. |
|
|
||
| You can optionally inject substitution tokens tied to template parameters (symbols) directly into your 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 your 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 your 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. 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. |
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