Skip to content

README-template.md

Latest commit

 

History

History
267 lines (185 loc) · 7.51 KB

README-template.md

File metadata and controls

267 lines (185 loc) · 7.51 KB

bITdevKit Templates

This repository contains custom .NET templates based on bITdevKit (bIT DevKit) that follows the Onion Architecture principles. These templates help you quickly scaffold new solutions and modules following this architecture approach.

Templates Overview

1. DevKit Solution Template (bdksolution)

The solution template creates a complete solution structure with an initial module. It sets up the foundation for your application following Onion Architecture principles.

2. DevKit Module Template (bdkmodule)

The module template helps you add new functional modules to your solution. Each module is structured following the Onion Architecture pattern with separate projects for different concerns.

Each module contains the following projects:

  • [ModuleName].Application.csproj
  • [ModuleName].Domain.csproj
  • [ModuleName].Infrastructure.csproj
  • [ModuleName].Presentation.csproj
  • [ModuleName].IntegrationTests.csproj
  • [ModuleName].UnitTests.csproj

Installation

Prerequisites

  • .NET 9 SDK or later

Install the Templates

To install the templates from NuGet.org:

dotnet new install BridgingIT.DevKit.Templates

Verify Installation

After installation, verify the templates are available:

dotnet new list

You should see:

bITdevKit Solution  bdksolution  [C#]     Solution
bITdevKit Module    bdkmodule    [C#]     Module

Update Templates

To update to the latest version:

# Uninstall current version
dotnet new uninstall BridgingIT.DevKit.Templates

# Install latest version
dotnet new install BridgingIT.DevKit.Templates

Creating a New Solution

To create a new solution with an initial module:

dotnet new devkitsolution --SolutionName SolutionName --ModuleName Core --allow-scripts yes -o ./projects/SolutionName

Parameters:

  • --SolutionName: The name of your solution (default: DevKit.Examples.GettingStarted)
  • --ModuleName: The name of the initial module (default: Core)
  • -o: Output directory for the solution

Adding a New Module

To add a new module to an existing solution:

cd ./projects/SolutionName
dotnet new bdkmodule --ModuleName ModuleName -o src/Modules/ModuleName --allow-scripts yes

Parameters:

  • --ModuleName: The name of the new module
  • -o: Output directory for the module

After adding a new module, the template will automatically add the generated projects to your solution file.

Importannt: Some manual adjustments are required after adding a new module. Otherwise the new module will not be fully setup. Please follow the steps below.

  • src\Presentation.Web.Server\Program.cs: Register the new module in the service configuration:
// ===============================================================================================
// Configure the modules
builder.Services.AddModules(builder.Configuration, builder.Environment)
    // ...
    .WithModule<[ModuleName]Module>()  // add this manually
    // ...
  • src\Presentation.Web.Server\appsettings.json: Add configuration section for the new module:
  // ...
  "Modules": {
    // ...
    "[ModuleName]": {  // add this manually
      "Enabled": true,
      "ConnectionStrings": {
        "Default": "ConnectionStringHere"
      }
    }
  }

Project Structure

The template creates a solution following Onion Architecture principles with the test projects included within the same directory as their corresponding implementation projects:

SolutionName/
├── src/
│   ├── Modules/
│   │   ├── ModuleName/
│   │   │   ├── ModuleName.Application/
│   │   │   ├── ModuleName.Domain/
│   │   │   ├── ModuleName.Infrastructure/
│   │   │   └── ModuleName.UnitTestPresentations/
│   └── Presentation.Web.Server/
├── tests/
│       └── ModuleName/
│           ├── ModuleName.IntegrationTests/
│           └── ModuleName.UnitTests/
└── SolutionName.slnx

Available Templates

Template Name Short Name Description
bITdevKit Solution bdksolution Creates a complete solution with initial module following Onion Architecture
bITdevKit Module bdkmodule Adds a new module to an existing solution

Troubleshooting

If you encounter any issues with the templates:

Template Installation Issues

  1. Templates not found after installation:

    # Check if templates are installed
dotnet new list

# If not found, try reinstalling
dotnet new install BridgingIT.DevKit.Templates --force

  2. Permission errors during installation:

    # On Linux/Mac, you might need sudo for global installation
sudo dotnet new install BridgingIT.DevKit.Templates

  3. Outdated templates:

    # Uninstall and reinstall to get latest version
dotnet new uninstall BridgingIT.DevKit.Templates
dotnet new install BridgingIT.DevKit.Templates

Project Creation Issues

  1. Missing .NET SDK:

    • Make sure you have .NET 9 SDK or later installed
    • Verify with: dotnet --version

  2. Projects not added to solution automatically:

    # Add projects manually to solution
dotnet sln YourSolution.sln add src/Modules/ModuleName/*.csproj

  3. Template parameters not working:

    # Check available parameters for a template
dotnet new bdksolution --help
dotnet new bdkmodule --help

NuGet Package Issues

  1. Package not found:

    • Ensure you have internet connection
    • Check NuGet.org is accessible
    • Try clearing NuGet cache: dotnet nuget locals all --clear

  2. Version conflicts:

    # Install specific version if needed
dotnet new install BridgingIT.DevKit.Templates::1.0.1-preview

Uninstalling Templates

To uninstall the templates:

dotnet new uninstall BridgingIT.DevKit.Templates

Development and Local Testing

For developers who want to test templates locally from source:

# Clone the repository
git clone https://github.com/bridgingIT/bIT.devkit-examples-gettingstarted.git
cd bIT.bITdevKit.GettingStarted

# Reinstall templates from local source
dotnet new uninstall . | dotnet new install .

# Test template creation
dotnet new bdksolution --SolutionName TestSolution --ModuleName Core -o ../TestSolution --allow-scripts yes
cd ../TestSolution
dotnet new bdkmodule --ModuleName Administration -o src/Modules/Administration --allow-scripts yes

Custom Modifications

You can customize these templates by modifying the template configuration files:

  • Solution template: .template.config/template.json in the solution template directory
  • Module template: src/Modules/CoreModule/.template.config/template.json in the module template directory
  • Post template scripts: .bdk/template/post-action-*.ps1

For more information about .NET template development:

Support and Issues

License

This project is licensed under the MIT License - see the LICENSE file for details.