Post

C# | 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
  • 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
1
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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
    {
      "$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.
1
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.
1
2
3
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.
1
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
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
    
    ![](/posts/2022/temp-04.PNG)
    

**Add the following content in TemplatePack.csproj project.**

**TemplatePack.csproj**

```xml     
    <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.
1
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
1
dotnet new --install  hbolajraf.CleanArchitecture.Templates

hbolajraf.CleanArchitecture.Templates is package Id.

output:

1
2
3
4
5
6
7
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.
1
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.
1
dotnet new --uninstall
  • To uninstall a particular template from local machine, use the following command.
1
2
dotnet new --uninstall hbolajraf.CleanArchitecture.Templates
dotnet new –uninstall <package id> 

Source code

This post is licensed under CC BY 4.0 by the author.