How to create .Net custom template using GitHub Packages Registry

Introduction

.NET gives us opportunity to create custom template for future use and GitHub packages registry is most popular now a days to host custom template. In this article, I will show you how to create .net custom template using GitHub packages registry.

Tools and Technology uses

• Visual Studio 2022
• .NET 6
• Visual C#
• GitHub

Implementation

Step 1: Create a personal access token (PAT) from GitHub

• Login into you GitHub
• Go to settings -> Developer Settings -> Personal Access Tokens
• Click “Generate new token” button
• Type Note for the token, expiration days
• Select scope for the token – here I have selected repo, write:packages, delete:packages as shown below.

• Now click “Generate Token” at the bottom of the panel
• Copy the token and store the token for further use because you cannot find it later

Step – 2: Add Nuget Source in visual studio

• Type the following command to add source

dotnet nuget add source https://nuget.pkg.github.com/mahedee/index.json --name github-mahedee --username mahedee --password <Your personal Access Token>

• You will see a source is added in C:\Users\mahedee\AppData\Roaming\NuGet\NuGet.Config file

• You can add source from visual studio Tools -> Options -> NuGet Package Manager -> Package Sources
• Restart visual studio to get new nuget package source

Step – 3: Create template for your application

• Create a project or multiple projects using a solution file.
• Here, I have created a clean architecture template with a solution file and multiple projects
• Create a folder name – “.template.config” in the root directory of your application.

• Create a file template.json in .template.config folder.
• Add the following content to template.json file

template.json

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Mahedee Hasan",
  "classifications": [
    "dotnet",
    "CleanArchitecture"
  ],
  "name": "Clean Architecture project template",
  "description": "Project template to create project using Clean Architecture",
  "identity": "CleanArchitecture",
  "shortName": "CleanArchitecture",
  "sourceName": "CleanArch",
  "tags": {
    "language": "C#",
    "type": "project"
  },
  "symbols": {
    "Framework": {
      "type": "parameter",
      "description": "The target framework for the project.",
      "datatype": "choice",
      "choices": [
        {
          "choice": "net6.0"
        },
        {
          "choice": "net5.0"
      }
      ],
      "defaultValue": "net6.0",
      "replaces": "{TargetFramework}"
    }
  }
}

Step -4: Install and create template locally (Optional)

• Go to one where “.template.config” folder exists.
• Now run the following command. Don’t forgot to add space “.” at the end.

dotnet new --install .

• You will see in the output that template is created. You will see Short Name of template which is used to install template.
• Now go to the directory where you want to install template and type the following command.

dotnet new CleanArchitecture
or,
dotnet new CleanArchitecture --force

Here CleanArchitecture is short name of the template

• To create template by another name type as follows.

dotnet new CleanArchitecture -o Location

Now projects name will be Location instead of CleanArch as mentioned in the previous json file.

• Now go to the same directory to uninstall the template and type the following command.

dotnet new --uninstall .

Step - 5: Packing a template into a NuGet Package (nupkg file)

• Create a .csproj file one directory up of “.template.config” folder.

• In my case the folder structure as follows

  

Add the following content in TemplatePack.csproj project.

TemplatePack.csproj

<Project Sdk="Microsoft.NET.Sdk"> 

  <PropertyGroup> 

    <PackageType>Template</PackageType> 

    <PackageVersion>1.0.0</PackageVersion> 

    <PackageId>Mahedee.CleanArchitecture.Templates</PackageId> 

    <Title>Clean Architecture Template</Title> 

    <Authors>Mahedee Hasan</Authors> 

    <Description>Clean Architecture Template</Description> 

    <PackageTags>dotnet-new;templates;clean-architecture</PackageTags> 

    <TargetFramework>netstandard2.0</TargetFramework> 

    <IncludeContentInPack>true</IncludeContentInPack> 

    <IncludeBuildOutput>false</IncludeBuildOutput> 

    <ContentTargetFolders>content</ContentTargetFolders> 

    <NoWarn>$(NoWarn);NU5128</NoWarn> 

    <NoDefaultExcludes>true</NoDefaultExcludes> 
    <RepositoryUrl>https://github.com/mahedee/public-packages</RepositoryUrl>

  </PropertyGroup> 

  <ItemGroup> 
    <Content Include="CleanArchitecture\**\*" Exclude="CleanArchitecture\**\bin\**;CleanArchitecture\**\obj\**" /> 
    <Compile Remove="..\**\*" /> 

  </ItemGroup> 

 

</Project> 

• To create package go to the directory where TemplatePack.csproj file exists and type the following command.

dotnet pack

• You will Mahedee.CleanArchitecture.Templates.1.0.0.nupkg file is created in bin/Debug folder.

Step 6: Now push the package to github package registry

• Go to the directory where Mahedee.CleanArchitecture.Templates.1.0.0.nupkg is exists.
• Type the following command to push the package in github package registry

dotnet nuget push .\Mahedee.CleanArchitecture.Templates.1.0.0.nupkg --api-key <Your personal access token> --source github-mahedee

• Here, “github-mahedee” is a github source which we have added in step – 2.
• Now login your github and you will see a template is uploaded to your package registry.

Step 7: Download template and install in local machine

• Run the following command to install in local machine

dotnet new --install  Mahedee.CleanArchitecture.Templates

Mahedee.CleanArchitecture.Templates is package Id.

output:

The following template packages will be installed:
   Mahedee.CleanArchitecture.Templates

Success: Mahedee.CleanArchitecture.Templates::1.0.0 installed the following templates:
Template Name                        Short Name         Language  Tags
-----------------------------------  -----------------  --------  ------------------------
Clean Architecture project template  CleanArchitecture  [C#]      dotnet/CleanArchitecture

• Now go to the directory where you want to regenerate the template and type the following command.

dotnet new CleanArchitecture

Here CleanArchitecture is the short name of the template

Note

• To see installed template in locally use the following command. You will also see how to uninstall the particular template.

dotnet new --uninstall

• To uninstall a particular template from local machine, use the following command.

dotnet new --uninstall Mahedee.CleanArchitecture.Templates
dotnet new –uninstall <package id> 

Source code