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 ASP.NET Core Web API Project webapiprj [C#] JandaBox/WebApi JandaBox Console App consolebox [C#] JandaBox/Console JandaBox Console App Project consoleprj [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.

To upgarde JandaBox templates to the latest version use following commands:

dotnet new uninstall JandaBox dotnet new install JandaBox

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

Console Application Project

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

dotnet new consoleprj -n HelloWorld

This is project only, without solution files etc.

Web API

Create .NET8 web API from webapibox template.

dotnet new webapibox -n MyWebService

The template provides solution file and the API project.

Web API Project

Create .NET8 web API project only from webapiprj template.

dotnet new webapiprj -n MyWebService

This template provides project folder only.

Service Files

Add new service interface, implementation and extsions.

dotnet new servicebox -n DemoService --name-space 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 --name-space 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>(); } } }

You can do the same from the Visual Studio.

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 --gitversioin

  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