[2.0] New content for templating: Create custom templates for dotnet new #2495
Conversation
guardrex
changed the title
guardrex
changed the title
|
One more thing I noticed: The metadata title has the preview warning, and the WARNING note is at the top of the content. However, the H1 doesn't have it. I'll fix that on review when I'm working on feedback. |
docs/core/tools/custom-templates.md
Outdated
| @@ -0,0 +1,232 @@ | |||
| --- | |||
| title: Create custom templates for dotnet new (.NET Core SDK 2.0 Preview 2) | Microsoft Docs | |||
| description: | |||
docs/core/tools/custom-templates.md
Outdated
|
|
||
| [!INCLUDE [core-preview-warning](~/includes/core-preview-warning.md)] | ||
|
|
||
| The [.NET Core SDK](https://www.microsoft.com/net/download/core) provides many useful templates, but you can create your own custom templates for any type of .NET project, such as an app, service, tool, or class library. You can even create a template that outputs one or more independent files, such as a configuration file. |
There was a problem hiding this comment.
wouldn't be better to say that The .NET Core SDK comes with many templates pre-installed for you to use with dotnet new?
docs/core/tools/custom-templates.md
Outdated
|
|
||
| The [.NET Core SDK](https://www.microsoft.com/net/download/core) provides many useful templates, but you can create your own custom templates for any type of .NET project, such as an app, service, tool, or class library. You can even create a template that outputs one or more independent files, such as a configuration file. | ||
|
|
||
| Templates work with any Microsoft framework, including .NET Core, .NET Framework, and Xamarin. Users install your custom template from a NuGet package on any NuGet feed, by referencing a NuGet *nupkg* file directly, or by specifying a file system directory that contains the template. The template engine offers features that allow you to replace values, include and exclude files and regions of files, and execute custom processing operations when your template is used. |
There was a problem hiding this comment.
Microsoft framework is throwing me off a bit here. Maybe we say .NET platform?
There was a problem hiding this comment.
I'm not 100% feel'in this one because I really did mean to say that the template engine (as a tool) works with any "Microsoft framework" (as opposed to any other non-MS frameworks) and list (at least some of) them. However, I don't think this sentence helps much here. The main thrust of this paragraph has more to do with using them, and I think we can assume that everyone knows this is a MS technology. Let's try killing this sentence and see if that works better.
docs/core/tools/custom-templates.md
Outdated
|
|
||
| Templates work with any Microsoft framework, including .NET Core, .NET Framework, and Xamarin. Users install your custom template from a NuGet package on any NuGet feed, by referencing a NuGet *nupkg* file directly, or by specifying a file system directory that contains the template. The template engine offers features that allow you to replace values, include and exclude files and regions of files, and execute custom processing operations when your template is used. | ||
|
|
||
| The template engine is open source, and the online code repository is at [dotnet/templating](https://github.com/dotnet/templating/) on GitHub. You can open an issue if you run into a problem or start a discussion for a new feature, possibly a feature that you contribute. Visit the [dotnet/dotnet-template-samples](https://github.com/dotnet/dotnet-template-samples) repo for samples of templates. More templates, including templates from third parties, are found at [Available templates for dotnet new](https://github.com/dotnet/templating/wiki/Available-templates-for-dotnet-new) at GitHub. A detailed pre-release blog post that describes how to create and install custom templates written by [Sayed Ibrahim Hashimi](https://github.com/sayedihashimi) is at [How to create your own templates for dotnet new](https://blogs.msdn.microsoft.com/dotnet/2017/04/02/how-to-create-your-own-templates-for-dotnet-new/). |
There was a problem hiding this comment.
wouldn't go into details of opening issues here. Also, we don't typically call out blog post authors in the docs.
docs/core/tools/custom-templates.md
Outdated
|
|
||
| ### Source files and folders | ||
|
|
||
| The source files and folders are composed of whatever files and folders you want the template engine to use when the `dotnet new <TEMPLATE>` command is executed. The template engine is designed to use *runnable projects* as source code to produce projects. This has several benefits: |
There was a problem hiding this comment.
are composed? maybe includes?
and what if i want a non-runnable project as a source code like a config file or solution?
There was a problem hiding this comment.
what if i want a non-runnable project as a source code like a config file or solution
Described below; however, I'm going to flesh it out a bit and explicitly call out "solution file" as a possible source/output for a template.
docs/core/tools/custom-templates.md
Outdated
|
|
||
| ### template.json | ||
|
|
||
| The *template.json* file is placed in a *.template.config* folder in the root directory of the template. The file provides configuration to the template engine when creating output from the source files and folders. The minimum configuration requires the members shown in the following table, which is sufficient to add to a .NET Core app to produce a functional template. |
There was a problem hiding this comment.
provides configuration -> provides configuration information
when creating output from the source files and folders -> is this necessary?
|
@mairaw Ready for another 👀 look. |
|
|
||
| Users install your custom template from a NuGet package on any NuGet feed, by referencing a NuGet *nupkg* file directly, or by specifying a file system directory that contains the template. The template engine offers features that allow you to replace values, include and exclude files and regions of files, and execute custom processing operations when your template is used. | ||
|
|
||
| The template engine is open source, and the online code repository is at [dotnet/templating](https://github.com/dotnet/templating/) on GitHub. Visit the [dotnet/dotnet-template-samples](https://github.com/dotnet/dotnet-template-samples) repo for samples of templates. More templates, including templates from third parties, are found at [Available templates for dotnet new](https://github.com/dotnet/templating/wiki/Available-templates-for-dotnet-new) on GitHub. A detailed pre-release blog post that describes how to create and install custom templates is at [How to create your own templates for dotnet new](https://blogs.msdn.microsoft.com/dotnet/2017/04/02/how-to-create-your-own-templates-for-dotnet-new/). |
There was a problem hiding this comment.
A detailed pre-release blog post that describes how to create and install custom templates is at How to create your own templates for dotnet new.
What makes the blog post useful to me if I'm already reading this docs article about how to create templates? Maybe you should mention why I should read the blog post (instead of continuing reading this article), or remove the link altogether?
There was a problem hiding this comment.
Yes, you're correct: We decided in a short offline chat (I'll add a note to the issue) that we need to keep the blog post linked here for two reasons:
- For the first pass on fully covering templates, we're covering the utter basics of template creation and usage and not adding a tutorial/walk-through to go with this reference topic. I did one thing that helps a dev trying to create a basic template: I kept the example "Garcia Software Console" template in use throughout the topic. This topic is really only going to get us started. We need a real tutorial, and I'll open an issue after we get this merged to discuss this aspect further.
- The first version of this topic won't cover all of the features of template design, so we'll need to expand the coverage. Where and how to cover the finer details for features such as replaceable parameter values, optional content, parameter options, custom processing, etc. is TBD. When I open the issue later, let's discuss how to best layout the coverage.
We'll probably end up with two issues: one saying we need a tutorial and a second saying we need to cover additional features of template design and how to lay that topic (or topics) out.
What I'll do here is just instruct the reader to access the blog post and Wiki for additional info after they've read this topic. (Let's take a 1st look at some draft language on the next commit, and then we can modify as needed.) As the reader gets down into the topic, they have linked access to the template.json schema. When the features of templates are fully in place in the docs, then yes, I think we should drop the blog post entirely.
|
|
||
| ## Packing a template into a NuGet package | ||
|
|
||
| Currently, a custom template is packed with [nuget.exe](https://dist.nuget.org/win-x86-commandline/latest/nuget.exe) (not [dotnet pack](dotnet-pack.md)). |
There was a problem hiding this comment.
Does this mean I can't pack a custom template on Unix? Is that worth mentioning?
There was a problem hiding this comment.
Good question. I just looked at the issues for Mono: https://github.com/NuGet/Home/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+mono
... so ... I guess as long as none of those would result in a big 💥 it should work. Before we state anything, let's ping @sayedihashimi to see if he knows.
There was a problem hiding this comment.
For xplat I'm hearing that NuGetizer is the way to go, see dotnet/dotnet-template-samples#16 (comment)
|
|
||
| Currently, a custom template is packed with [nuget.exe](https://dist.nuget.org/win-x86-commandline/latest/nuget.exe) (not [dotnet pack](dotnet-pack.md)). | ||
|
|
||
| The contents of the project folder, together with its *.template.config\template.json* file, is placed into a folder named *content*. Next to the *content* folder, add a [*nuspec* file](https://docs.microsoft.com/nuget/create-packages/creating-a-package), which is an XML manifest file that describes a package's contents and drives the process of creating the NuGet package. |
There was a problem hiding this comment.
Shouldn't it be "The contents […] are placed"?
| **Example** | ||
|
|
||
| ```console | ||
| nuget pack C:\Users\<USER>\Documents\Templates\GarciaSoftware.ConsoleTemplate.CSharp\GarciaSoftware.ConsoleTemplate.CSharp.nuspec |
There was a problem hiding this comment.
Is there a reason to use absolute path here? Wouldn't just nuget pack GarciaSoftware.ConsoleTemplate.CSharp.nuspec be better? Or maybe use a shorter, relative path, like nuget pack Templates/GarciaSoftware.ConsoleTemplate.CSharp/GarciaSoftware.ConsoleTemplate.CSharp.nuspec, which can be also used in later examples?
There was a problem hiding this comment.
Not knowing where they are, I feel a bit safer with a full path. This is part of that "weak tutorial" idea that I had for this topic, where you see I've placed examples to show how a basic template works. Since it isn't a tutorial, I'm less concerned about their working directory when they try to run the command. Of course, they must change it a little to make it work.
| **Example** | ||
|
|
||
| ```console | ||
| dotnet new -i C:/Users/Garcia/GarciaSoftware.ConsoleTemplate.CSharp.1.0.0.nupkg |
There was a problem hiding this comment.
This example uses slashes and explicitly names the user (C:/Users/Garcia). The example above uses backslahes and user name placeholder (C:\Users\<USER>). If you're going to keep these absolute paths, I think they should at least be consistent.
|
@guardrex for #965, we'll be adding a link to documentation describing installing templates when there's a parameter error (I believe for the 2.0 release yet), but that's about it. Is there something specific that you feel is blocking for this document referenced in there? I wouldn't cover installing the 1.x templates here as they also require the 1.x runtime to be installed - I think that would be better covered elsewhere as it's not tightly related to content creation/packaging/distribution. |
|
@mlorbetske I see. I couldn't tell if any major changes were expected in behavior or in help comments surrounding the template options, but you're saying 'no', so we're good. 👍 The only question then is whether or not I should add a few lines and a command to show how to install the 1.x templates? |
|
@guardrex I think the edit with my response to cover that was added as you were writing your reply :) I think the 1.x template install would be best covered separately, in a blog post about 1.x/2.0 SxS development (as it's not just the templates - multiple packs - that must be installed, but the runtime as well and the matter of different templates being available depending on the active CLI) |
|
@mlorbetske Cool. Outside of reviewer feedback, I just need to get the tutorial/walk-thru in place. It's coming along very well. Thanks for all of your help. |
|
is this still WIP @guardrex? |
|
@mairaw Yes, very much so. I have to rip the tutorial/walk-thru bits out of what was going to be just the one topic to make two: a ref topic and a tutorial topic. I'll be finishing it up this weekend.. |
guardrex
changed the title
|
I need to make more changes to the dotnet new command. But for now, I've just added the two syntaxes and readded old options so I don't lose them. In a separate PR, I'll make the additional changes needed. |
Fixes #2405