The Template Creator extension provides a way to create a project template from an existing project or solution open in Visual Studio for Mac and have the project template available in the New Project dialog straight away.
The Template Creator uses the .NET Core templating engine to create the projects from the project templates.
Let us take a look in more detail at what the Template Creator extension provides in Visual Studio for Mac.
Features
- Create a project template from an existing solution or project
- Create custom top level project template categories
Supports
- Visual Studio Mac 7.0 or later.
Creating a new Project Template
To create a new project template for a project opened in Visual Studio for Mac, right click the project and select Create Template.
A Template Information dialog is then opened.
The information in the dialog is used to populate the generated template.json file. Further details on what the template.json file holds is available in the reference for template.json.
- Author
- Author of the project template.
- Display Name
- This is the template name displayed in the New Project dialog.
- Description
- This is the description displayed in the New Project dialog.
- Category
- This is the category in the New Project dialog used by the template.
- Short Name
- This is the short name for the template that can be used from the .NET Core command line.
- Default Project Name
- This is the default project name that will be used with the .NET Core command line.
- Identity
- This is the unique id for the template. This should be unique across all custom project templates.
- Group Identity
- This is typically a substring of the template’s Identity.
By default the project template will use the Other – .NET – General category in the New Project dialog. To change the category click the browse button next to the category text box to open the Template Categories dialog.
Select the required category and click OK. The selected category will then be updated in the Template Information dialog.
Click OK to generate the template.json file. The template.json file will be opened in the text editor. It will also be displayed in the Solution window in the .template.config folder.
The project template is now available in the New Project dialog.
Updating a Project Template
After the project template is created you can modify the original project and its template.json file as required.
Changes made to the project are available in the New Project dialog immediately.
Changes made to the template.json file are available immediately in the same instance of Visual Studio for Mac where the template.json file is being edited.
Multiple Projects in a Template
A project template may create more than one project. To create a project template for all projects in the solution right click the solution and select Create Template.
A template.json file will be created in a .template.config directory inside the solution’s directory.
Note that in order for the new projects created to use the name specified in the New Project
dialog they should all have a common start to their name. The template.json file’s sourceName
will be the part that is replaced with the name of the project specified in the New Project dialog.
Configuring Registered Project Templates
The .NET Core templating engine supports project templates in NuGet packages or project templates that unpackaged in a directory. The Template Creator extension does not package the project templates into a NuGet package and instead stores a set of directories that are scanned by the .NET Core templating engine for templates. The set of directories that are registered can be viewed and updated in the Preferences dialog from the Templates – Custom Folders section.
The templating engine will scan the configured directories and look for all the template.json files which define the project templates. The project templates found are then made available to the Visual Studio for Mac’s New Project dialog by the Template Creator extension.
When the template.json file is created using the information in the Template Information dialog the Template Creator extenxion also registers the project’s directory so it will be scanned by the templating engine.
To remove a project template from the New Project dialog you can either delete the template.json file or remove the folder from the Custom Folders defined in the Preferences dialog.
If you have an existing set of project templates that use template.json files and are not in a NuGet package then you can register a single parent directory in the Preferences dialog.
Custom Categories
Custom top level categories can be defined for your project templates by adding them in Preferences – Templates – Custom Categories.
The Add Top Level Category button will add a new top level category and two child category
levels. The New Project dialog requires three category levels. The ids used should ensure that
the full path to the template’s category is unique. For example, with a custom category
custom/net/general there should not be another top level custom category id, but the second
and third level category ids can be re-used in another top level category, such as top/net/general.
The Add Category button will add a single child category to the currently selected category whilst the Remove button will remove the selected category.
Note that changes to the categories require Visual Studio for Mac to be restarted before they are visible in the New Project dialog.
Also note that it is not currently possible to extend existing project template categories using the Template Creator extension.
Diagnosing Template Problems
If the template does not appear in the New Project dialog or fails to be created then you may be able to diagnose the problem by opening the Templating Log window. This is available from the View – Pads menu.
This window will show messages returned from the .NET Core templating engine and any errors reported by the Template Creator extension.
Installation
The Template Creator extension is available to download from GitHub.
To install the extension open the Extensions Manager by selecting Extensions… from the main menu. Click the Install from file button. Select the .mpack file and then click the Open button.
The extension is also available in the Extensions Manager from the Visual Studio Extension Repository (Beta channel).