How to create .Net custom template using GitHub Packages Registry

3 minute read

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

Comments