JandaBox 0.8.0

JandaBox

Out of the box .NET8 templates

• Console App with dependency injection, logging, configuration, GitVersion and CommandLineParser.
• ASP.NET Core Web API with Serilog, AutoMapper and GitVersion
• NuGet ready Class Library with with GitHub Actions and GitVersion.
• Service files: a service interface, an implementation, and an extension class.

Template Name                            Short Name  Language  Tags
---------------------------------------  ----------  --------  ----------------
JandaBox ASP.NET Core Web API            webapibox   [C#]      JandaBox/WebApi
JandaBox Console App                     consolebox  [C#]      JandaBox/Console
JandaBox NuGet Class Library             nugetbox    [C#]      JandaBox/NuGet
JandaBox Service Classes and Extensions  servicebox  [C#]      JandaBox/Service

Learn more about templates in the wiki pages.

Quick Start

To install JandaBox templates use dotnet command.

dotnet new install JandaBox

You are now ready to use the templates from command line or from Visual Studio.

Console Application

Create .NET8 console application with dependency injection, Serilog and configuration.

dotnet new consolebox -n HelloWorld

HelloWorld basic console app using command line interface

Web API

Create .NET8 web API from webapibox template.

dotnet new webapibox -n MyWebService

Service Files

Add new service interface, implementation and extsions.

dotnet new servicebox -n DemoService --nameSpace MyApp.Services --logger

Add a new service tutorial

This tutorial demonstrates how to add simple service to the console application created with JandaBox.

Create demo console application.

C:\Demo>dotnet new consolebox
The template "JandaBox Console App" was created successfully.

Go to the source folder and create Services directory.

C:\Demo>cd src\Demo
C:\Demo\src\Demo>mkdir Services
C:\Demo\src\Demo>cd Services
C:\Demo\src\Demo\Services

Add demo service

dotnet new servicebox -n DemoService --nameSpace Demo.Services --logger
The template "JandaBox Service Classes and Extensions" was created successfully.

The template provides following files:

IDemoService.cs

namespace Demo.Services
{
    public interface IDemoService
    {

    }
}

DemoService.cs

using Microsoft.Extensions.Logging;

namespace Demo.Services
{
    internal class DemoService : IDemoService
    {
        private readonly ILogger<DemoService> _logger;

        public DemoService(ILogger<DemoService> logger) 
        {
            _logger = logger;
        }
    }
}

DemoServiceExtensions.cs

using Microsoft.Extensions.DependencyInjection;

namespace Demo.Services
{
    public static class DemoServiceExtensions
    {
        public static IServiceCollection AddDemoService(this IServiceCollection services)
        {
            return services.AddTransient<IDemoService, DemoService>();
        }
    }
}

Class Library into NuGet tutorial

This tutorial demonstrates how to create a new library, push it to GitHub, and publish it on NuGet.org using the JandaBox nugetbox template. Additionally, this tutorial provides explanations on why and how to create PAT tokens and NuGet.org tokens.

Here's what we aim to accomplish:

1. The library will be named AnyoneDrive and will be available under the MIT license.
2. The package's author is Matt Janda.
3. Semantic versioning, as provided by GitVersion, will be used for versioning the library.
4. The package will be published on GitHub under the Jandini owner.
5. Automatic building and publishing of the package will be handled by GitHub actions.
6. The package will be published to a private GitHub packages registry for each branch and commit. This approach allows you to create NuGet packages and test them without the need to publish them to the public NuGet.org.
7. The package will be published to Nuget.org only after a tag is created.

Please note that you should replace Jandini and AnyoneDrive with your GitHub owner and your repository name, respectively.

Let's get started!

• Create a new EMPTY repository in GitHub.

  • Head over to GitHub's repository creation page.
  • Create a new repository, making sure not to add a README.md, .gitignore, or license file.
  • Your repository will have a home at https://github.com/Jandini/AnyoneDrive.git.

• Open your command line or terminal and run the following command to create a new project:

  dotnet new nugetbox -n AnyoneDrive --nuget --tagNugetOrg --license --authors "Matt Janda" --user Jandini --actions --gitVersion
  

  This command will create a new project named "AnyoneDrive". Once created, navigate to the folder and list its contents:

  cd AnyoneDrive
  dir
  

  The directory structure should resemble the following:

  06/10/2023  22:56    <DIR>          .github
  06/10/2023  22:56    <DIR>          src
  06/10/2023  22:56             6,001 .gitignore
  06/10/2023  22:56               241 GitVersion.yml
  06/10/2023  22:56             6,643 icon.png
  06/10/2023  22:56             1,067 LICENSE
  06/10/2023  22:56               476 README.md
  

• Add the project to GitHub repository.

  Initialize a local Git repository and simultaneously create a new branch:

  git init -b main
  

  Add the remote origin to the local repository:

  git remote add origin https://github.com/Jandini/AnyoneDrive.git
  

  Stage all the files before creating the first commit:

  git add .
  

  Create the initial commit:

  git commit -m "First commit"
  

  Push the new branch to the remote GitHub repository, using -u to set the upstream branch that doesn't exist yet in the remote repository:

  git push -u origin main
  

You've successfully created a new project and made it available on GitHub. To view your repository, visit https://github.com/Jandini/AnyoneDrive

The GitHub Actions have started executing the "Build" action, which is currently failing as expected. To investigate further, go to GitHub Actions by navigating to https://github.com/Jandini/AnyoneDrive/actions and check the build details to understand why it's failing.

The build is failing at the "Setup" step, and you'll see the following error message:

Error: The NUGET_AUTH_TOKEN environment variable was not provided. In this step, add the following: 
env:
  NUGET_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}

The NUGET_AUTH_TOKEN is an environment variable used in the context of the NuGet package manager, which is a package manager for .NET development. NuGet is used to manage and distribute libraries, frameworks, and tools for .NET applications.

This error occurs because the Setup step is attempting to configure dotnet to have access (source-url) to your private GitHub NuGet registry. You can find this configuration in your GitHub Actions workflow file at https://github.com/Jandini/AnyoneDrive/blob/main/.github/workflows/build.yml#L28:

- name: Setup
  uses: actions/setup-dotnet@v1
  with:
    dotnet-version: 7.0.x
    source-url: https://nuget.pkg.github.com/${{ github.repository_owner }}/index.json

To resolve this issue, you should NOT follow the error's recommendation and use NUGET_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}. The GITHUB_TOKEN has read access only to your private GitHub NuGet registry, which will enable the Setup stage to proceed successfully.

However, the "Push" step will fail due to insufficient permissions with the provided GITHUB_TOKEN.

- name: Push
  # Push packages into private github repository 
  if: github.ref == 'refs/heads/main'
  run: dotnet nuget push "../bin/Release/*.nupkg" -k ${{ secrets.PACKAGE_REGISTRY_TOKEN }} -s https://nuget.pkg.github.com/${{ github.repository_owner }}/index.json --skip-duplicate

In the workflow file (build.yml), the definition of NUGET_AUTH_TOKEN assigns the PACKAGE_REGISTRY_TOKEN secret string as follows:

env:
    NUGET_AUTH_TOKEN: ${{ secrets.PACKAGE_REGISTRY_TOKEN }}

The build is currently failing because your repository does not have the secret string that contains the Personal Access Token (PAT) required for successful execution.

Now, let's create a Personal Access Token (PAT) and add it to the secrets of your GitHub repository:

1. Generate a PAT:

   • Go to your User Profile > Settings > Developer settings > Personal access tokens. Alternatively, you can follow this link: GitHub Token Settings.
   • Click on Generate new token (classic) and authenticate your user.
   • In the Note field, enter a name for your token (it can be anything you prefer).
   • Set the Expiration time according to your preference.
   • Select the following scopes:
     • write:packages - Allows you to upload packages to GitHub Package Registry.
     • read:packages - Enables downloading packages from GitHub Package Registry.
   • Click Generate Token.

   Be sure to copy the generated token and keep it in a secure place. This token can be used in multiple repositories.

2. Add the Token to Repository Secrets:

   • Navigate to your AnyoneDrive repository on GitHub.
   • Go to Settings > Secrets and variables > Actions. You can access it directly via this link: Repository Secrets.
   • Click on New repository secret.
   • Set the Name to PACKAGE_REGISTRY_TOKEN, matching what's declared in your build.yml.
   • Paste the PAT token you obtained earlier into the Secret text box.

Now, the secret PACKAGE_REGISTRY_TOKEN is securely stored within your GitHub repository. Please note that you can update an existing secret if your PAT token expires. However, you won't be able to view the current value for security reasons.

Return to GitHub Actions and re-run any previously failed jobs. You should now have a successful build, and the first NuGet package will be available in your GitHub private NuGet registry.

Resources

• Box icon was downloaded from Flaticon
• https://learn.microsoft.com/en-us/dotnet/core/tools/custom-templates
• https://github.com/dotnet/templating/wiki