Visual Studio Item Templates vs .NET Templates in 2023

Long ago, one of the ways we'd get some reuse out of standard and utility files would be by exporting item templates. Since the .NET CLI rolled around, the approach has been different and much easier.
.editorconfig .NET .NET CLI dotnet dotnet new git NuGet nuget.org
đź“… 29 Oct 2023

Exporting Item Templates in Visual Studio

Let's start by looking at what the process looked like to export an Item Project template in Visual Studio.

In Visual Studio, go to Project | Export Template...
Figure: In Visual Studio, go to Project | Export Template...

Next, a dialog will come up asking you some info like which file you want to export, which references are essential for the item to work as expected, and some metadata for the item template

The Export Template Wizzard will guide you through the information needed to create the Item Project template
Figure: The Export Template Wizzard will guide you through the information needed to create the Item Project template

Windows Explorer will open showing you the file
Figure: Windows Explorer will open showing you the file

⚠️ WARNING: Make sure you backup this file to use on other machines or share it with your friends

Reusing this file is simple. All you need to do is copy the file into the My Exported Templates folder (you will need to create this folder if it does not exist) on another computer.


Pros and Cons

Let's look at the pros and cons of exporting item templates in Visual Studio

âś… Quick and easy
âś… Private by default
âś… Item Templates show in the Visual Studio Project | New Item dialog
❌ Only one file per item template
❌ Manually backed up and shared
❌ Updates require more manual effort
⚠️ Requires restarting Visual Studio to use

So, let's look at the modern alternative to using Item Templates

Creating config for a dotnet new template

So, this approach takes a little more effort but has many benefits over creating an item template.

How does it work

dotnet new templates are installed from nuget package feeds. This could be the default public feed https://www.nuget.org/, which is typical for community/open source templates and is where the dotnet new install command will look for packages if not informed to look elsewhere using the --add-source argument. This post will create a package for the public feed and will be available to anyone who tries to install it

Creating the nuget package

There are a couple of files that we'll need to create in a folder. I've published this sample to GordonBeeming/DefaultCSharpRepoFiles on GitHub if you want to browse the source. We start with the following structure.

root
└───.template.config
    └───template.json
    └───icon.png
└───DefaultCSharpRepoFiles.nuspec
└───README.md

This icon is used to represent the nuget package once we publish it
Figure: This icon is used to represent the nuget package once we publish it

The text files have this content in them




        


  
Figure: .template.config/template.json - This is the configuration file that informs the .NET CLI what our template is and what it does



        




        


  
Figure: DefaultCSharpRepoFiles.nuspec - This file contains all the files that will be placed on the page that is published to nuget.org



        




        


  
Figure: README.md - This file contains information that is shown on the repository on GitHub and the package page on nuget.org



        


  
I won't dive into all the configurations inside all the files. You can read up on all the config and the process in more detail at Create an item template for dotnet new - .NET CLI | Microsoft Learn. 


Once you have all these files, you can add any other files you want to include in the template once installed. I've included the following files for now in my template


- .editorconfig
- .gitattributes
- .gitignore


Run the below to pack the nuget package so it can be uploaded to nuget.org



        




        


  
and this will create a nupkg file (note you need a copy of nuget.exe globally to just pack directly like this)



        
Once uploaded you will see all the information for the package, click Submit
  

  Figure: Once uploaded you will see all the information for the package, click Submit


            

        
After clicking Submit, you will see that the page is uploaded with couple of warnings informing you that the page will take a bit to validate and index
  

  Figure: After clicking Submit, you will see that the page is uploaded with couple of warnings informing you that the page will take a bit to validate and index


        


  
Once the validation and indexing process is completed, you can install the template and use it using the commands below



        




        


  
The dotnet new install command will install the latest template and update it if there is a newer version.


To check for updates without installing you can run 



        




        


  
If there are any updates, you will give get a response like the one below using dotnet new update, you can update all templates at once



        




        


  
Pros and Cons


Let's look at the pros and cons of creating a .NET template


âś… Easy to share with friends
âś… Easy to version control changes
âś… Easy to automatically package updates (check out next week's blog post for how we'd do this)
âś… Flexibility - You can include any number of files in the template, from in and out of the solution
❌ Public by default (not ideal for enterprises - maybe I'll add a post on changing this)
❌ A more advanced approach, requiring a lot more work than creating an Item template


Conclusion


The newer, preferred approach to creating item-type templates has changed significantly but has many advantages over the previous item-based templates. There is tons of documentation on how dotnet templates work and how you can customize them


If you want to see how to automate the publish to nuget.org, take a look at the next post Deploying .NET templates using GitHub Actions - Gordon Beeming