C# | Create .Net custom template using GitHub Packages Registry

Note
You can check other posts on my personal website: https://hbolajraf.net

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
• 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/hbolajraf/index.json --name github-hbolajraf --username hbolajraf --password <Your personal Access Token>

• You will see a source is added in C:\Users\hbolajraf\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": "hbolajraf 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 .

console

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>hbolajraf.CleanArchitecture.Templates</PackageId>     
        <Title>Clean Architecture Template</Title>     
        <Authors>hbolajraf 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/hbolajraf/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 hbolajraf.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 hbolajraf.CleanArchitecture.Templates.1.0.0.nupkg is exists.

• Type the following command to push the package in github package registry

  dotnet nuget push .\hbolajraf.CleanArchitecture.Templates.1.0.0.nupkg --api-key --source github-hbolajraf

• Here, “github-hbolajraf” 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  hbolajraf.CleanArchitecture.Templates

hbolajraf.CleanArchitecture.Templates is package Id.

output:

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

Success: hbolajraf.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 hbolajraf.CleanArchitecture.Templates
dotnet new –uninstall <package id>